Elasticsearch Instance Network Management#

A skill for managing Alibaba Cloud Elasticsearch instance network configurations, including network triggering, Kibana PVL network, white IP list, HTTPS settings, and Kibana SSO authentication.

Architecture#

text

Alibaba Cloud Account → Elasticsearch Service → ES Instance(s) → Network Configuration
                                                        ├── Public Network Access
                                                        ├── Kibana PVL Network
                                                        ├── White IP List
                                                        ├── HTTPS Settings
                                                        └── Kibana SSO Authentication

---

Installation#

Pre-check: Aliyun CLI >= 3.3.3 required Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update, or see references/cli-installation-guide.md for installation instructions.

[MUST] AI-Mode Configuration

Before executing any CLI commands, enable AI-Mode and set User-Agent. After the workflow completes, disable AI-Mode.

bash

# Step 1: Enable AI-Mode (before CLI operations)
aliyun configure ai-mode enable

# Step 2: Set User-Agent for traceability
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage"

After all CLI operations are complete:

bash

# Step 3: Disable AI-Mode (after workflow ends)
aliyun configure ai-mode disable

[MUST] Plugin Update

bash

aliyun configure set --auto-plugin-install true
aliyun plugin update

[MUST] CLI Installation (if not already installed or version < 3.3.3):

bash

curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version

---

Environment Variables#

VariableRequiredDescriptionALIBABA_CLOUD_ACCESS_KEY_IDYesAlibaba Cloud AccessKey IDALIBABA_CLOUD_ACCESS_KEY_SECRETYesAlibaba Cloud AccessKey SecretALIBABA_CLOUD_REGION_IDNoDefault Region ID (e.g., cn-hangzhou)

---

CLI User-Agent Requirement#

[MUST] CLI User-Agent — The user-agent is set globally via aliyun configure ai-mode set-user-agent during installation. As a fallback, every aliyun CLI command invocation must also include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

Parameter Confirmation#

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, white IPs, VPC IDs, security groups, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Parameter NameRequired/OptionalDescriptionDefault ValueInstanceIdRequired (for all operations)Elasticsearch Instance ID-RegionIdOptionalRegion IDcn-hangzhounodeTypeRequired (TriggerNetwork)Instance Type: KIBANA/WORKER-networkTypeRequired (TriggerNetwork)Network Type: PUBLIC/PRIVATE-actionTypeRequired (TriggerNetwork)Action Type: OPEN/CLOSE-resourceGroupIdOptionalResource Group ID-whiteIpGroupRequired (ModifyWhiteIps)White IP Group Configuration-whiteIpTypeOptional (ModifyWhiteIps)White IP Type: PRIVATE_ES/PUBLIC_KIBANAPRIVATE_ES

---

Authentication#

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values
• NEVER ask user to input AK/SK in conversation or command line
• ONLY use aliyun configure list to check credential status

bash

aliyun configure list

If no valid credentials, guide user to run aliyun configure in terminal (never accept plaintext AK/SK in chat). Credential portal: Alibaba Cloud RAM Console

---

RAM Policy#

RAM permissions required for Elasticsearch instance network configuration operations. See references/ram-policies.md for details.

---

Core Workflow#

Prerequisite: Instance Status Check

Before executing any network configuration operation, verify that the instance status is active. Network configuration changes cannot be executed when instance status is activating, invalid, or inactive.

bash

