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

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.

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

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

[MUST] Plugin Update

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

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

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

Environment Variables

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.

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

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.

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

# 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.

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

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/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.

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)

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

whiteIpType Values:

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

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.

# 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.

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

# 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.

# 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