Elasticsearch Instance Network Management

# Install Aliyun CLI
curl -fsSL --connect-timeout 10 --max-time 60 https://aliyuncli.alicdn.com/install.sh | bash

# Verify installation
aliyun version

Environment Variables

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.

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

Credential Issue Handling:

If aliyun configure list shows no valid credentials or incorrect configuration:

1. Identify the issue: Inform the user that credentials are not configured or misconfigured
2. Guide proper configuration: Direct the user to configure credentials in the terminal (not in the chat dialog):
   • Run aliyun configure for interactive configuration
   • Or set environment variables in shell profile
3. Prohibit plaintext input: Absolutely forbidden to let user input AK/SK in plaintext in the chat dialog
4. Wait for re-verification: After configuration, re-run aliyun configure list to verify

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.

# Check instance status
aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills | jq -r '.Result.status'

If the return value is not active, wait until the instance status becomes active before proceeding.

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 enabling/disabling public/private network for both cluster and Kibana on basic management instances. Supports enabling/disabling public and private network for cluster on cloud-native instances. Supports enabling/disabling Kibana public network on cloud-native instances. For Kibana private network on cloud-native instances, use:

• EnableKibanaPvlNetwork to enable Kibana private link
• DisableKibanaPvlNetwork to disable Kibana private link

Parameters:

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

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

# Enable Elasticsearch private network access
aliyun elasticsearch trigger-network \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --body '{
    "nodeType": "WORKER",
    "networkType": "PRIVATE",
    "actionType": "OPEN"
  }' \
  --user-agent AlibabaCloud-Agent-Skills

# 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

Pre-check (Required):

# 1. Check instance architecture type (timeout 30s)
arch_type=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills | jq -r '.Result.archType')

echo "Instance architecture type: $arch_type"

# 2. If cloud-native (public) and trying to open/close Kibana private network, TriggerNetwork is not supported
if [ "$arch_type" == "public" ] && [ "$node_type" == "KIBANA" ] && [ "$network_type" == "PRIVATE" ]; then
  echo "❌ Cloud-native instances do not support TriggerNetwork for Kibana private network, use EnableKibanaPvlNetwork/DisableKibanaPvlNetwork instead"
  exit 1
fi

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):

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.

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

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

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.

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

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)

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

# Modify ES private network white list
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> \
  --body '{"nodeType":"WORKER","networkType":"PRIVATE","whiteIpList":["192.168.1.0/24","10.0.0.0/8"]}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Modify Kibana public network white list
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> \
  --body '{"nodeType":"KIBANA","networkType":"PUBLIC","whiteIpList":["0.0.0.0/0"]}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

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

whiteIpType Values:

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

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

# Delete IPs from white group (Delete mode, at least one IP must remain)
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> \
  --body '{"modifyMode":"Delete","whiteIpGroup":{"groupName":"default","ips":["192.168.1.100"],"whiteIpType":"PRIVATE_ES"}}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Create new white group (Cover mode + new group name)
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> \
  --body '{"modifyMode":"Cover","whiteIpGroup":{"groupName":"new_group","ips":["10.0.0.0/8"],"whiteIpType":"PRIVATE_ES"}}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Delete white group (Cover mode + empty ips)
aliyun elasticsearch modify-white-ips \
  --instance-id <InstanceId> \
  --body '{"modifyMode":"Cover","whiteIpGroup":{"groupName":"group_to_delete","ips":[],"whiteIpType":"PRIVATE_ES"}}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

modifyMode Description:

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.

# Check current HTTPS status
protocol=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills | 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
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.

# Check current HTTPS status
protocol=$(aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills | 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
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:

# 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

Success Verification Method

For detailed verification steps, see references/verification-method.md

Quick Verification:

1. TriggerNetwork: Check RequestId, use DescribeInstance to confirm network config changes
2. EnableKibanaPvlNetwork/DisableKibanaPvlNetwork: Check return status, use DescribeInstance to confirm PVL status
3. ModifyWhiteIps: Check return status, use DescribeInstance to confirm whitelist updated
4. OpenHttps/CloseHttps: Check return status, use DescribeInstance to confirm HTTPS status

Best Practices

1. Check architecture type for Kibana private network: For cloud-native instances (archType=public), TriggerNetwork does not support Kibana private network (nodeType=KIBANA, networkType=PRIVATE). Use EnableKibanaPvlNetwork/DisableKibanaPvlNetwork instead.
2. Kibana private network whitelist for cloud-native instances: For cloud-native instances (archType=public), Kibana private network access control should be done via UpdateKibanaPvlNetwork to modify security groups, not ModifyWhiteIps
3. Backup whitelist: Record existing configuration before modifying whitelist
4. Use 0.0.0.0/0 with caution: Opening access to all IPs poses security risks; only open necessary IP ranges
5. HTTPS recommendation: Enable HTTPS in production environments to ensure data transmission security
6. Network change impact: TriggerNetwork operations may cause brief service interruptions; execute during off-peak hours
7. Use clientToken: Use clientToken for write operations to ensure idempotency
8. Retry on instance status errors: If API calls fail with InstanceStatusNotSupportCurrentAction, TargetInstanceStatusNotSupportCurrentAction, or ConcurrencyUpdateInstanceConflict, wait 30-60 seconds and retry. See references/verification-method.md for details.
9. Idempotent operations: Check current state before making changes. Skip API calls if desired state is already achieved.

Reference Links