Elasticsearch Instance Management

Manage Alibaba Cloud Elasticsearch instances: create, describe, list, restart, upgrade/downgrade configuration, and query node information.

Architecture

Alibaba Cloud Elasticsearch Instance Management
├── createInstance     (Create Instance)
├── DescribeInstance   (Query Instance Details)
├── ListInstance       (List Instances)
├── ListAllNode        (Query Cluster Node Info)
├── RestartInstance    (Restart Instance)
└── UpdateInstance     (Upgrade/Downgrade Instance Configuration)

Prerequisites

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.

Pre-check: Aliyun CLI plugin update required [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

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

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

[MUST] AI-Mode — Before executing CLI commands, run:

1. aliyun configure ai-mode enable
2. aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage"

After all CLI operations complete, run: aliyun configure ai-mode disable

Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules (MUST FOLLOW):

• NEVER read, echo, or print AK/SK values
• NEVER ask the user to input AK/SK directly in the conversation
• NEVER use aliyun configure set with literal credential values
• NEVER accept AK/SK provided directly by users in the conversation
• ONLY read credentials from environment variables or pre-configured CLI profiles

⚠️ CRITICAL: Handling User-Provided Credentials

If a user attempts to provide AK/SK directly (e.g., "My AK is xxx, SK is yyy"):

1. STOP immediately - Do NOT execute any command
2. Reject the request politely with the following message:

   For your account security, please do not provide Alibaba Cloud AccessKey ID and AccessKey Secret directly in the conversation.
   
   Please use the following secure methods to configure credentials:
   
   Method 1: Interactive configuration via aliyun configure (Recommended)
       aliyun configure
       # Enter AK/SK as prompted, credentials will be securely stored in local config file
   
   Method 2: Configure via environment variables
       export ALIBABA_CLOUD_ACCESS_KEY_ID=\x3Cyour-access-key-id>
       export ALIBABA_CLOUD_ACCESS_KEY_SECRET=\x3Cyour-access-key-secret>
   
   After configuration, please retry your request.
   

3. Do NOT proceed with any Alibaba Cloud operations until credentials are properly configured

Check CLI configuration:

   aliyun configure list

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

If no valid credentials exist, STOP here.

RAM Policy

Ensure the RAM user has the required permissions. See references/ram-policies.md for detailed policy configurations.

Minimum Required Permissions:

• elasticsearch:CreateInstance
• elasticsearch:DescribeInstance
• elasticsearch:ListInstance
• elasticsearch:ListAllNode
• elasticsearch:RestartInstance
• elasticsearch:UpdateInstance

Core Workflow

Note: Elasticsearch APIs use ROA (RESTful) style. You can use --body to specify the HTTP request body as a JSON string. See examples in each task below.

Idempotency: For write operations (create, restart, delete, etc.), you MUST use the --client-token parameter to ensure idempotency.

• Use a UUID format unique identifier as clientToken
• When a request times out or fails, you can safely retry with the same clientToken. When retrying after timeout, it is recommended to wait 10 seconds before retrying
• Duplicate requests with the same clientToken will not execute the operation repeatedly
• Generation method: Prefer using uuidgen or PowerShell GUID; if the environment doesn't support it, generate a UUID format string directly; if strict randomness is not required, use idem-timestamp-semantic-identifier as a fallback. Do not interrupt the process due to unavailable commands.

Task 1: Create Elasticsearch Instance

node-specifications-by-region.md Different roles in different regions support different specifications when creating instances, refer to this document.

⚠️ CRITICAL: Required Parameters and Region Validation

When creating an ES instance, parameters such as --region, esAdminPassword, vpcId, vswitchId, vsArea, paymentType MUST be explicitly provided by the user.

Important Notes:

• The --region parameter MUST NOT be guessed or use default values
• If the user does not provide a region or provides an invalid region, you MUST clearly prompt the user to provide a valid region

For detailed validation rules, refer to related-apis.md - createInstance Required Parameters and Region Validation

Method 2: Using --body to specify HTTP request body (RESTful style)

# Generate idempotency token first
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch create-instance \
  --region \x3CRegionId> \
  --client-token $CLIENT_TOKEN \
  --body '{
    "esAdminPassword": "\x3CPassword>",
    "esVersion": "7.10_with_X-Pack",
    "nodeAmount": 2,
    "nodeSpec": {"disk": 20, "diskType": "cloud_ssd","spec": "elasticsearch.sn2ne.large.new"},
    "networkConfig": {"vpcId": "\x3CVpcId>","vswitchId": "\x3CVswitchId>", "vsArea": "\x3CZoneId>", "type": "vpc"},
    "paymentType": "postpaid",
    "description": "\x3CInstanceName>"
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Example: Create Single Availability Zone Instance

# Generate idempotency token (use the same token when retrying after timeout)
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch create-instance \
  --region cn-hangzhou \
  --client-token $CLIENT_TOKEN \
  --body '{
    "esAdminPassword": "YourPassword123!",
    "esVersion": "7.10_with_X-Pack",
    "nodeAmount": 2,
    "nodeSpec": {
      "disk": 20,
      "diskType": "cloud_ssd",
      "spec": "elasticsearch.sn2ne.large.new"
    },
    "networkConfig": {
      "vpcId": "vpc-bp1xxx",
      "vswitchId": "vsw-bp1xxx",
      "vsArea": "cn-hangzhou-i",
      "type": "vpc"
    },
    "paymentType": "postpaid",
    "description": "my-es-instance",
    "kibanaConfiguration": {
      "spec": "elasticsearch.sn1ne.large",
      "amount": 1,
      "disk": 0
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Example: Create Multi-Availability Zone Instance

1. For multi-AZ instances, networkConfig.vswitchId only supports the primary availability zone vSwitch, and networkConfig.vsArea only supports the primary availability zone name. Nodes will be automatically distributed to different availability zones. Do not specify availability zones and vSwitches through zoneInfos when creating, let the cloud provider allocate automatically.
2. Specify the number of availability zones through zoneCount. For multi-AZ instances, you must create master nodes.

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch create-instance \
  --region cn-hangzhou \
  --client-token $CLIENT_TOKEN \
  --body '{
    "esAdminPassword": "YourPassword123!",
    "esVersion": "7.10_with_X-Pack",
    "nodeAmount": 2,
    "nodeSpec": {
      "disk": 20,
      "diskType": "cloud_ssd",
      "spec": "elasticsearch.sn2ne.large.new"
    },
    "networkConfig": {
      "vpcId": "vpc-bp1xxx", "vswitchId": "vsw-bp1xxx", "vsArea": "cn-hangzhou-i", "type": "vpc"
    },
    "paymentType": "postpaid",
    "description": "my-es-instance",
    "zoneCount": "2",
    "kibanaConfiguration": {
      "spec": "elasticsearch.sn1ne.large",
      "amount": 1
    },
    "masterConfiguration": {
      "amount": 3,
      "disk": 20,
      "diskType": "cloud_essd",
      "spec": "elasticsearch.sn2ne.xlarge"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Error Handling

1. When an error occurs indicating that order parameters do not meet validation conditions, it may be due to incorrect data node specifications. You should prompt the user to use the correct specifications and not guess on your own. Refer to the specifications document node-specifications-by-region.md

Task 2: Describe Instance Details

⚠️ Important: Required Parameters Must Be Provided by User When querying instance details, --region and --instance-id must be explicitly provided by the user. Do not guess the region. For detailed instructions, refer to related-apis.md - DescribeInstance Required Parameters

aliyun elasticsearch describe-instance \
  --region \x3CRegionId> \
  --instance-id \x3CInstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Task 3: List Instances

⚠️ Important: Required Parameters and Parameter Validation

• The --region parameter must be explicitly provided by the user. Do not guess or use default values.
• The --status parameter only supports valid values: activating, active, inactive, invalid (case-sensitive)
• For detailed instructions, refer to related-apis.md - ListInstance Required Parameters and Parameter Validation

aliyun elasticsearch list-instance \
  --region \x3CRegionId> \
  --page 1 \
  --size 10 \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

For detailed parameters, filter examples, and response format, refer to related-apis.md - ListInstance

Task 4: Restart Instance

⚠️ CRITICAL: Pre-restart Check Requirements

Before executing a restart operation, you must first query the instance status and confirm it is active: Pre-check Rules:

• Only when the instance status is active can you execute the restart operation
• If the instance status is abnormal (such as activating, inactive, invalid, etc.), restart operation is prohibited
• If the instance status is abnormal, you should inform the user that the current status is not suitable for restart and recommend waiting for the instance to recover or contacting Alibaba Cloud technical support

Using --body to specify HTTP request body (RESTful style)

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch restart-instance \
  --region \x3CRegionId> \
  --instance-id \x3CInstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '\x3CJSON_BODY>' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Example (using --body):

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

# Normal restart
aliyun elasticsearch restart-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"restartType":"instance"}' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

# Force restart
aliyun elasticsearch restart-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"restartType":"instance","force":true}' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

# Restart specific nodes
aliyun elasticsearch restart-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"restartType":"nodeIp","nodes":["10.0.XX.XX","10.0.XX.XX"]}' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Task 5: Update Instance Configuration (Upgrade/Downgrade)