# Check instance status with retry logic
max_retries=10
retry_count=0
while [ $retry_count -lt $max_retries ]; do
  status=$(aliyun elasticsearch describe-instance \
    --instance-id <InstanceId> \
    --read-timeout 30 \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.status')

  if [ "$status" == "active" ]; then
    echo "✅ Instance status is active, proceeding..."
    break
  else
    echo "⚠️ Instance status is $status, waiting 30s before retry..."
    sleep 30
    retry_count=$((retry_count + 1))
  fi
done

if [ $retry_count -eq $max_retries ]; then
  echo "❌ Instance did not become active after $max_retries retries, aborting"
  exit 1
fi

Task 1: Trigger Network (Enable/Disable Public/Private Network Access)#

Enable or disable public or private network access for Elasticsearch or Kibana clusters.

Scope: Supports all network types on basic management instances. On cloud-native instances, supports cluster public/private network and Kibana public network. For Kibana private network on cloud-native instances, use EnableKibanaPvlNetwork / DisableKibanaPvlNetwork instead.

Parameters:

ParameterTypeRequiredDescriptionnodeTypeStringYesInstance Type: KIBANA (Kibana cluster) / WORKER (Elasticsearch cluster)networkTypeStringYesNetwork Type: PUBLIC / PRIVATEactionTypeStringYesAction Type: OPEN (enable) / CLOSE (disable)bash

# Example: Enable Kibana public network access
aliyun elasticsearch trigger-network \
  --instance-id <InstanceId> --read-timeout 30 \
  --body '{"nodeType":"KIBANA","networkType":"PUBLIC","actionType":"OPEN"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

# Example: Disable Elasticsearch public network access
aliyun elasticsearch trigger-network \
  --instance-id <InstanceId> --read-timeout 30 \
  --body '{"nodeType":"WORKER","networkType":"PUBLIC","actionType":"CLOSE"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

Pre-check (Required):

Network Status Fields (via DescribeInstance):

• Result.enablePublic: ES public network (private network is always on, cannot be disabled)
• Result.enableKibanaPublicNetwork: Kibana public network
• Result.enableKibanaPrivateNetwork: Kibana private network

If the target network is already in the desired state, skip the TriggerNetwork call and inform the user.

bash

# Pre-check: architecture + current network status
instance_info=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage)

arch_type=$(echo "$instance_info" | jq -r '.Result.archType')

# Cloud-native Kibana private network: use EnableKibanaPvlNetwork/DisableKibanaPvlNetwork instead
if [ "$arch_type" == "public" ] && [ "$node_type" == "KIBANA" ] && [ "$network_type" == "PRIVATE" ]; then
  echo "❌ Use EnableKibanaPvlNetwork/DisableKibanaPvlNetwork for cloud-native Kibana private network"
  exit 1
fi

# Check if target network already in desired state
enable_public=$(echo "$instance_info" | jq -r '.Result.enablePublic')
enable_kibana_public=$(echo "$instance_info" | jq -r '.Result.enableKibanaPublicNetwork')
enable_kibana_private=$(echo "$instance_info" | jq -r '.Result.enableKibanaPrivateNetwork')

# Map nodeType+networkType to status field (ES private is always on)
# WORKER+PUBLIC -> enablePublic | KIBANA+PUBLIC -> enableKibanaPublicNetwork | KIBANA+PRIVATE -> enableKibanaPrivateNetwork
# If actionType=OPEN and already true, or actionType=CLOSE and already false, skip

---

Task 2: Enable Kibana PVL Network (Enable Kibana Private Network Access)#

Enable Kibana private network access (PrivateLink) for an Elasticsearch instance.

Prerequisites: Only supports cloud-native instances (archType=public), Kibana spec must be > 1 core 2GB. For basic management instances, use TriggerNetwork.

Request Parameters (Body):

ParameterTypeRequiredDescriptionendpointNameStringYesEndpoint name, recommended format: {InstanceId}-kibana-endpoint``securityGroupsArrayYesSecurity group ID arrayvSwitchIdsZoneArrayYesVSwitch and availability zone informationvSwitchIdsZone[].vswitchIdStringYesVirtual switch IDvSwitchIdsZone[].zoneIdStringYesAvailability zone IDvpcIdStringYesVPC instance ID

Pre-check: Call DescribeInstance first to check Result.enableKibanaPrivateNetwork. If already enabled, compare current config (vpcId, vswitchId, securityGroups) with user requirements. If they match, skip and inform user config is already correct.

bash

# Check current Kibana PVL status and config
instance_info=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage)

pvl_enabled=$(echo "$instance_info" | jq -r '.Result.enableKibanaPrivateNetwork')
current_vpc=$(echo "$instance_info" | jq -r '.Result.networkConfig.vpcId')
current_vswitch=$(echo "$instance_info" | jq -r '.Result.networkConfig.vswitchId')

