Alibabacloud Elasticsearch Instance Manage

Alibaba Cloud Elasticsearch Instance Management Skill. Use for creating, querying, listing, and restarting Elasticsearch instances on Alibaba Cloud. Triggers...

Security Scan

The skill is an instruction-only Alibaba Cloud Elasticsearch instance management guide that is internally consistent with its stated purpose and does not request unexplained credentials or install code.

Purpose & Capability

Name/description match the content: all files are documentation for using the Aliyun CLI to create, list, describe, restart, and inspect ES instances. Nothing in the bundle asks for unrelated cloud providers, binaries, or capabilities.

Instruction Scope

Runtime instructions are CLI commands (aliyun elasticsearch ...) and validation/check steps. The README explicitly requires Aliyun CLI >=3.3.1, instructs how to verify config, and forbids asking users to paste AK/SK into the conversation. The instructions do require the agent/operator to run CLI commands and to read CLI configuration state (aliyun configure list), which is appropriate for the skill's function.

Install Mechanism

No install spec or code files — instruction-only. Documentation includes recommended official download URLs for the Aliyun CLI (aliyuncli.alicdn.com) which are expected and standard for this purpose.

Credentials

The skill declares no required env vars or credentials. The docs describe standard Alibaba Cloud credential mechanisms (CLI profiles, environment variables, ECS RAM roles) and explicitly prohibit hardcoding or echoing AK/SK. The requested permissions (RAM actions listed) align with the described management operations.

Persistence & Privilege

always is false (normal). disable-model-invocation is false (default), so the agent may invoke the skill autonomously. This is expected for a management skill; however, because the skill runs CLI commands that will use whatever credentials are present on the host, install only in environments where you trust the skill and the agent.

Assessment

This skill is documentation-only and appears coherent for managing Alibaba Cloud Elasticsearch via the official Aliyun CLI. Before installing/use: ensure you have Aliyun CLI >=3.3.1 and credentials provisioned via secure methods (CLI profiles, environment variables, STS/RAM roles) — do NOT paste AK/SK into chat. Limit the RAM policy to least-privilege (only the elasticsearch actions needed, optionally VPC read permissions), and verify you trust the agent because it will execute aliyun CLI commands using whatever credentials/config exist on the host. If you need to prevent autonomous use, consider disabling model invocation for the skill or using a restricted profile before allowing operations.

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.

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

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=<your-access-key-id>
       export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-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

---

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

# 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

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,
      "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

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 <RegionId> \
  --instance-id <InstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

Example:

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

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

Example with filters:

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

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

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

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:

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

# 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

1. Always confirm parameters before executing create commands
2. Use --cli-query to filter JSON output for specific fields
3. Monitor instance status after create/restart operations
4. Set meaningful instance names using --description for easy identification
5. Use appropriate node specifications based on your workload requirements
6. Configure Kibana for visualization and management
7. Enable master nodes for production environments with 3+ data nodes
8. 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:

1. Generate unique Token before each operation: Use uuidgen to generate UUID
2. 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
3. Use different Tokens for different operations: Each independent operation requires a new clientToken, but if the user requests a retry, use the same clientToken
4. Token validity: clientToken is typically valid for 24 hours

# 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

---

Official Documentation

• Elasticsearch Product Page
• Elasticsearch API Reference
• Elasticsearch Pricing