Skills
skills/aliyun/alibabacloud-aiops-skills/alibabacloud-elasticsearch-instance-manage

alibabacloud-elasticsearch-instance-manage

SKILL.md

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

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

Weekly Installs
8
Repository
aliyun/alibabac…s-skills
GitHub Stars
28
First Seen
2 days ago
Security Audits
Gen Agent Trust HubPass
SocketWarn
SnykFail
Installed on
opencode8
gemini-cli8
deepagents8
antigravity8
github-copilot8
amp8