if [ "$pvl_enabled" == "true" ]; then
  # Check if current config matches user requirements
  if [ "$current_vpc" == "<VpcId>" ] && [ "$current_vswitch" == "<VswitchId>" ]; then
    echo "✅ Kibana private network already enabled with matching config, no action needed"
    exit 0
  fi
fi

# Enable Kibana private network access
aliyun elasticsearch enable-kibana-pvl-network \
  --instance-id <InstanceId> \
  --body '{
    "endpointName": "<InstanceId>-kibana-endpoint",
    "securityGroups": ["<SecurityGroupId>"],
    "vSwitchIdsZone": [{"vswitchId": "<VswitchId>", "zoneId": "<ZoneId>"}],
    "vpcId": "<VpcId>"
  }' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

Task 3: Disable Kibana PVL Network (Disable Kibana Private Network Access)#

Disable Kibana private network access for an Elasticsearch instance.

Prerequisites: This API only supports cloud-native instances (archType=public). For basic management instances, use TriggerNetwork.

bash

aliyun elasticsearch disable-kibana-pvl-network \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

Task 4: Modify White IPs (Modify White IP List)#

Update the access white IP list for the specified instance. Two update methods are supported (cannot be used simultaneously):

1. IP White List Method: Use whiteIpList + nodeType + networkType
2. IP White Group Method: Use modifyMode + whiteIpGroup

Notes:

• Cannot update when instance status is activating, invalid, or inactive
• Public network white list does not support private IPs; private network white list does not support public IPs
• Kibana private network white list for cloud-native instances (archType=public) cannot be modified via this API. Use UpdateKibanaPvlNetwork API to modify security groups instead (see Task 7)

Method 1: IP White List (Update Default Group)

ParameterTypeRequiredDescriptionwhiteIpListArrayYesIP white list, will overwrite Default groupnodeTypeStringYesNode Type: WORKER (ES cluster) / KIBANAnetworkTypeStringYesNetwork Type: PUBLIC / PRIVATEbash

# Modify ES public network white list (overwrite Default group)
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> --read-timeout 30 \
  --body '{"nodeType":"WORKER","networkType":"PUBLIC","whiteIpList":["59.0.0.0/8","120.0.0.0/8"]}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

Method 2: IP White Group (Supports Incremental/Overwrite/Delete)

ParameterTypeRequiredDescriptionmodifyModeStringNoModify mode: Cover (overwrite, default) / Append / DeletewhiteIpGroup.groupNameStringYesWhite IP group namewhiteIpGroup.ipsArrayYesIP address listwhiteIpGroup.whiteIpTypeStringNoWhite IP type (see table below)

whiteIpType Values:

ValueDescriptionPRIVATE_ESElasticsearch private network white listPUBLIC_ESElasticsearch public network white listPRIVATE_KIBANAKibana private network white listPUBLIC_KIBANAKibana public network white listbash

# Overwrite specified white group (Cover mode)
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> --read-timeout 30 \
  --body '{"modifyMode":"Cover","whiteIpGroup":{"groupName":"default","ips":["59.0.0.0/8","120.0.0.0/8"],"whiteIpType":"PUBLIC_ES"}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

# Append IPs to white group (Append mode, group must exist)
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> --read-timeout 30 \
  --body '{"modifyMode":"Append","whiteIpGroup":{"groupName":"default","ips":["172.16.0.0/12"],"whiteIpType":"PRIVATE_ES"}}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

modifyMode Description:

ModeDescriptionCoverOverwrite mode (default). Empty ips deletes group; non-existent groupName creates newAppendAppend mode. Group must exist, otherwise NotFound errorDeleteDelete mode. Remove specified IPs, at least one IP must remain

IMPORTANT: modifyMode Selection Guidelines

• Use Append for incremental addition, Cover for full replacement, Delete for removal
• If user intent is unclear, MUST ask user which mode to use before executing
• If Append fails with NotFound: inform user, suggest Cover mode to create group. Do NOT silently switch modes.

---

Task 5: Open HTTPS (Enable HTTPS)#

Enable HTTPS access for an Elasticsearch instance.