⚠️ CRITICAL: Pre-update Check Requirements

Before executing an update operation, you must first query the instance status and confirm it is active:

• Only when the instance status is active can you execute the update operation
• If the instance status is abnormal (such as activating, inactive, invalid), update operation is prohibited
• If the instance status is abnormal, inform the user that the current status is not suitable for configuration change and recommend waiting for the instance to recover

Important Constraints:

• Each update call can only change one type of node (data node, dedicated master node, cold data node, coordinating node, Kibana node, or elastic node)
• Upgrade: Cannot reduce storage size, storage type, node count, or spec CPU/memory
• Downgrade: Cannot increase storage size, storage type, node count, or spec CPU/memory. The orderActionType query parameter MUST be set to downgrade. Cannot reduce node count via this API (use ShrinkNode instead). Force change and updateType are not supported for downgrade
• Storage size reduction is not supported in either direction
• Enabled nodes cannot be disabled

For detailed API usage, parameters, and examples, refer to related-apis.md - UpdateInstance

node-specifications-by-region.md Different roles in different regions support different specifications, refer to this document.

CLI Command (using --body for RESTful HTTP body):

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch update-instance \
  --region \x3CRegionId> \
  --instance-id \x3CInstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '\x3CJSON_BODY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Example: Upgrade data node spec

CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new"}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Example: Downgrade data node spec (must set orderActionType=downgrade)

CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --order-action-type downgrade \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.large.new"}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Request Body Examples:

The following examples show the --body JSON for each common upgrade/downgrade scenario.

Note: Each call can only change one type of node. For data nodes, nodeAmount and nodeSpec are considered the same type and can be combined in one call.

Error Handling

1. When an error occurs indicating order parameters do not meet validation conditions, it may be due to incorrect node specifications. Refer to node-specifications-by-region.md
2. If the instance status is not active, prompt the user to wait for the instance to recover before retrying
3. If attempting to change multiple node types at once, inform the user that only one node type can be changed per operation

Task 6: List All Nodes (Query Cluster Node Information)

aliyun elasticsearch list-all-node \
  --region \x3CRegionId> \
  --instance-id \x3CInstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Parameters:

Example:

# List all nodes with monitoring info
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

# Query specific fields
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result[].{Host:host,Type:nodeType,Health:health,CPU:cpuPercent,Heap:heapPercent,Disk:diskUsedPercent}" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Response Fields:

Success Verification

See references/verification-method.md for detailed verification steps.

Quick Verification:

# Check instance status
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result.status" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

Expected status: active

Reference Links