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

---

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

>

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

# 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

Acceptance Criteria: alibabacloud-elasticsearch-network-manage

Scenario: Elasticsearch Instance Network Management Purpose: Skill testing acceptance criteria

---

Correct CLI Command Patterns

1. Product — verify product name exists

✅ CORRECT: elasticsearch

aliyun elasticsearch trigger-network

❌ INCORRECT: es, elastic, Elasticsearch

# Incorrect examples
aliyun es trigger-network           # Wrong product name
aliyun elastic trigger-network      # Wrong product name
aliyun Elasticsearch trigger-network # Case error

---

2. Command — verify action exists under the product

TriggerNetwork

✅ CORRECT:

aliyun elasticsearch trigger-network --instance-id es-cn-xxx --vpc-id vpc-xxx --vswitch-id vsw-xxx

❌ INCORRECT:

aliyun elasticsearch TriggerNetwork --instance-id es-cn-xxx      # Should use lowercase hyphen format
aliyun elasticsearch trigger-networks --instance-id es-cn-xxx    # Plural form is wrong
aliyun elasticsearch triggerNetwork --instance-id es-cn-xxx      # Camel case is wrong

EnableKibanaPvlNetwork

✅ CORRECT:

aliyun elasticsearch enable-kibana-pvl-network --instance-id es-cn-xxx

❌ INCORRECT:

aliyun elasticsearch EnableKibanaPvlNetwork --instance-id es-cn-xxx  # Should use lowercase hyphen
aliyun elasticsearch enable-kibana-pvl --instance-id es-cn-xxx       # Incomplete command

DisableKibanaPvlNetwork

✅ CORRECT:

aliyun elasticsearch disable-kibana-pvl-network --instance-id es-cn-xxx

❌ INCORRECT:

aliyun elasticsearch DisableKibanaPvlNetwork --instance-id es-cn-xxx  # Should use lowercase hyphen
aliyun elasticsearch close-kibana-pvl --instance-id es-cn-xxx         # Wrong verb

UpdateKibanaPvlNetwork

✅ CORRECT:

aliyun elasticsearch update-kibana-pvl-network --instance-id es-cn-xxx --pvl-id es-cn-xxx-kibana-internal-internal --body '{"securityGroups": ["sg-xxx"]}'

❌ INCORRECT:

aliyun elasticsearch UpdateKibanaPvlNetwork --instance-id es-cn-xxx   # Should use lowercase hyphen
aliyun elasticsearch update-kibana-pvl --instance-id es-cn-xxx         # Incomplete command

ModifyWhiteIps

✅ CORRECT:

aliyun elasticsearch modify-white-ips --instance-id es-cn-xxx --body '{...}'

❌ INCORRECT:

aliyun elasticsearch ModifyWhiteIps --instance-id es-cn-xxx      # Should use lowercase hyphen
aliyun elasticsearch modify-white-ip --instance-id es-cn-xxx     # Singular form is wrong
aliyun elasticsearch update-white-ips --instance-id es-cn-xxx    # Wrong verb

OpenHttps

✅ CORRECT:

aliyun elasticsearch open-https --instance-id es-cn-xxx

❌ INCORRECT:

aliyun elasticsearch OpenHttps --instance-id es-cn-xxx      # Should use lowercase hyphen
aliyun elasticsearch enable-https --instance-id es-cn-xxx   # Wrong verb

CloseHttps

✅ CORRECT:

aliyun elasticsearch close-https --instance-id es-cn-xxx

❌ INCORRECT:

aliyun elasticsearch CloseHttps --instance-id es-cn-xxx      # Should use lowercase hyphen
aliyun elasticsearch disable-https --instance-id es-cn-xxx   # Wrong verb

DescribeInstance

✅ CORRECT:

aliyun elasticsearch describe-instance --instance-id es-cn-xxx

❌ INCORRECT:

aliyun elasticsearch DescribeInstance --instance-id es-cn-xxx  # Should use lowercase hyphen
aliyun elasticsearch get-instance --instance-id es-cn-xxx      # Wrong verb

---

3. Parameters — verify each parameter name exists for the command

--instance-id

✅ CORRECT:

aliyun elasticsearch trigger-network --instance-id es-cn-xxx --vpc-id vpc-xxx --vswitch-id vsw-xxx

❌ INCORRECT:

aliyun elasticsearch trigger-network --InstanceId es-cn-xxx    # Camel case is wrong
aliyun elasticsearch trigger-network --instanceId es-cn-xxx    # Lower camel case is wrong
aliyun elasticsearch trigger-network --id es-cn-xxx            # Wrong parameter name

--vpc-id

✅ CORRECT:

aliyun elasticsearch trigger-network --vpc-id vpc-xxxxxx

❌ INCORRECT:

aliyun elasticsearch trigger-network --vpcId vpc-xxxxxx        # Camel case is wrong
aliyun elasticsearch trigger-network --vpc vpc-xxxxxx          # Wrong parameter name

--vswitch-id

✅ CORRECT:

aliyun elasticsearch trigger-network --vswitch-id vsw-xxxxxx

❌ INCORRECT:

aliyun elasticsearch trigger-network --vswitchId vsw-xxxxxx    # Camel case is wrong
aliyun elasticsearch trigger-network --vsw-id vsw-xxxxxx       # Wrong parameter name

--pvl-id

✅ CORRECT:

aliyun elasticsearch update-kibana-pvl-network --pvl-id es-cn-xxx-kibana-internal-internal

❌ INCORRECT:

aliyun elasticsearch update-kibana-pvl-network --pvlId es-cn-xxx-kibana-internal-internal   # Camel case is wrong
aliyun elasticsearch update-kibana-pvl-network --pvl es-cn-xxx-kibana-internal-internal      # Wrong parameter name

--white-ip-type

✅ CORRECT:

aliyun elasticsearch modify-white-ips --white-ip-type PRIVATE_ES

❌ INCORRECT:

aliyun elasticsearch modify-white-ips --whiteIpType PRIVATE_ES     # Camel case is wrong
aliyun elasticsearch modify-white-ips --ip-type PRIVATE_ES         # Wrong parameter name

--body (RequestBody)

✅ CORRECT:

aliyun elasticsearch modify-white-ips \
  --instance-id es-cn-xxx \
  --body '{"whiteIpGroup": [{"groupName": "default", "ips": ["192.168.0.0/16"]}]}'

❌ INCORRECT:

# JSON format error
aliyun elasticsearch modify-white-ips --instance-id es-cn-xxx \
  --body {whiteIpGroup: [{groupName: default}]}  # Missing quotes and correct format

--resource-group-id

✅ CORRECT:

aliyun elasticsearch trigger-network --resource-group-id rg-xxxxxx

❌ INCORRECT:

aliyun elasticsearch trigger-network --resourceGroupId rg-xxxxxx   # Camel case is wrong
aliyun elasticsearch trigger-network --rg-id rg-xxxxxx             # Wrong parameter name

---

4. --user-agent flag present

✅ CORRECT — Every command must include --user-agent AlibabaCloud-Agent-Skills:

aliyun elasticsearch trigger-network --instance-id es-cn-xxx --vpc-id vpc-xxx --vswitch-id vsw-xxx --user-agent AlibabaCloud-Agent-Skills
aliyun elasticsearch enable-kibana-pvl-network --instance-id es-cn-xxx --user-agent AlibabaCloud-Agent-Skills
aliyun elasticsearch modify-white-ips --instance-id es-cn-xxx --body '{...}' --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT — Missing user-agent:

aliyun elasticsearch trigger-network --instance-id es-cn-xxx --vpc-id vpc-xxx --vswitch-id vsw-xxx  # Missing --user-agent

---

5. Architecture Type Check

✅ CORRECT — Check architecture type before executing TriggerNetwork for Kibana private network:

# Check instance architecture type
arch_type=$(aliyun elasticsearch describe-instance --instance-id es-cn-xxx --user-agent AlibabaCloud-Agent-Skills | jq -r '.Result.archType')

if [ "$arch_type" == "public" ] && [ "$node_type" == "KIBANA" ] && [ "$network_type" == "PRIVATE" ]; then
  echo "Cloud-native instance does not support TriggerNetwork for Kibana private network"
  exit 1
fi

# Execute TriggerNetwork
aliyun elasticsearch trigger-network --instance-id es-cn-xxx --body '{"nodeType":"WORKER","networkType":"PUBLIC","actionType":"OPEN"}' --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT — Execute without checking architecture type:

# Error: Did not check archType
aliyun elasticsearch trigger-network --instance-id es-cn-xxx --body '{"nodeType":"WORKER","networkType":"PUBLIC","actionType":"OPEN"}' --user-agent AlibabaCloud-Agent-Skills

---

Correct Common SDK Code Patterns (if applicable)

1. Import Patterns

✅ CORRECT:

from alibabacloud_tea_openapi.client import Client as OpenApiClient
from alibabacloud_credentials.client import Client as CredentialClient
import alibabacloud_tea_openapi.models as open_api_models

❌ INCORRECT:

# Wrong import path
from aliyunsdkcore.client import AcsClient  # Legacy SDK
from alibabacloud_elasticsearch import Client  # Product-specific SDK not applicable for ROA style API

2. Authentication — must use CredentialClient, never hardcode AK/SK

✅ CORRECT:

from alibabacloud_credentials.client import Client as CredentialClient

credential = CredentialClient()
config = open_api_models.Config(
    credential=credential,
    endpoint="elasticsearch.cn-hangzhou.aliyuncs.com"
)
client = OpenApiClient(config)

❌ INCORRECT:

# Hardcoded credentials - strictly forbidden!
config = open_api_models.Config(
    access_key_id="LTAI4xxx",
    access_key_secret="xxx"
)

# Reading from environment variables directly - not recommended
import os
config = open_api_models.Config(
    access_key_id=os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    access_key_secret=os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
)

3. Client Initialization

✅ CORRECT:

from alibabacloud_tea_openapi.client import Client as OpenApiClient
import alibabacloud_tea_openapi.models as open_api_models

credential = CredentialClient()
config = open_api_models.Config(
    credential=credential,
    endpoint="elasticsearch.cn-hangzhou.aliyuncs.com"
)
client = OpenApiClient(config)

4. API Call Pattern (ROA Style)

Elasticsearch API uses ROA style, which differs from RPC style:

✅ CORRECT:

import alibabacloud_tea_openapi.models as open_api_models
from alibabacloud_tea_util.models import RuntimeOptions