Pre-check: Call DescribeInstance first to check Result.protocol. If already HTTPS, skip OpenHttps and inform user HTTPS is already enabled.

bash

# Check current HTTPS status
protocol=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.protocol')

if [ "$protocol" == "HTTPS" ]; then
  echo "✅ HTTPS is already enabled, no action needed"
else
  # Enable HTTPS
  aliyun elasticsearch open-https \
    --instance-id <InstanceId> \
    --read-timeout 30 \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage
fi

---

Task 6: Close HTTPS (Disable HTTPS)#

Disable HTTPS access for an Elasticsearch instance.

Pre-check: Call DescribeInstance first to check Result.protocol. If already HTTP, skip CloseHttps and inform user HTTPS is already disabled.

bash

# Check current HTTPS status
protocol=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.protocol')

if [ "$protocol" == "HTTP" ]; then
  echo "✅ HTTPS is already disabled, no action needed"
else
  # Disable HTTPS
  aliyun elasticsearch close-https \
    --instance-id <InstanceId> \
    --read-timeout 30 \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage
fi

---

Task 7: Update Kibana PVL Network (Update Kibana Private Network Configuration)#

Update Kibana private network access configuration, primarily used for modifying security groups.

Prerequisites:

1. This API only supports cloud-native instances (archType=public). For basic management instances, use TriggerNetwork.
2. Kibana specification must be greater than 1 core 2GB.
3. Instance must have Kibana private network access enabled.

Use Case: Use this API when cloud-native instances need to modify Kibana private network access security groups (whitelist control).

Request Parameters:

ParameterTypeLocationRequiredDescriptionInstanceIdStringPathYesInstance IDpvlIdStringQueryYesKibana private link ID, format: {InstanceId}-kibana-internal-internal``endpointNameStringBodyNoEndpoint namesecurityGroupsArrayBodyNoSecurity group ID arraybash

# Update Kibana private network security group
aliyun elasticsearch update-kibana-pvl-network \
  --instance-id <InstanceId> \
  --pvl-id <InstanceId>-kibana-internal-internal \
  --body '{"securityGroups": ["<NewSecurityGroupId>"]}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

Task 8: Update Kibana SSO (Enable/Disable Kibana Alibaba Cloud Account Authentication)#

Enable or disable Kibana Alibaba Cloud account SSO authentication. When enabled, users must log in with their Alibaba Cloud account before using Kibana.

Prerequisites: This API only supports cloud-native instances (archType=public).

Pre-check: Call DescribeInstance to check Result.enableKibanaPublicSSO / Result.enableKibanaPrivateSSO. If desired state already achieved, skip the call.

Parameters: See references/related-apis.md for full details.

bash

# Enable Kibana SSO for public network
aliyun elasticsearch update-kibana-sso \
  --instance-id <InstanceId> \
  --body '{"enable":true,"networkType":"PUBLIC"}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

# Disable Kibana SSO for private network
aliyun elasticsearch update-kibana-sso \
  --instance-id <InstanceId> \
  --body '{"enable":false,"networkType":"PRIVATE"}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

---

Success Verification Method#

For detailed verification steps, see references/verification-method.md. After each operation, check RequestId in response and call DescribeInstance to confirm changes.

---

Best Practices#

1. Cloud-native Kibana: Private network uses EnableKibanaPvlNetwork/DisableKibanaPvlNetwork. Whitelist via UpdateKibanaPvlNetwork. SSO via UpdateKibanaSso (archType=public only).
2. Security: Use 0.0.0.0/0 with caution. Enable HTTPS in production.
3. Reliability: Use clientToken for idempotency. Retry on InstanceStatusNotSupportCurrentAction/ ConcurrencyUpdateInstanceConflict (wait 30-60s). Check current state before changes, skip if desired state already achieved.

---

Reference Links#

ReferenceDescriptionreferences/related-apis.mdAPI and CLI command reference tablereferences/ram-policies.mdRAM permission policiesreferences/cli-installation-guide.mdCLI installation guidereferences/verification-method.mdVerification methodsreferences/acceptance-criteria.mdAcceptance criteria