Elasticsearch Instance Management

Manage Alibaba Cloud Elasticsearch instances: create, describe, list, restart, 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)

Prerequisites

Pre-check: Aliyun CLI >= 3.3.1 required Run
aliyun version
to verify >= 3.3.1. If not installed or version too low, see references/cli-installation-guide.md for installation instructions. Then [MUST] run
aliyun configure set --auto-plugin-install true
to enable automatic plugin installation.

bash

# Verify CLI version
aliyun version

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

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"):
STOP immediately - Do NOT execute any command
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=<your-access-key-id>
    export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

After configuration, please retry your request.
Do NOT proceed with any Alibaba Cloud operations until credentials are properly configured
Check CLI configuration:
bash
   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
```

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)

bash

# Generate idempotency token first
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch create-instance \
  --region <RegionId> \
  --client-token $CLIENT_TOKEN \
  --body '{
    "esAdminPassword": "<Password>",
    "esVersion": "7.10_with_X-Pack",
    "nodeAmount": 2,
    "nodeSpec": {
      "disk": 20,
      "diskType": "cloud_ssd",
      "spec": "elasticsearch.sn2ne.large.new"
    },
    "networkConfig": {
      "vpcId": "<VpcId>",
      "vswitchId": "<VswitchId>",
      "vsArea": "<ZoneId>",
      "type": "vpc"
    },
    "paymentType": "postpaid",
    "description": "<InstanceName>"
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Example: Create Single Availability Zone Instance

bash

# 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

Example: Create Multi-Availability Zone Instance

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.
Specify the number of availability zones through zoneCount. For multi-AZ instances, you must create master nodes.

bash

# 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,
      "disk": 0
    },
    "masterConfiguration": {
      "amount": 3,
      "disk": 20,
      "diskType": "cloud_essd",
      "spec": "elasticsearch.sn2ne.xlarge"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Error Handling

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

bash

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Example:

bash

aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

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

bash

aliyun elasticsearch list-instance \
  --region <RegionId> \
  --page 1 \
  --size 10 \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Example with filters:

bash

# List all instances
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

# Filter by status
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

# Filter by name (fuzzy match)
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --description "my-es" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

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)

bash

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch restart-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_BODY>' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Example (using --body):

bash

# 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

# 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

# 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

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

bash

aliyun elasticsearch list-all-node \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Parameters:

Parameter	Required	Description
`--instance-id`	Yes	Instance ID
`--extended`	No	Whether to return node monitoring information, default true

Example:

bash

# 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

# 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

Response Fields:

Field	Description
`host`	Node IP address
`nodeType`	Node type: MASTER/WORKER/WORKER_WARM/COORDINATING/KIBANA
`health`	Node health status: GREEN/YELLOW/RED/GRAY
`cpuPercent`	CPU usage rate
`heapPercent`	JVM memory usage rate
`diskUsedPercent`	Disk usage rate
`loadOneM`	One minute load
`zoneId`	Availability zone where the node is located
`port`	Node access port

Success Verification

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

Quick Verification:

bash

# 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

Expected status:

active

Best Practices

Always confirm parameters before executing create commands
Use
--cli-query
to filter JSON output for specific fields
Monitor instance status after create/restart operations
Set meaningful instance names using
```
--description
```
for easy identification
Use appropriate node specifications based on your workload requirements
Configure Kibana for visualization and management
Enable master nodes for production environments with 3+ data nodes
Use idempotency tokens (
```
--client-token
```
) for all write operations to enable safe retries on timeout

Idempotency Best Practices

For write operations (create, restart, delete), be sure to follow these idempotency best practices:

Generate unique Token before each operation: Use
```
uuidgen
```
to generate UUID
Reuse Token when retrying after timeout: If the request times out, retry with the same clientToken. When the user requests a retry, use the same clientToken
Use different Tokens for different operations: Each independent operation requires a new clientToken, but if the user requests a retry, use the same clientToken
Token validity: clientToken is typically valid for 24 hours

bash

# Example: Safe retry pattern
CLIENT_TOKEN=$(uuidgen)
echo "Using clientToken: $CLIENT_TOKEN"

# First attempt
aliyun elasticsearch create-instance --client-token $CLIENT_TOKEN ...

# If timeout, retry with the same Token
aliyun elasticsearch create-instance --client-token $CLIENT_TOKEN ...

Reference Links

Reference	Description
related-apis.md	API and CLI command details
ram-policies.md	RAM permission policies
verification-method.md	Verification steps
acceptance-criteria.md	Correct/incorrect patterns
cli-installation-guide.md	CLI installation guide
node-specifications-by-region.md	Node specifications by region and role

alibabacloud-elasticsearch-instance-manage

NPX Install

Tags

SKILL.md Content

Elasticsearch Instance Management

Architecture

Prerequisites

Authentication

RAM Policy

Core Workflow

Task 1: Create Elasticsearch Instance

Task 2: Describe Instance Details

Task 3: List Instances

Task 4: Restart Instance

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

Success Verification

Best Practices

Idempotency Best Practices

Reference Links

Official Documentation