# Construct ROA request
params = open_api_models.Params(
    action="TriggerNetwork",
    version="2017-06-13",
    protocol="HTTPS",
    method="POST",
    auth_type="AK",
    style="ROA",
    pathname=f"/openapi/instances/{instance_id}/actions/network-trigger",
    req_body_type="json",
    body_type="json"
)

request = open_api_models.OpenApiRequest()
runtime = RuntimeOptions()

response = client.call_api(params, request, runtime)

---

Error Handling Patterns

Correct Error Handling

✅ CORRECT:

from Tea.exceptions import TeaException

try:
    response = client.call_api(params, request, runtime)
except TeaException as e:
    print(f"Error Code: {e.code}")
    print(f"Error Message: {e.message}")
    print(f"Request ID: {e.data.get('RequestId', 'N/A')}")

❌ INCORRECT:

# Not handling exceptions
response = client.call_api(params, request, runtime)

# Exception catch too broad
try:
    response = client.call_api(params, request, runtime)
except:  # Catching all exceptions
    pass

---

Summary Checklist

• [ ] CLI commands use lowercase hyphen format (e.g., trigger-network, not TriggerNetwork)
• [ ] Product name uses elasticsearch
• [ ] Parameter names use lowercase hyphen format (e.g., --instance-id, not --InstanceId)
• [ ] Every command includes --user-agent AlibabaCloud-Agent-Skills
• [ ] JSON parameters use correct format and quotes
• [ ] Check archType field before executing TriggerNetwork
• [ ] SDK uses CredentialClient for authentication, no hardcoded credentials
• [ ] SDK uses ROA style to call Elasticsearch API
• [ ] Properly handle API call exceptions

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.3+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds elasticsearch

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun elasticsearch --help
   aliyun elasticsearch trigger-network --help
   aliyun elasticsearch modify-white-ips --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

RAM Policies - Elasticsearch Instance Network Management

This document lists the RAM permissions required to execute Elasticsearch instance network management operations.

---

Full Permission Policy

To execute all network management operations, use the following full permission policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:TriggerNetwork",
        "elasticsearch:EnableKibanaPvlNetwork",
        "elasticsearch:DisableKibanaPvlNetwork",
        "elasticsearch:UpdateKibanaPvlNetwork",
        "elasticsearch:ModifyWhiteIps",
        "elasticsearch:OpenHttps",
        "elasticsearch:CloseHttps",
        "elasticsearch:UpdateKibanaSso"
      ],
      "Resource": "*"
    }
  ]
}

---

Per-Operation Permission Policies

1. DescribeInstance - View Instance Details

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:DescribeInstance",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

Limit to specific instance:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:DescribeInstance",
      "Resource": "acs:elasticsearch:cn-hangzhou:*:instances/es-cn-xxxxxx"
    }
  ]
}

2. TriggerNetwork - Trigger Network Change

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:TriggerNetwork",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

3. EnableKibanaPvlNetwork - Enable Kibana Private Network Access

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:EnableKibanaPvlNetwork",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

4. DisableKibanaPvlNetwork - Disable Kibana Private Network Access

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:DisableKibanaPvlNetwork",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

5. UpdateKibanaPvlNetwork - Update Kibana Private Network Access Configuration

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:UpdateKibanaPvlNetwork",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

6. ModifyWhiteIps - Modify Whitelist

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:ModifyWhiteIps",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

7. OpenHttps - Enable HTTPS

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:OpenHttps",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

8. CloseHttps - Disable HTTPS

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:CloseHttps",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

9. UpdateKibanaSso - Enable/Disable Kibana SSO Authentication

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticsearch:UpdateKibanaSso",
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

---

Read-Only Permission Policy

Only view instance information, no modification operations:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance"
      ],
      "Resource": "*"
    }
  ]
}

---

Network Management Permission Policy

Allow viewing and managing network configurations (excluding architecture changes):

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:EnableKibanaPvlNetwork",
        "elasticsearch:DisableKibanaPvlNetwork",
        "elasticsearch:UpdateKibanaPvlNetwork",
        "elasticsearch:ModifyWhiteIps",
        "elasticsearch:OpenHttps",
        "elasticsearch:CloseHttps",
        "elasticsearch:UpdateKibanaSso"
      ],
      "Resource": "*"
    }
  ]
}

---

Resource ARN Format

Elasticsearch resource ARN format:

acs:elasticsearch:{region}:{account-id}:instances/{instance-id}

Examples:

---

Related Dependency Permissions

VPC Related Permissions (required for TriggerNetwork)

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeVSwitches",
        "vpc:DescribeVSwitchAttributes"
      ],
      "Resource": "*"
    }
  ]
}

---

Reference Links

• RAM Policy Overview
• Elasticsearch Authorization Information

Related APIs - Elasticsearch Instance Network Management

This document lists all APIs and CLI commands related to Elasticsearch instance network management.

---

Important Constraints

Required Parameter Handling Principles

>

- No guessing: If user does not provide required parameters, Agent is prohibited from guessing or fabricating parameter values

- Must ask: When required parameters are missing, must ask user and obtain exact values before executing

- Clear notification: Inform user which required parameters are missing, their purpose and format requirements

>

Core Required Parameters (needed for all operations):

>

| Parameter | Description | Requirement |

|-----------|-------------|-------------|

| InstanceId | Elasticsearch Instance ID | Must be provided by user, format like es-cn-xxxxxx, no guessing or using example values |

