Alibabacloud Elasticsearch Network Manage

Other

Alibaba Cloud Elasticsearch Instance Network Management Skill. Use for managing ES instance network configurations including triggering network, Kibana PVL network, white IP list, HTTPS settings, and Kibana SSO authentication. Triggers: "elasticsearch network", "ES network", "kibana pvl", "white ip", "https", "trigger network", "modify white ips", "kibana sso", "kibana authentication".

Install

openclaw skills install alibabacloud-elasticsearch-network-manage

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

Variable	Required	Description
`ALIBABA_CLOUD_ACCESS_KEY_ID`	Yes	Alibaba Cloud AccessKey ID
`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	Yes	Alibaba Cloud AccessKey Secret
`ALIBABA_CLOUD_REGION_ID`	No	Default 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 Name	Required/Optional	Description	Default Value
`InstanceId`	Required (for all operations)	Elasticsearch Instance ID	-
`RegionId`	Optional	Region ID	cn-hangzhou
`nodeType`	Required (TriggerNetwork)	Instance Type: KIBANA/WORKER	-
`networkType`	Required (TriggerNetwork)	Network Type: PUBLIC/PRIVATE	-
`actionType`	Required (TriggerNetwork)	Action Type: OPEN/CLOSE	-
`resourceGroupId`	Optional	Resource Group ID	-
`whiteIpGroup`	Required (ModifyWhiteIps)	White IP Group Configuration	-
`whiteIpType`	Optional (ModifyWhiteIps)	White IP Type: PRIVATE_ES/PUBLIC_KIBANA	PRIVATE_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
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:

Parameter	Type	Required	Description
`nodeType`	String	Yes	Instance Type: KIBANA (Kibana cluster) / WORKER (Elasticsearch cluster)
`networkType`	String	Yes	Network Type: PUBLIC / PRIVATE
`actionType`	String	Yes	Action Type: OPEN (enable) / CLOSE (disable)

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

Parameter	Type	Required	Description
`endpointName`	String	Yes	Endpoint name, recommended format: `{InstanceId}-kibana-endpoint`
`securityGroups`	Array	Yes	Security group ID array
`vSwitchIdsZone`	Array	Yes	VSwitch and availability zone information
`vSwitchIdsZone[].vswitchId`	String	Yes	Virtual switch ID
`vSwitchIdsZone[].zoneId`	String	Yes	Availability zone ID
`vpcId`	String	Yes	VPC 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.

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

IP White List Method: Use whiteIpList + nodeType + networkType
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)

Parameter	Type	Required	Description
`whiteIpList`	Array	Yes	IP white list, will overwrite Default group
`nodeType`	String	Yes	Node Type: WORKER (ES cluster) / KIBANA
`networkType`	String	Yes	Network Type: PUBLIC / PRIVATE

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

Parameter	Type	Required	Description
`modifyMode`	String	No	Modify mode: Cover (overwrite, default) / Append / Delete
`whiteIpGroup.groupName`	String	Yes	White IP group name
`whiteIpGroup.ips`	Array	Yes	IP address list
`whiteIpGroup.whiteIpType`	String	No	White IP type (see table below)

whiteIpType Values:

Value	Description
`PRIVATE_ES`	Elasticsearch private network white list
`PUBLIC_ES`	Elasticsearch public network white list
`PRIVATE_KIBANA`	Kibana private network white list
`PUBLIC_KIBANA`	Kibana public network white list

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

Mode	Description
`Cover`	Overwrite mode (default). Empty ips deletes group; non-existent groupName creates new
`Append`	Append mode. Group must exist, otherwise NotFound error
`Delete`	Delete 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.

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

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

Kibana specification must be greater than 1 core 2GB.

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:

Parameter	Type	Location	Required	Description
`InstanceId`	String	Path	Yes	Instance ID
`pvlId`	String	Query	Yes	Kibana private link ID, format: `{InstanceId}-kibana-internal-internal`
`endpointName`	String	Body	No	Endpoint name
`securityGroups`	Array	Body	No	Security group ID array

# 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

Cloud-native Kibana: Private network uses EnableKibanaPvlNetwork/DisableKibanaPvlNetwork. Whitelist via UpdateKibanaPvlNetwork. SSO via UpdateKibanaSso (archType=public only).
Security: Use 0.0.0.0/0 with caution. Enable HTTPS in production.
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

Reference	Description
references/related-apis.md	API and CLI command reference table
references/ram-policies.md	RAM permission policies
references/cli-installation-guide.md	CLI installation guide
references/verification-method.md	Verification methods
references/acceptance-criteria.md	Acceptance criteria