| RegionId | Region ID | Must be provided or confirmed by user, like cn-hangzhou, cn-shanghai, no assuming defaults |

>

Other Required Parameters Example:

>

EnableKibanaPvlNetwork also requires vpcId, vswitchId, zoneId, securityGroups etc. If user does not provide them, must ask user to obtain them; cannot use example or default values.

---

API List

1. TriggerNetwork - Enable/Disable Public/Private Network Access

Request Parameters:

CLI Examples:

# Enable Kibana public network access
aliyun elasticsearch trigger-network \
  --instance-id es-cn-xxxxxx \
  --body '{
    "nodeType": "KIBANA",
    "networkType": "PUBLIC",
    "actionType": "OPEN"
  }' \
  --user-agent AlibabaCloud-Agent-Skills

# Disable Elasticsearch public network access
aliyun elasticsearch trigger-network \
  --instance-id es-cn-xxxxxx \
  --body '{
    "nodeType": "WORKER",
    "networkType": "PUBLIC",
    "actionType": "CLOSE"
  }' \
  --user-agent AlibabaCloud-Agent-Skills

# Enable Elasticsearch private network access
aliyun elasticsearch trigger-network \
  --instance-id es-cn-xxxxxx \
  --body '{
    "nodeType": "WORKER",
    "networkType": "PRIVATE",
    "actionType": "OPEN"
  }' \
  --user-agent AlibabaCloud-Agent-Skills

Parameter Values:

Restrictions:

• Only supports basic management architecture instances (archType != public)
• For cloud-native instances, use EnableKibanaPvlNetwork / DisableKibanaPvlNetwork

---

2. EnableKibanaPvlNetwork - Enable Kibana Private Network Access

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

Request Parameters (Path):

Request Parameters (Body):

CLI Examples:

# Enable Kibana private network access (full parameters)
aliyun elasticsearch enable-kibana-pvl-network \
  --instance-id es-cn-xxxxxx \
  --body '{
    "endpointName": "es-cn-xxxxxx-kibana-endpoint",
    "securityGroups": ["sg-bp1abqv5dbxwcsabumv1"],
    "vSwitchIdsZone": [
      {
        "vswitchId": "vsw-bp1x936kmfj670gzt0l6g",
        "zoneId": "cn-hangzhou-i"
      }
    ],
    "vpcId": "vpc-bp156dwhpk7x1fuix74h3"
  }' \
  --user-agent AlibabaCloud-Agent-Skills

Get Required Parameters:

# Get VPC and VSwitch info from instance details
aliyun elasticsearch describe-instance \
  --instance-id es-cn-xxxxxx | jq '.Result.networkConfig | {vpcId, vswitchId, vsArea}'

# Query security groups under VPC
aliyun ecs DescribeSecurityGroups \
  --VpcId vpc-xxxxxx \
  --RegionId cn-hangzhou | jq '.SecurityGroups.SecurityGroup[] | {SecurityGroupId, SecurityGroupName}'

---

3. DisableKibanaPvlNetwork - Disable Kibana Private Network Access

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

Request Parameters:

CLI Examples:

# Disable Kibana PVL
aliyun elasticsearch disable-kibana-pvl-network \
  --instance-id es-cn-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

# With resource group specified
aliyun elasticsearch disable-kibana-pvl-network \
  --instance-id es-cn-xxxxxx \
  --resource-group-id rg-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

---

4. UpdateKibanaPvlNetwork - Update Kibana Private Network Access Configuration

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), because ModifyWhiteIps does not support Kibana private network whitelist modification for cloud-native instances.

Request Parameters:

CLI Examples:

# Update Kibana private network access security groups
aliyun elasticsearch update-kibana-pvl-network \
  --instance-id es-cn-xxxxxx \
  --pvl-id es-cn-xxxxxx-kibana-internal-internal \
  --body '{"securityGroups": ["sg-bp1newgroup123"]}' \
  --user-agent AlibabaCloud-Agent-Skills

# Update both endpoint name and security groups
aliyun elasticsearch update-kibana-pvl-network \
  --instance-id es-cn-xxxxxx \
  --pvl-id es-cn-xxxxxx-kibana-internal-internal \
  --body '{"endpointName": "new-kibana-endpoint", "securityGroups": ["sg-bp1newgroup123"]}' \
  --user-agent AlibabaCloud-Agent-Skills

pvlId Description:

• Format is {InstanceId}-kibana-internal-internal
• For example, if instance ID is es-cn-xxxxxx, then pvlId is es-cn-xxxxxx-kibana-internal-internal

---

5. ModifyWhiteIps - Modify Whitelist

Notes:

- Cannot update when instance status is activating, invalid, or inactive

- Cannot use both methods simultaneously

- Public network whitelist does not support private IPs; private network whitelist does not support public IPs

- Cloud-native instances (archType=public) Kibana private network whitelist cannot be modified through this API, use UpdateKibanaPvlNetwork API via security group changes instead

Request Parameters (Path/Query):

Method 1: IP Whitelist (Body Parameters)

Method 2: IP Whitelist Group (Body Parameters)

whiteIpType Values:

CLI Examples:

# Method 1: IP whitelist - Modify ES public network whitelist
aliyun elasticsearch modify-white-ips \
  --instance-id es-cn-xxxxxx \
  --body '{"nodeType":"WORKER","networkType":"PUBLIC","whiteIpList":["59.0.0.0/8","120.0.0.0/8"]}' \
  --user-agent AlibabaCloud-Agent-Skills

# Method 1: IP whitelist - Modify ES private network whitelist
aliyun elasticsearch modify-white-ips \
  --instance-id es-cn-xxxxxx \
  --body '{"nodeType":"WORKER","networkType":"PRIVATE","whiteIpList":["192.168.1.0/24","10.0.0.0/8"]}' \
  --user-agent AlibabaCloud-Agent-Skills

# Method 2: IP whitelist group - Cover mode
aliyun elasticsearch modify-white-ips \
  --instance-id es-cn-xxxxxx \
  --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

# Method 2: IP whitelist group - Append mode (group must exist)
aliyun elasticsearch modify-white-ips \
  --instance-id es-cn-xxxxxx \
  --body '{"modifyMode":"Append","whiteIpGroup":{"groupName":"default","ips":["172.16.0.0/12"],"whiteIpType":"PRIVATE_ES"}}' \
  --user-agent AlibabaCloud-Agent-Skills

# Method 2: IP whitelist group - Delete mode (at least one IP must remain)
aliyun elasticsearch modify-white-ips \
  --instance-id es-cn-xxxxxx \
  --body '{"modifyMode":"Delete","whiteIpGroup":{"groupName":"default","ips":["192.168.1.100"],"whiteIpType":"PRIVATE_ES"}}' \
  --user-agent AlibabaCloud-Agent-Skills

modifyMode Description:

modifyMode Selection Guidelines:

CRITICAL: The modifyMode and whiteIpList parameters have destructive potential. Incorrect mode selection can overwrite or delete existing whitelist entries.

>

Selection Rules:

- Append — User wants to add IPs to an existing group without affecting current entries

- Cover — User wants to replace the entire group content, or create a new group, or delete a group (empty ips)

- Delete — User wants to remove specific IPs from an existing group

- Method 1 (whiteIpList) — Always overwrites the Default group; use only when user explicitly wants full replacement

>

When user intent is unclear, MUST ask the user which mode to use. Never assume Cover mode by default.

>

Append NotFound Error Recovery:

If Append fails because the group does not exist:

1. Inform the user that the group does not exist

2. Suggest creating it using Cover mode with the desired IPs

3. Do NOT silently switch to Cover mode — this could overwrite an existing group with the same name

---

6. OpenHttps - Enable HTTPS

Request Parameters:

CLI Examples:

# Enable HTTPS
aliyun elasticsearch open-https \
  --instance-id es-cn-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

# With resource group specified
aliyun elasticsearch open-https \
  --instance-id es-cn-xxxxxx \
  --resource-group-id rg-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

---

7. CloseHttps - Disable HTTPS

Request Parameters:

CLI Examples:

# Disable HTTPS
aliyun elasticsearch close-https \
  --instance-id es-cn-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

# With resource group specified
aliyun elasticsearch close-https \
  --instance-id es-cn-xxxxxx \
  --resource-group-id rg-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

---

8. DescribeInstance - View Instance Details

Request Parameters:

CLI Examples:

# View instance details
aliyun elasticsearch describe-instance \
  --instance-id es-cn-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills

# Check architecture type (for TriggerNetwork support)
aliyun elasticsearch describe-instance \
  --instance-id es-cn-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills | jq '.Result.archType'

Response Fields (Network Related):

---

9. UpdateKibanaSso - Enable/Disable Kibana Alibaba Cloud Account Authentication

Request Parameters:

Status Check Fields (via DescribeInstance):

Pre-check Script:

# Verify architecture and current SSO status
instance_info=$(aliyun elasticsearch describe-instance \
  --instance-id es-cn-xxxxxx \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage)

arch_type=$(echo "$instance_info" | jq -r '.Result.archType')
if [ "$arch_type" != "public" ]; then
  echo "❌ UpdateKibanaSso only supports cloud-native instances (archType=public)"
  exit 1
fi

public_sso=$(echo "$instance_info" | jq -r '.Result.enableKibanaPublicSSO')
private_sso=$(echo "$instance_info" | jq -r '.Result.enableKibanaPrivateSSO')
echo "Current SSO status: public=$public_sso, private=$private_sso"

CLI Examples:

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

# Disable Kibana SSO for public network
aliyun elasticsearch update-kibana-sso \
  --instance-id es-cn-xxxxxx \
  --body '{"enable":false,"networkType":"PUBLIC"}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

# Enable Kibana SSO for private network
aliyun elasticsearch update-kibana-sso \
  --instance-id es-cn-xxxxxx \
  --body '{"enable":true,"networkType":"PRIVATE"}' \
  --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 es-cn-xxxxxx \
  --body '{"enable":false,"networkType":"PRIVATE"}' \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

Response:

{
  "RequestId": "C82758DD-282F-4D48-934F-92170A33****",
  "Result": true
}

RAM Permission: elasticsearch:UpdateKibanaSso

---

API Version Information

---

Architecture Type Description

archType Field

Check Architecture Type

# Check instance architecture type
arch_type=$(aliyun elasticsearch describe-instance \
  --instance-id es-cn-xxxxxx \
  --user-agent AlibabaCloud-Agent-Skills | jq -r '.Result.archType')

if [ "$arch_type" == "public" ]; then
  echo "Cloud-native instance"
else
  echo "Basic management instance"
fi

---

Reference Links

• TriggerNetwork API Documentation
• EnableKibanaPvlNetwork API Documentation
• DisableKibanaPvlNetwork API Documentation
• ModifyWhiteIps API Documentation
• OpenHttps API Documentation
• CloseHttps API Documentation
• UpdateKibanaSso API Documentation
• DescribeInstance API Documentation

Verification Method - Elasticsearch Instance Network Management

This document describes methods to verify whether various API operations are successful.

---

1. DescribeInstance Verification (Pre-check)

Verification Command:

aliyun elasticsearch describe-instance \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage

Success Criteria:

• HTTP status code: 200
• Response JSON contains RequestId field
• Result.instanceId matches the requested InstanceId
• Result.archType exists (used to determine TriggerNetwork support)

Verification Script:

INSTANCE_ID="es-cn-xxxxxx"
result=$(aliyun elasticsearch describe-instance --instance-id $INSTANCE_ID --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.Result.instanceId' > /dev/null 2>&1; then
    returned_id=$(echo "$result" | jq -r '.Result.instanceId')
    arch_type=$(echo "$result" | jq -r '.Result.archType')
    
    if [ "$returned_id" == "$INSTANCE_ID" ]; then
        echo "✅ DescribeInstance succeeded"
        echo "Instance architecture type: $arch_type"
        
        # Check if cloud-native
        if [ "$arch_type" == "public" ]; then
            echo "⚠️  Cloud-native instance, TriggerNetwork not supported for Kibana private network"
        else
            echo "✅ Basic management instance, TriggerNetwork supported"
        fi
    else
        echo "❌ Returned instance ID does not match"
    fi
else
    echo "❌ DescribeInstance failed"
    echo "$result"
fi

---

2. TriggerNetwork Verification

Verification Steps:

1. Confirm instance is not cloud-native (archType != public) when operating Kibana private network 2. Execute TriggerNetwork 3. Use DescribeInstance to confirm network configuration changes

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"
VPC_ID="vpc-xxxxxx"
VSWITCH_ID="vsw-xxxxxx"

# 1. Check architecture type
arch_type=$(aliyun elasticsearch describe-instance \
  --instance-id $INSTANCE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.archType')

if [ "$arch_type" == "public" ] && [ "$node_type" == "KIBANA" ] && [ "$network_type" == "PRIVATE" ]; then
  echo "❌ Cloud-native instance does not support TriggerNetwork for Kibana private network"
  exit 1
fi

# 2. Execute network change
echo "Triggering network change..."
result=$(aliyun elasticsearch trigger-network \
  --instance-id $INSTANCE_ID \
  --body '{"nodeType":"WORKER","networkType":"PUBLIC","actionType":"OPEN"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ TriggerNetwork request submitted"
  echo "RequestId: $(echo "$result" | jq -r '.RequestId')"
else
  echo "❌ TriggerNetwork failed"
  echo "$result"
  exit 1
fi

# 3. Wait and verify network change (timeout: max 15 minutes)
sleep 10
echo "Verifying network configuration changes..."
max_retries=30
retry_count=0

start_time=$(date +%s)
timeout_seconds=900

while [ $retry_count -lt $max_retries ]; do
  # Check total timeout (15 minutes)
  current_time=$(date +%s)
  elapsed=$((current_time - start_time))
  if [ $elapsed -gt $timeout_seconds ]; then
    echo "⚠️  Verification timeout (15 minutes), please check network configuration manually"
    break
  fi
  
  network_config=$(aliyun elasticsearch describe-instance \
    --instance-id $INSTANCE_ID \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>/dev/null | jq -r '.Result.networkConfig')
  
  current_vpc=$(echo "$network_config" | jq -r '.vpcId')
  current_vswitch=$(echo "$network_config" | jq -r '.vswitchId')
  
  if [ "$current_vpc" == "$VPC_ID" ] && [ "$current_vswitch" == "$VSWITCH_ID" ]; then
    echo "✅ TriggerNetwork succeeded, network configuration updated"
    break
  fi
  
  retry_count=$((retry_count + 1))
  echo "Waiting for network change to complete... ($retry_count/$max_retries)"
  sleep 30
done

if [ $retry_count -eq $max_retries ]; then
  echo "⚠️  Verification timeout, please check network configuration manually"
fi

Success Criteria:

• TriggerNetwork request returns RequestId
• DescribeInstance returns network configuration matching the request

---

3. EnableKibanaPvlNetwork Verification

Verification Steps:

1. Execute EnableKibanaPvlNetwork 2. Use DescribeInstance to confirm Kibana PVL is enabled

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"

# 1. Execute enable operation
echo "Enabling Kibana PVL..."
result=$(aliyun elasticsearch enable-kibana-pvl-network \
  --instance-id $INSTANCE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ EnableKibanaPvlNetwork request submitted"
else
  echo "❌ EnableKibanaPvlNetwork failed"
  echo "$result"
  exit 1
fi

# 2. Wait and verify (timeout: max 10 minutes)
sleep 10
echo "Verifying Kibana PVL status..."
max_retries=20
retry_count=0
start_time=$(date +%s)
timeout_seconds=600

while [ $retry_count -lt $max_retries ]; do
  # Check total timeout
  current_time=$(date +%s)
  elapsed=$((current_time - start_time))
  if [ $elapsed -gt $timeout_seconds ]; then
    echo "⚠️  Verification timeout (10 minutes), please check Kibana PVL status manually"
    break
  fi
  
  pvl_enabled=$(aliyun elasticsearch describe-instance \
    --instance-id $INSTANCE_ID \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>/dev/null | jq -r '.Result.enableKibanaPrivateNetwork')
  
  if [ "$pvl_enabled" == "true" ]; then
    echo "✅ EnableKibanaPvlNetwork succeeded, Kibana PVL is enabled"
    break
  fi
  
  retry_count=$((retry_count + 1))
  echo "Waiting for Kibana PVL to enable... ($retry_count/$max_retries)"
  sleep 30
done

if [ $retry_count -eq $max_retries ]; then
  echo "⚠️  Verification timeout, please check Kibana PVL status manually"
fi

Success Criteria:

• EnableKibanaPvlNetwork request returns RequestId
• DescribeInstance returns enableKibanaPrivateNetwork as true

---

4. DisableKibanaPvlNetwork Verification

Verification Steps:

1. Confirm instance is cloud-native (archType=public) 2. Execute DisableKibanaPvlNetwork 3. Use DescribeInstance to confirm Kibana PVL is disabled

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"

# 1. Execute disable operation
echo "Disabling Kibana PVL..."
result=$(aliyun elasticsearch disable-kibana-pvl-network \
  --instance-id $INSTANCE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ DisableKibanaPvlNetwork request submitted"
else
  echo "❌ DisableKibanaPvlNetwork failed"
  echo "$result"
  exit 1
fi

# 2. Wait and verify (timeout: max 10 minutes)
sleep 10
echo "Verifying Kibana PVL status..."
max_retries=20
retry_count=0
start_time=$(date +%s)
timeout_seconds=600

while [ $retry_count -lt $max_retries ]; do
  # Check total timeout
  current_time=$(date +%s)
  elapsed=$((current_time - start_time))
  if [ $elapsed -gt $timeout_seconds ]; then
    echo "⚠️  Verification timeout (10 minutes), please check Kibana PVL status manually"
    break
  fi
  
  pvl_enabled=$(aliyun elasticsearch describe-instance \
    --instance-id $INSTANCE_ID \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>/dev/null | jq -r '.Result.enableKibanaPrivateNetwork')
  
  if [ "$pvl_enabled" == "false" ] || [ "$pvl_enabled" == "null" ]; then
    echo "✅ DisableKibanaPvlNetwork succeeded, Kibana PVL is disabled"
    break
  fi
  
  retry_count=$((retry_count + 1))
  echo "Waiting for Kibana PVL to disable... ($retry_count/$max_retries)"
  sleep 30
done

if [ $retry_count -eq $max_retries ]; then
  echo "⚠️  Verification timeout, please check Kibana PVL status manually"
fi

Success Criteria:

• DisableKibanaPvlNetwork request returns RequestId
• DescribeInstance returns enableKibanaPrivateNetwork as false or not exists

---

5. UpdateKibanaPvlNetwork Verification

Verification Steps:

1. Execute UpdateKibanaPvlNetwork 2. Use DescribeInstance to confirm Kibana private network access configuration is updated

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"
PVL_ID="${INSTANCE_ID}-kibana-internal-internal"
NEW_SG="sg-bp1newgroup123"

# 1. Execute update operation
echo "Updating Kibana PVL configuration..."
result=$(aliyun elasticsearch update-kibana-pvl-network \
  --instance-id $INSTANCE_ID \
  --pvl-id $PVL_ID \
  --body "{\"securityGroups\": [\"$NEW_SG\"]}" \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ UpdateKibanaPvlNetwork request submitted"
  echo "RequestId: $(echo "$result" | jq -r '.RequestId')"
else
  echo "❌ UpdateKibanaPvlNetwork failed"
  echo "$result"
  exit 1
fi

# 2. Wait and verify (timeout: max 10 minutes)
sleep 10
echo "Verifying Kibana PVL configuration update..."
max_retries=20
retry_count=0
start_time=$(date +%s)
timeout_seconds=600

while [ $retry_count -lt $max_retries ]; do
  # Check total timeout
  current_time=$(date +%s)
  elapsed=$((current_time - start_time))
  if [ $elapsed -gt $timeout_seconds ]; then
    echo "⚠️  Verification timeout (10 minutes), please check Kibana PVL configuration manually"
    break
  fi
  
  instance_info=$(aliyun elasticsearch describe-instance \
    --instance-id $INSTANCE_ID \
    --read-timeout 30 \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>/dev/null)
  
  status=$(echo "$instance_info" | jq -r '.Result.status')
  
  if [ "$status" == "active" ]; then
    echo "✅ UpdateKibanaPvlNetwork succeeded, Kibana PVL configuration updated"
    break
  fi
  
  retry_count=$((retry_count + 1))
  echo "Waiting for Kibana PVL configuration update... ($retry_count/$max_retries)"
  sleep 30
done

if [ $retry_count -eq $max_retries ]; then
  echo "⚠️  Verification timeout, please check Kibana PVL configuration manually"
fi

Success Criteria:

• UpdateKibanaPvlNetwork request returns RequestId
• DescribeInstance returns instance status as active, security group configuration is updated

---

6. ModifyWhiteIps Verification

Verification Steps:

1. Execute ModifyWhiteIps 2. Use DescribeInstance to confirm whitelist is updated

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"

# 1. Execute whitelist modification
echo "Modifying whitelist..."
result=$(aliyun elasticsearch modify-white-ips \
  --instance-id $INSTANCE_ID \
  --white-ip-type PRIVATE_ES \
  --body '{
    "whiteIpGroup": [
      {
        "groupName": "default",
        "ips": ["192.168.1.0/24"]
      }
    ]
  }' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ ModifyWhiteIps request submitted"
else
  echo "❌ ModifyWhiteIps failed"
  echo "$result"
  exit 1
fi

# 2. Wait and verify
sleep 5
echo "Verifying whitelist update..."
white_ips=$(aliyun elasticsearch describe-instance \
  --instance-id $INSTANCE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage | jq -r '.Result.networkConfig.whiteIpList')

echo "Current whitelist: $white_ips"
echo "✅ ModifyWhiteIps succeeded"

Success Criteria:

• ModifyWhiteIps request returns RequestId
• DescribeInstance returns whitelist matching the request

---

7. OpenHttps Verification

Verification Steps:

1. Execute OpenHttps 2. Use DescribeInstance to confirm HTTPS is enabled

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"

# 1. Execute enable HTTPS
echo "Enabling HTTPS..."
result=$(aliyun elasticsearch open-https \
  --instance-id $INSTANCE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ OpenHttps request submitted"
else
  echo "❌ OpenHttps failed"
  echo "$result"
  exit 1
fi

# 2. Wait and verify (timeout: max 10 minutes)
sleep 10
echo "Verifying HTTPS status..."
max_retries=20
retry_count=0
start_time=$(date +%s)
timeout_seconds=600

while [ $retry_count -lt $max_retries ]; do
  # Check total timeout
  current_time=$(date +%s)
  elapsed=$((current_time - start_time))
  if [ $elapsed -gt $timeout_seconds ]; then
    echo "⚠️  Verification timeout (10 minutes), please check HTTPS status manually"
    break
  fi
  
  protocol=$(aliyun elasticsearch describe-instance \
    --instance-id $INSTANCE_ID \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>/dev/null | jq -r '.Result.protocol')
  
  if [ "$protocol" == "HTTPS" ]; then
    echo "✅ OpenHttps succeeded, HTTPS is enabled"
    break
  fi
  
  retry_count=$((retry_count + 1))
  echo "Waiting for HTTPS to enable... ($retry_count/$max_retries)"
  sleep 30
done

if [ $retry_count -eq $max_retries ]; then
  echo "⚠️  Verification timeout, please check HTTPS status manually"
fi

Success Criteria:

• OpenHttps request returns RequestId
• DescribeInstance returns protocol as HTTPS

---

8. CloseHttps Verification

Verification Steps:

1. Execute CloseHttps 2. Use DescribeInstance to confirm HTTPS is disabled

Verification Command:

INSTANCE_ID="es-cn-xxxxxx"

# 1. Execute disable HTTPS
echo "Disabling HTTPS..."
result=$(aliyun elasticsearch close-https \
  --instance-id $INSTANCE_ID \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)

if echo "$result" | jq -e '.RequestId' > /dev/null 2>&1; then
  echo "✅ CloseHttps request submitted"
else
  echo "❌ CloseHttps failed"
  echo "$result"
  exit 1
fi

# 2. Wait and verify (timeout: max 10 minutes)
sleep 10
echo "Verifying HTTPS status..."
max_retries=20
retry_count=0
start_time=$(date +%s)
timeout_seconds=600

while [ $retry_count -lt $max_retries ]; do
  # Check total timeout
  current_time=$(date +%s)
  elapsed=$((current_time - start_time))
  if [ $elapsed -gt $timeout_seconds ]; then
    echo "⚠️  Verification timeout (10 minutes), please check HTTPS status manually"
    break
  fi
  
  protocol=$(aliyun elasticsearch describe-instance \
    --instance-id $INSTANCE_ID \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>/dev/null | jq -r '.Result.protocol')
  
  if [ "$protocol" == "HTTP" ]; then
    echo "✅ CloseHttps succeeded, HTTPS is disabled"
    break
  fi
  
  retry_count=$((retry_count + 1))
  echo "Waiting for HTTPS to disable... ($retry_count/$max_retries)"
  sleep 30
done

if [ $retry_count -eq $max_retries ]; then
  echo "⚠️  Verification timeout, please check HTTPS status manually"
fi

Success Criteria:

• CloseHttps request returns RequestId
• DescribeInstance returns protocol as HTTP

---

Common Error Handling

Common Error Codes:

Error Handling Script Template:

result=$(aliyun elasticsearch <command> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-network-manage 2>&1)
exit_code=$?

if [ $exit_code -ne 0 ]; then
    error_code=$(echo "$result" | jq -r '.Code // empty')
    error_message=$(echo "$result" | jq -r '.Message // empty')
    
    echo "❌ Command execution failed"
    echo "Error code: $error_code"
    echo "Error message: $error_message"
    
    # Specific error handling
    case "$error_code" in
        "InvalidInstanceType")
            echo "Hint: Cloud-native instances do not support this operation"
            ;;
        "InstanceActivating")
            echo "Hint: Please wait for instance status to become active and retry"
            ;;
    esac
else
    echo "✅ Command execution succeeded"
fi