Skill: sdk-team/alibabacloud-elasticsearch-instance-manage (version 0.0.3)

--- name: alibabacloud-elasticsearch-instance-manage description: | Alibaba Cloud Elasticsearch Instance Management Skill. Use for creating, querying, listing, restarting, and upgrading/downgrading Elasticsearch instances on Alibaba Cloud. Triggers: "elasticsearch", "ES instance", "elasticsearch instance", "create ES", "query ES instance", "restart ES", "ES node", "cluster node", "upgrade ES", "downgrade ES", "scale ES", "resize ES" --- # 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](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. ```bash 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 [REDACTED_SECRET]` 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=<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**: > ```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](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](references/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](references/related-apis.md#1-createinstance---create-elasticsearch-instance) **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/alibabacloud-elasticsearch-instance-manage ``` **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/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. ```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 }, "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](references/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](references/related-apis.md#2-describeinstance---query-instance-details) ```bash aliyun elasticsearch describe-instance \ --region <RegionId> \ --instance-id <InstanceId> \ --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](references/related-apis.md#3-listinstance---list-instances) ```bash aliyun elasticsearch list-instance \ --region <RegionId> \ --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](references/related-apis.md#3-listinstance---list-instances) ### 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/alibabacloud-elasticsearch-instance-manage ``` **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/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](references/related-apis.md#6-updateinstance---upgradedowngrade-instance-configuration) [node-specifications-by-region.md](references/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):** ```bash # Generate idempotency token CLIENT_TOKEN=$(uuidgen) aliyun elasticsearch update-instance \ --region <RegionId> \ --instance-id <InstanceId> \ --client-token $CLIENT_TOKEN \ --body '<JSON_BODY>' \ --connect-timeout 3 \ --read-timeout 30 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage ``` **Example: Upgrade data node spec** ```bash 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)** ```bash 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. | # | Scenario | Request Body (`--body`) | |---|----------|------------------------| | 1 | Data node disk upgrade/downgrade | `{"nodeSpec":{"disk":40}}` | | 2 | Data node spec upgrade/downgrade | `{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new"}}` | | 3 | Data node disk + spec together | `{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new","disk":40}}` | | 4 | Data node count increase/decrease | `{"nodeAmount":4}` | | 5 | Data node count + disk + spec together | `{"nodeAmount":4,"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new","disk":40}}` | | 6 | Master node spec upgrade/downgrade | `{"masterConfiguration":{"spec":"elasticsearch.sn2ne.xlarge"}}` | | 7 | Kibana node spec change | `{"kibanaConfiguration":{"spec":"elasticsearch.sn1ne.large"}}` | | 8 | Coordinating node count + spec | `{"clientNodeConfiguration":{"amount":3,"spec":"elasticsearch.sn1ne.large"}}` | | 9 | Cold node count + disk + spec | `{"warmNodeConfiguration":{"amount":3,"spec":"elasticsearch.sn1ne.large","disk":500}}` | **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](references/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) ```bash aliyun elasticsearch list-all-node \ --region <RegionId> \ --instance-id <InstanceId> \ --connect-timeout 3 \ --read-timeout 10 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage ``` **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/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:** | 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](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/alibabacloud-elasticsearch-instance-manage ``` Expected status: `active` --- ## Reference Links | Reference | Description | |-----------|-------------| | [related-apis.md](references/related-apis.md) | API and CLI command details | | [ram-policies.md](references/ram-policies.md) | RAM permission policies | | [verification-method.md](references/verification-method.md) | Verification steps | | [acceptance-criteria.md](references/acceptance-criteria.md) | Correct/incorrect patterns | | [cli-installation-guide.md](references/cli-installation-guide.md) | CLI installation guide | | [node-specifications-by-region.md](references/node-specifications-by-region.md) | Node specifications by region and role | | [Elasticsearch Product Page](https://www.aliyun.com/product/bigdata/elasticsearch) | Official product page | | [Elasticsearch API Reference](https://next.api.aliyun.com/product/elasticsearch) | Official API reference |

path: references/acceptance-criteria.md
content: # Acceptance Criteria: alibabacloud-elasticsearch-instance-manage

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

## Table of Contents

- [Correct CLI Command Patterns](#correct-cli-command-patterns)
- [Correct Common SDK Code Patterns (if applicable)](#correct-common-sdk-code-patterns-if-applicable)
- [Response Validation Criteria](#response-validation-criteria)
- [Security Criteria](#security-criteria)
- [References](#references)

---

## Correct CLI Command Patterns

### 1. Product — verify product name exists

#### ✅ CORRECT
```bash
aliyun elasticsearch create-instance ...
aliyun elasticsearch describe-instance ...
aliyun elasticsearch list-instance ...
aliyun elasticsearch restart-instance ...
aliyun elasticsearch update-instance ...
```

#### ❌ INCORRECT
```bash
aliyun es create-instance ...              # Wrong: product name is "elasticsearch" not "es"
aliyun Elasticsearch create-instance ...   # Wrong: product name must be lowercase
aliyun elastic create-instance ...         # Wrong: incomplete product name
```

---

### 2. Command — verify action exists under the product

#### ✅ CORRECT
```bash
aliyun elasticsearch create-instance      # Use kebab-case
aliyun elasticsearch describe-instance    # Use kebab-case
aliyun elasticsearch list-instance        # Use kebab-case
aliyun elasticsearch restart-instance     # Use kebab-case
aliyun elasticsearch update-instance      # Use kebab-case
```

#### ❌ INCORRECT
```bash
aliyun elasticsearch CreateInstance       # Wrong: use kebab-case, not PascalCase
aliyun elasticsearch createInstance       # Wrong: use kebab-case, not camelCase
aliyun elasticsearch create_instance      # Wrong: use kebab-case, not snake_case
aliyun elasticsearch createinstance       # Wrong: words must be separated by hyphens
```

---

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

#### ✅ CORRECT - create-instance
```bash
aliyun elasticsearch create-instance \
  --region cn-hangzhou \
  --es-admin-password "YourPassword123!" \
  --es-version "7.10_with_X-Pack" \
  --node-amount 2 \
  --network-config 'vpcId=vpc-xxx vswitchId=vsw-xxx vsArea=cn-hangzhou-i type=vpc' \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT - create-instance
```bash
aliyun elasticsearch create-instance \
  --password "xxx"           # Wrong: should be --es-admin-password
  --version "7.10"           # Wrong: should be --es-version
  --nodeAmount 2             # Wrong: should be --node-amount (kebab-case)
  --networkConfig '{...}'    # Wrong: should be --network-config (kebab-case)
```

#### ✅ CORRECT - describe-instance
```bash
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT - describe-instance
```bash
aliyun elasticsearch describe-instance \
  --instanceId es-cn-xxx****   # Wrong: should be --instance-id (kebab-case)
  --InstanceId es-cn-xxx****   # Wrong: should be --instance-id (kebab-case, lowercase)
```

#### ✅ CORRECT - list-instance
```bash
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --page 1 \
  --size 10 \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT - list-instance
```bash
aliyun elasticsearch list-instance \
  --pageNumber 1   # Wrong: should be --page
  --pageSize 10    # Wrong: should be --size
```

#### ✅ CORRECT - restart-instance
```bash
aliyun elasticsearch restart-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --force true \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT - restart-instance
```bash
aliyun elasticsearch restart-instance \
  --instanceId es-cn-xxx****   # Wrong: should be --instance-id
  --Force true                  # Wrong: should be --force (lowercase)
```

#### ✅ CORRECT - list-all-node
```bash
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --user-agent AlibabaCloud-Agent-Skills

# With extended parameter
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --extended false \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT - list-all-node
```bash
aliyun elasticsearch list-all-node \
  --instanceId es-cn-xxx****   # Wrong: should be --instance-id
  --Extended true               # Wrong: should be --extended (lowercase)

aliyun elasticsearch listAllNode \
  --instance-id es-cn-xxx****   # Wrong: command should be list-all-node (kebab-case)
```

#### ✅ CORRECT - update-instance
```bash
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $(uuidgen) \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new"}}' \
  --user-agent AlibabaCloud-Agent-Skills

# Downgrade with orderActionType
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $(uuidgen) \
  --order-action-type downgrade \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.large.new"}}' \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT - update-instance
```bash
aliyun elasticsearch update-instance \
  --instanceId es-cn-xxx****   # Wrong: should be --instance-id (kebab-case)

aliyun elasticsearch update-instance \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new"},"warmNodeConfiguration":{"amount":3}}'   # Wrong: cannot change multiple node types in one call

aliyun elasticsearch update-instance \
  --order-action-type downgrade \
  --body '{"nodeAmount":2}'   # Wrong: cannot reduce node count via UpdateInstance, use ShrinkNode
```

---

### 4. User-Agent — every command must include user-agent

#### ✅ CORRECT
```bash
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills
```

#### ❌ INCORRECT
```bash
aliyun elasticsearch list-instance \
  --region cn-hangzhou
  # Missing: --user-agent AlibabaCloud-Agent-Skills
```

---

### 5. Parameter Values — verify format requirements

#### ✅ CORRECT - network-config format
```bash
# Format 1: key=value pairs
--network-config 'vpcId=vpc-xxx vswitchId=vsw-xxx vsArea=cn-hangzhou-i type=vpc'

# Format 2: JSON string
--network-config '{"vpcId":"vpc-xxx","vswitchId":"vsw-xxx","vsArea":"cn-hangzhou-i","type":"vpc"}'
```

#### ❌ INCORRECT - network-config format
```bash
# Wrong: missing required fields
--network-config 'vpcId=vpc-xxx'

# Wrong: incorrect field names
--network-config 'vpc_id=vpc-xxx vswitch_id=vsw-xxx'
```

#### ✅ CORRECT - es-version format
```bash
--es-version "7.10_with_X-Pack"
--es-version "8.5.1_with_X-Pack"
--es-version "6.7_with_X-Pack"
```

#### ❌ INCORRECT - es-version format
```bash
--es-version "7.10"           # Wrong: missing "_with_X-Pack"
--es-version "7.10-X-Pack"    # Wrong: incorrect format
```

#### ✅ CORRECT - payment-type values
```bash
--payment-type postpaid    # Pay-as-you-go
--payment-type prepaid     # Subscription
```

#### ❌ INCORRECT - payment-type values
```bash
--payment-type PayAsYouGo       # Wrong: should be "postpaid"
--payment-type Subscription     # Wrong: should be "prepaid"
```

---

## Correct Common SDK Code Patterns (if applicable)

### 1. Import Patterns

#### ✅ CORRECT
```python
from alibabacloud_tea_openapi.client import Client as OpenApiClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_util import models as util_models
```

#### ❌ INCORRECT
```python
from aliyunsdkcore.client import AcsClient           # Wrong: old SDK
from aliyunsdkelasticsearch.request import ...        # Wrong: product-specific SDK not recommended
```

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

#### ✅ CORRECT
```python
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_openapi import models as open_api_models

# Use CredentialClient for automatic credential management
credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = "elasticsearch.cn-hangzhou.aliyuncs.com"
```

#### ❌ INCORRECT
```python
# NEVER hardcode credentials
config = open_api_models.Config(
    [REDACTED_SECRET]",          # FORBIDDEN
    [REDACTED_SECRET]"       # FORBIDDEN
)
```

### 3. Client Initialization

#### ✅ CORRECT
```python
from alibabacloud_tea_openapi.client import Client as OpenApiClient

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

---

## Response Validation Criteria

### create-instance Response
✅ Must contain:
- `RequestId` (string)
- `Result.instanceId` (string matching pattern `es-cn-*`)

### describe-instance Response
✅ Must contain:
- `RequestId` (string)
- `Result.instanceId` (string)
- `Result.status` (string: active|activating|inactive|invalid)
- `Result.esVersion` (string)

### list-instance Response
✅ Must contain:
- `RequestId` (string)
- `Headers.X-Total-Count` (integer)
- `Result` (array of instance objects)

### restart-instance Response
✅ Must contain:
- `RequestId` (string)
- `Result.instanceId` (string)

### update-instance Response
✅ Must contain:
- `RequestId` (string)
- `Result.instanceId` (string)
- `Result.status` (string, expected `activating` after successful update)

---

## Security Criteria

### ✅ CORRECT Security Practices
1. Use `aliyun configure list` to verify credentials (never echo AK/SK)
2. Use CredentialClient for SDK authentication
3. Use environment variables for sensitive data
4. Include `--user-agent AlibabaCloud-Agent-Skills` in all commands

### ❌ INCORRECT Security Practices
1. Hardcoding access keys in code or commands
2. Printing or echoing credential values
3. Using `aliyun configure set` with literal credential values in automated scripts

---

## References

- [Elasticsearch CLI Help](aliyun elasticsearch --help)
- [Alibaba Cloud CLI Documentation](https://help.aliyun.com/zh/cli/)
- [Elasticsearch API Reference](https://next.api.aliyun.com/product/elasticsearch)


path: references/cli-installation-guide.md
content: # 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.

## Table of Contents

- [Installation](#installation)
  - [macOS](#macos)
  - [Linux](#linux)
  - [Windows](#windows)
- [Configuration](#configuration)
  - [Quick Start](#quick-start)
  - [Configuration Modes](#configuration-modes)
  - [Environment Variables](#environment-variables)
  - [Managing Multiple Profiles](#managing-multiple-profiles)
  - [Credential Priority](#credential-priority)
- [Verification](#verification)
  - [Test Authentication](#test-authentication)
  - [Debug Configuration](#debug-configuration)
- [Security Best Practices](#security-best-practices)
- [Troubleshooting](#troubleshooting)
- [Advanced Configuration](#advanced-configuration)
  - [Custom Endpoint](#custom-endpoint)
  - [Proxy Settings](#proxy-settings)
  - [Timeout Settings](#timeout-settings)
- [Next Steps](#next-steps)
- [References](#references)

---

## Installation

### macOS

**Using Homebrew (Recommended)**
```bash
brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version
```

**Using Binary**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```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

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 several authentication modes. For security reasons, credential configuration is not shown in this guide. Please refer to the [official Aliyun CLI documentation](https://help.aliyun.com/zh/cli/) for secure credential setup.

**Available Authentication Modes:**

| Mode | Description | Use Case |
|------|-------------|----------|
| `AK` | Access Key authentication | General purpose |
| `StsToken` | Temporary credentials with STS token | CI/CD pipelines, temporary access |
| `RamRoleArn` | Assume RAM role | Cross-account access, elevated privileges |
| `EcsRamRole` | ECS instance RAM role | Scripts running on ECS instances |
| `RsaKeyPair` | RSA key pair authentication | Special authentication scenarios |
| `RamRoleArnWithEcs` | ECS + RAM role combination | Cross-account from ECS |

**Configure using interactive mode (recommended):**
```bash
aliyun configure
```

This will prompt you to enter credentials securely without exposing them in command history.

### Environment Variables

Environment variables provide the **highest priority** credential source and override config file settings.

**Supported Environment Variables:**

| Variable | Purpose |
|----------|---------|
| `ALIBABA_CLOUD_ACCESS_KEY_ID` | Access Key ID |
| `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | Access Key Secret |
| `ALIBABA_CLOUD_SECURITY_TOKEN` | STS Token (for temporary credentials) |
| `ALIBABA_CLOUD_REGION_ID` | Default region |
| `ALIBABA_CLOUD_ECS_METADATA` | ECS RAM Role name |
| `ALIBABA_CLOUD_PROFILE` | Profile name to use |

> **Security Best Practices:**
> - Set environment variables in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or CI/CD secret stores
> - NEVER commit credentials to version control
> - NEVER echo or print environment variable values
> - Use your shell's secure credential management or CI/CD secret stores

**Use Cases:**
- CI/CD pipelines (via secret environment variables)
- Docker containers
- Temporary credential override

### Managing Multiple Profiles

**Create Named Profiles**

Use interactive mode to create profiles securely:
```bash
# Create a new profile
aliyun configure --profile projectA

# Or use the set command with --mode only, then configure credentials interactively
aliyun configure set --profile projectA --mode AK --region cn-hangzhou
# Then run 'aliyun configure' to set credentials
```

> **Security Note**: Avoid using `--access-key-id` and `--access-key-secret` flags in commands as they may be recorded in shell history. Use interactive mode instead.

**Use Specific Profile**

```bash
aliyun ecs describe-instances --profile projectA

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

**List and Switch Profiles**

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

```bash
# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions
```

**If successful**, you'll see:
```json
{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "China East 1 (Hangzhou)"
      },
      ...
    ]
  },
  "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

```bash
# 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

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

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

### 3. Rotate Access Keys Regularly

1. Create new access key in [RAM Console](https://ram.console.aliyun.com/manage/ak)
2. Update configuration using interactive mode:
   ```bash
   aliyun configure
   ```
3. Delete old access key from console

> **Security Note**: Use interactive mode (`aliyun configure`) to avoid exposing credentials in shell history.

### 4. Use STS Tokens for Temporary Access

Configure STS Token mode interactively:
```bash
aliyun configure --mode StsToken
```

Or use environment variables for temporary credentials in CI/CD pipelines.

### 5. Use ECS RAM Roles When Possible

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

### 6. Never Commit Credentials

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

# Use environment variables in CI/CD instead
```

### 7. Secure Config File

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

## Troubleshooting

### Issue: Command Not Found

```bash
# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH
```

### Issue: Authentication Failed

```bash
# 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

```bash
# Error: Forbidden.RAM

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

### Issue: STS Token Expired

```bash
# Error: InvalidSecurityToken.Expired

# Reconfigure with new token using interactive mode
aliyun configure --mode StsToken
```

> **Security Note**: Use interactive mode to avoid exposing credentials in shell history.

### Issue: Wrong Region

```bash
# 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

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

### Proxy Settings

```bash
# 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

```bash
# 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):
   ```bash
   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote
   ```

2. **Explore commands**:
   ```bash
   aliyun ecs --help
   aliyun fc --help
   ```

3. **Read documentation**:
   - [Command Syntax Guide](./command-syntax.md)
   - [Global Flags Reference](./global-flags.md)
   - [Common Scenarios](./common-scenarios.md)

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


path: references/node-specifications-by-region.md
content: # Elasticsearch Node Specifications and Region Support

This document describes the specification types supported by different node roles in Alibaba Cloud Elasticsearch, as well as regional support information, for reference when creating instances.

> **Important Note**: Different regions support different specifications. Please refer to the purchase page for specific details. The following specification information is for reference only. When actually creating instances, please refer to the available specifications on the Alibaba Cloud console purchase page or those returned by the API.

## Table of Contents

- [Node Role Description](#node-role-description)
- [Data Node Specifications](#data-node-specifications)
- [Dedicated Master Node Specifications](#dedicated-master-node-specifications)
- [Kibana Node Specifications](#kibana-node-specifications)
- [Coordinating Node Specifications](#coordinating-node-specifications)
- [Cold Data Node (Warm Node) Specifications](#cold-data-node-warm-node-specifications)
- [Specification Selection Recommendations for Creating Instances](#specification-selection-recommendations-for-creating-instances)
- [Related Documentation](#related-documentation)

---

## Node Role Description

| Node Role | Description | Required |
|---------|------|--------|
| Data Node | Stores index data, executes CRUD operations, aggregations, etc. | Yes |
| Dedicated Master Node | Manages cluster operations such as creating/deleting indices, allocating shards, etc. | Recommended for production |
| Kibana Node | Provides Kibana visualization interface | Yes (default 1 core 2G included) |
| Coordinating Node | Offloads CPU overhead from data nodes, suitable for CPU-intensive workloads | Optional |
| Cold Data Node (Warm Node) | Stores infrequently accessed historical data, enables hot-cold separation | Optional |

---

## Data Node Specifications


### New Generation Cloud Disk Specifications -- Recommended
Beijing, Shanghai, Hangzhou, Shenzhen, Zhangjiakou do not support cloud disk specifications, use new generation cloud disk specifications instead
| Spec Code | CPU and Memory |
|---------|----------|
| `elasticsearch.sn1ne.large.new` | 2 cores 4 GiB |
| `elasticsearch.sn1ne.xlarge.new` | 4 cores 8 GiB |
| `elasticsearch.sn1ne.2xlarge.new` | 8 cores 16 GiB |
| `elasticsearch.sn1ne.4xlarge.new` | 16 cores 32 GiB |
| `elasticsearch.sn1ne.8xlarge.new` | 32 cores 64 GiB |
| `elasticsearch.sn2ne.large.new` | 2 cores 8 GiB |
| `elasticsearch.sn2ne.xlarge.new` | 4 cores 16 GiB |
| `elasticsearch.sn2ne.2xlarge.new` | 8 cores 32 GiB |
| `elasticsearch.sn2ne.4xlarge.new` | 16 cores 64 GiB |
| `elasticsearch.turbo1.ga.large` | 2 cores 8 GiB |
| `elasticsearch.turbo1.ga.xlarge` | 4 cores 16 GiB |
| `elasticsearch.turbo1.ga.2xlarge` | 8 cores 32 GiB |
| `elasticsearch.turbo1.ga.4xlarge` | 16 cores 64 GiB |
| `elasticsearch.turbo1.ga.8xlarge` | 32 cores 128 GiB |
| `elasticsearch.turbo1.ca.large` | 2 cores 4 GiB |
| `elasticsearch.turbo1.ca.xlarge` | 4 cores 8 GiB |
| `elasticsearch.turbo1.ca.2xlarge` | 8 cores 16 GiB |
| `elasticsearch.turbo1.ca.4xlarge` | 16 cores 32 GiB |
| `elasticsearch.turbo1.ca.8xlarge` | 32 cores 64 GiB |
| `elasticsearch.turbo1.ca.16xlarge` | 64 cores 128 GiB |


### Cloud Disk Specifications
Beijing, Shanghai, Hangzhou, Shenzhen, Zhangjiakou do not support cloud disk specifications

| Spec Code | CPU and Memory |
|---------|----------|
| `elasticsearch.sn1ne.large` | 2 cores 4 GiB |
| `elasticsearch.sn1ne.xlarge` | 4 cores 8 GiB |
| `elasticsearch.sn1ne.2xlarge` | 8 cores 16 GiB |
| `elasticsearch.sn1ne.4xlarge` | 16 cores 32 GiB |
| `elasticsearch.sn1ne.8xlarge` | 32 cores 64 GiB |
| `elasticsearch.sn2ne.large` | 2 cores 8 GiB |
| `elasticsearch.sn2ne.xlarge` | 4 cores 16 GiB |
| `elasticsearch.sn2ne.2xlarge` | 8 cores 32 GiB |
| `elasticsearch.sn2ne.4xlarge` | 16 cores 64 GiB |
| `elasticsearch.sn2ne.8xlarge` | 32 cores 128 GiB |


---

## Dedicated Master Node Specifications

Dedicated master nodes are used for cluster management operations, recommended for production environments.

### Specification Features
- Default count is 3, cannot be changed
- Default storage space is 20 GiB, cannot be changed

### New Generation Cloud Disk Specifications

Applicable to Beijing, Shanghai, Hangzhou, Shenzhen regions

| Spec Code | CPU and Memory |
|---------|----------|
| `elasticsearch.sn1ne.large.new` | 2 cores 4 GiB |
| `elasticsearch.sn1ne.xlarge.new` | 4 cores 8 GiB |
| `elasticsearch.sn1ne.2xlarge.new` | 8 cores 16 GiB |
| `elasticsearch.sn1ne.4xlarge.new` | 16 cores 32 GiB |
| `elasticsearch.sn1ne.8xlarge.new` | 32 cores 64 GiB |
| `elasticsearch.sn2ne.large.new` | 2 cores 8 GiB |
| `elasticsearch.sn2ne.xlarge.new` | 4 cores 16 GiB |
| `elasticsearch.sn2ne.2xlarge.new` | 8 cores 32 GiB |
| `elasticsearch.sn2ne.4xlarge.new` | 16 cores 64 GiB |

### Cloud Disk Specifications

Applicable to Zhangjiakou, Chengdu, Guangzhou, Ulanqab, Qingdao, Hong Kong, and other regions

| Spec Code | CPU and Memory |
|---------|----------|
| `elasticsearch.sn1ne.large` | 2 cores 4 GiB |
| `elasticsearch.sn1ne.xlarge` | 4 cores 8 GiB |
| `elasticsearch.sn1ne.2xlarge` | 8 cores 16 GiB |
| `elasticsearch.sn1ne.4xlarge` | 16 cores 32 GiB |
| `elasticsearch.sn1ne.8xlarge` | 32 cores 64 GiB |
| `elasticsearch.sn2ne.large` | 2 cores 8 GiB |
| `elasticsearch.sn2ne.xlarge` | 4 cores 16 GiB |
| `elasticsearch.sn2ne.2xlarge` | 8 cores 32 GiB |
| `elasticsearch.sn2ne.4xlarge` | 16 cores 64 GiB |

### Storage Type Support
- ESSD Cloud Disk (default)
- SSD Cloud Disk

---

## Kibana Node Specifications

Kibana nodes are used to provide the visualization interface.

### Specification Features
- Enabled by default, cannot be disabled
- Production environments recommend 2 cores 4 GiB or higher

### Common Specification Reference

| Spec Code | CPU and Memory | Use Case |
|---------|----------|--------|
| `elasticsearch.sn1ne.large` | 2 cores 4 GiB | Production recommended |
| `elasticsearch.sn1ne.xlarge` | 4 cores 8 GiB | Large-scale clusters |
| `elasticsearch.sn2ne.large` | 2 cores 8 GiB | Production recommended |
| `elasticsearch.sn2ne.xlarge` | 4 cores 16 GiB | Large-scale clusters |
| `elasticsearch.sn2ne.2xlarge` | 8 cores 32 GiB | Large-scale clusters |

---

## Coordinating Node Specifications

Coordinating nodes are used to offload CPU overhead from data nodes, suitable for CPU-intensive workloads (such as large aggregation queries).

### Specification Features
- Optional node type
- Storage space defaults to 20 GiB, cannot be changed
- Currently only supports Ultra Cloud Disk
- The number of nodes purchased must be a multiple of the number of availability zones

### Common Specification Reference

| Spec Code | CPU and Memory |
|---------|----------|
| `elasticsearch.sn1ne.large` | 2 cores 4 GiB |
| `elasticsearch.sn1ne.xlarge` | 4 cores 8 GiB |
| `elasticsearch.sn1ne.2xlarge` | 8 cores 16 GiB |
| `elasticsearch.sn1ne.4xlarge` | 16 cores 32 GiB |
| `elasticsearch.sn1ne.8xlarge` | 32 cores 64 GiB |
| `elasticsearch.sn2ne.large` | 2 cores 8 GiB |
| `elasticsearch.sn2ne.xlarge` | 4 cores 16 GiB |
| `elasticsearch.sn2ne.2xlarge` | 8 cores 32 GiB |
| `elasticsearch.sn2ne.4xlarge` | 16 cores 64 GiB |

---

## Cold Data Node (Warm Node) Specifications

Cold data nodes are used to store infrequently accessed historical data, enabling hot-cold data separation.

### Specification Features
- Optional node type
- Minimum storage space is 500 GiB
- Supports Ultra Cloud Disk
- The number of nodes purchased must be a multiple of the number of availability zones

### Common Specification Reference

| Spec Code | CPU and Memory |
|---------|----------|
| `elasticsearch.sn1ne.large` | 2 cores 4 GiB |
| `elasticsearch.sn1ne.xlarge` | 4 cores 8 GiB |
| `elasticsearch.sn1ne.2xlarge` | 8 cores 16 GiB |
| `elasticsearch.sn1ne.4xlarge` | 16 cores 32 GiB |
| `elasticsearch.sn1ne.8xlarge` | 32 cores 64 GiB |
| `elasticsearch.sn2ne.large` | 2 cores 8 GiB |
| `elasticsearch.sn2ne.xlarge` | 4 cores 16 GiB |
| `elasticsearch.sn2ne.2xlarge` | 8 cores 32 GiB |
| `elasticsearch.sn2ne.4xlarge` | 16 cores 64 GiB |

---


## Specification Selection Recommendations for Creating Instances

### Data Node Selection

| Scenario | Recommended Spec Family | Recommended Specification |
|------|-----------|--------|
| Small Application | Cloud Disk 1:2 | `elasticsearch.sn1ne.xlarge.new` (4 cores 8 GiB) |
| Medium Application | Cloud Disk 1:4 | `elasticsearch.sn2ne.xlarge.new` (4 cores 16 GiB) |
| Large Application | Cloud Disk 1:4/1:8 | `elasticsearch.sn2ne.2xlarge.new` (8 cores 32 GiB) and above |
| Memory-intensive | Cloud Disk 1:8 | `elasticsearch.r5.2xlarge` (8 cores 64 GiB) and above |

### Dedicated Master Node Selection

- Data nodes ≤ 10: 2 cores 4 GiB or 2 cores 8 GiB
- Data nodes > 10: Recommend 4 cores 16 GiB and above

### Kibana Node Selection

- Production environment: Recommend 2 cores 4 GiB and above

---


## Related Documentation

- [Elasticsearch Node Specifications Official Documentation](https://help.aliyun.com/zh/es/product-overview/node-specifications)
- [ES Instance Node Configuration Instructions](https://help.aliyun.com/zh/es/user-guide/purchase-page-parameters)
- [Create Elasticsearch Instance API](https://next.api.aliyun.com/api/elasticsearch/2017-06-13/createinstance)


path: references/ram-policies.md
content: # RAM Policies - Elasticsearch Instance Management

This document lists the RAM (Resource Access Management) permissions required for Elasticsearch instance management operations.

## Table of Contents

- [Required Permissions Overview](#required-permissions-overview)
- [Minimum Required Policy](#minimum-required-policy)
- [Resource-Level Policy (Recommended)](#resource-level-policy-recommended)
- [Region-Specific Policy](#region-specific-policy)
- [Read-Only Policy](#read-only-policy)
- [Full Management Policy](#full-management-policy)
- [Additional Permissions for VPC Resources](#additional-permissions-for-vpc-resources)
- [System Policies](#system-policies)
  - [Attach System Policy via CLI](#attach-system-policy-via-cli)
- [Policy Best Practices](#policy-best-practices)
- [References](#references)

---

## Required Permissions Overview

| API Action | Required Permission | Description |
|------------|---------------------|-------------|
| createInstance | `elasticsearch:CreateInstance` | Create Elasticsearch Instance |
| DescribeInstance | `elasticsearch:DescribeInstance` | Query Instance Details |
| ListInstance | `elasticsearch:ListInstance` | List Instances |
| ListAllNode | `elasticsearch:ListAllNode` | Query Cluster Node Information |
| RestartInstance | `elasticsearch:RestartInstance` | Restart Instance |
| UpdateInstance | `elasticsearch:UpdateInstance` | Upgrade/Downgrade Instance Configuration |

---

## Minimum Required Policy

The following policy grants the minimum permissions needed for Elasticsearch instance management:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance",
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:ListAllNode",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance"
      ],
      "Resource": "*"
    }
  ]
}
```

---

## Resource-Level Policy (Recommended)

For better security, restrict permissions to specific resources:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance"
      ],
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}
```

---

## Region-Specific Policy

Restrict operations to specific regions:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance",
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance"
      ],
      "Resource": "acs:elasticsearch:cn-hangzhou:*:instances/*"
    }
  ]
}
```

---

## Read-Only Policy

For users who only need to view instance information:

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

---

## Additional Permissions for VPC Resources

When creating Elasticsearch instances, you may also need VPC-related permissions:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance",
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeVSwitches"
      ],
      "Resource": "*"
    }
  ]
}
```

---

## System Policies

Alibaba Cloud provides built-in system policies for Elasticsearch:

| Policy Name | Description |
|-------------|-------------|
| `AliyunElasticsearchFullAccess` | Full Management Permissions |
| `AliyunElasticsearchReadOnlyAccess` | Read-Only Permissions |

### Attach System Policy via CLI

```bash
# Attach full access policy to RAM user
aliyun ram attach-policy-to-user \
  --policy-type System \
  --policy-name AliyunElasticsearchFullAccess \
  --user-name <UserName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

# Attach read-only policy to RAM user
aliyun ram attach-policy-to-user \
  --policy-type System \
  --policy-name AliyunElasticsearchReadOnlyAccess \
  --user-name <UserName> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

---

## Policy Best Practices

1. **Principle of Least Privilege**: Grant only the minimum permissions required
2. **Use Resource-Level Restrictions**: Restrict to specific instances when possible
3. **Separate Read and Write**: Use different policies for different operation types
4. **Regular Auditing**: Review and audit permissions periodically
5. **Use RAM Roles**: For applications, use RAM roles instead of hardcoded credentials

---

## References

- [Elasticsearch RAM Policies](https://help.aliyun.com/document_detail/187755.html)
- [RAM Policy Structure](https://help.aliyun.com/document_detail/93739.html)
- [RAM Console](https://ram.console.aliyun.com/)


path: references/related-apis.md
content: # Related APIs - Elasticsearch Instance Management

This document lists all CLI commands and APIs used in the Elasticsearch Instance Management Skill.

## Table of Contents

- [API Overview](#api-overview)
  - [Using --body Parameter](#using---body-parameter)
- [API Details](#api-details)
  - [1. createInstance - Create Elasticsearch Instance](#1-createinstance---create-elasticsearch-instance)
  - [2. DescribeInstance - Query Instance Details](#2-describeinstance---query-instance-details)
  - [3. ListInstance - List Instances](#3-listinstance---list-instances)
  - [4. RestartInstance - Restart Instance](#4-restartinstance---restart-instance)
  - [5. ListAllNode - Query Cluster Node Information](#5-listallnode---query-cluster-node-information)
  - [6. UpdateInstance - Upgrade/Downgrade Instance Configuration](#6-updateinstance---upgradedowngrade-instance-configuration)
- [Instance Status Reference](#instance-status-reference)
- [Elasticsearch Version Reference](#elasticsearch-version-reference)
- [Official Documentation](#official-documentation)

---

## API Overview

> **Note on API Style:** Elasticsearch APIs use **ROA (RESTful)** style. This means:
> - Parameters can be passed via `--body` as a JSON string representing the HTTP request body
> - Alternatively, individual flags can be used for simple parameters
> - The `--body` approach is useful for complex nested structures or when you have a ready-to-use JSON payload

### Using `--body` Parameter

The `--body` parameter allows you to specify the HTTP request body as a JSON string for RESTful API calls:

```bash
aliyun elasticsearch <command> \
  --region <RegionId> \
  --body '<JSON_PAYLOAD>' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Example:**
```bash
aliyun elasticsearch create-instance \
  --region cn-hangzhou \
  --body '{
    "esAdminPassword": "YourPassword123!",
    "esVersion": "7.10_with_X-Pack",
    "nodeAmount": 2,
    "networkConfig": {
      "vpcId": "vpc-bp1xxx",
      "vswitchId": "vsw-bp1xxx",
      "type": "vpc"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Tips:**
- Use `--body $(cat payload.json)` to read from a file
- For complex nested objects, `--body` is often more readable than multiple flags
- Both `--body` and individual flags can be used together (flags take precedence)

| Product | CLI Command | API Action | Description |
|---------|------------|------------|-------------|
| Elasticsearch | `aliyun elasticsearch create-instance` | createInstance | Create Elasticsearch Instance |
| Elasticsearch | `aliyun elasticsearch describe-instance` | DescribeInstance | Query Instance Details |
| Elasticsearch | `aliyun elasticsearch list-instance` | ListInstance | List ES Instances in a Region |
| Elasticsearch | `aliyun elasticsearch list-all-node` | ListAllNode | Query All Cluster Node Information |
| Elasticsearch | `aliyun elasticsearch restart-instance` | RestartInstance | Restart Elasticsearch Cluster |
| Elasticsearch | `aliyun elasticsearch update-instance` | UpdateInstance | Upgrade/Downgrade Instance Configuration |

---

## API Details

> **Idempotency:** For write operations (createInstance, RestartInstance, UpdateInstance), you **MUST** use the `--client-token` parameter to ensure idempotency for safe retries when requests time out.

### 1. createInstance - Create Elasticsearch Instance

> **⚠️ CRITICAL: Required Parameters and Region Validation**
>
> **1. region Parameter (Required and Must Be Validated)**
>
> The `--region` parameter **MUST be explicitly provided by the user**. Agents **MUST NOT guess or use default values**.
>
> **Pre-execution Check Steps:**
> 1. Check if the user has provided the `--region` parameter
> 2. If region is missing, **immediately ask the user**:
>    ```
>    Please provide the region where the instance is located, e.g., cn-hangzhou, cn-shanghai, cn-beijing, etc.
>    ```
> 3. If the user has provided a region, **validate its legitimacy**:
>    - Valid Alibaba Cloud region format starts with `cn-` or `ap-` prefix
>    - Common valid regions: `cn-hangzhou`, `cn-shanghai`, `cn-beijing`, `cn-shenzhen`, `cn-zhangjiakou`, `cn-hongkong`, `ap-southeast-1`, etc.
> 4. If the region is obviously invalid (e.g., empty string, pure numbers, contains special characters), **prompt the user**:
>    ```
>    The provided region "{region}" does not appear to be a valid Alibaba Cloud region.
>    Please provide a valid region ID, e.g., cn-hangzhou, cn-shanghai, cn-beijing, etc.
>    ```
>
> **Prohibited Behaviors:**
> - ❌ Do NOT use a default region (such as cn-hangzhou) to replace the user-specified region
> - ❌ Do NOT assume the user wants to create an instance in a specific region
>
> ---
>
> **2. Other Required Parameters**
>
> When creating an ES instance, the following parameters **MUST be explicitly provided by the user**. Agents **MUST NOT guess or fabricate** these values:
>
> | Parameter | Description | Example |
> |------|------|------|
> | `esAdminPassword` | Instance admin password | `YourPassword123!` |
> | `vpcId` | VPC Network ID | `vpc-bp1xxx` |
> | `vswitchId` | VSwitch ID | `vsw-bp1xxx` |
> | `vsArea` | Availability Zone ID | `cn-hangzhou-i` |
> | `paymentType` | Payment type (`postpaid` or `prepaid`) | `postpaid` |
>
> **Pre-execution Check Steps:**
> 1. Check if the user has provided all required parameters above
> 2. If any are missing, **immediately stop and prompt the user to provide**, in this format:
>    ```
>    The following parameters are required to create an ES instance, please provide:
>    - [ ] Instance password (esAdminPassword): ___
>    - [ ] VPC ID (vpcId): ___
>    - [ ] VSwitch ID (vswitchId): ___
>    - [ ] Availability Zone (vsArea): ___
>    - [ ] Payment Type (paymentType): postpaid/prepaid
>    ```
> 3. Wait for the user to explicitly provide before continuing with the create command
>
> **Prohibited Behaviors:**
> - ❌ Do NOT use example values as actual parameters
> - ❌ Do NOT guess vsArea based on region
> - ❌ Do NOT use default passwords or fabricate passwords
> - ❌ Do NOT assume the user's VPC or vswitch ID

**API Style:** ROA (RESTful)


**CLI Command (using --body for RESTful HTTP body):**
```bash
# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun elasticsearch create-instance \
  --region <RegionId> \
  --client-token $CLIENT_TOKEN \
  --body '{
    "esAdminPassword": "<Password>",
    "esVersion": "<Version>",
    "nodeAmount": <NodeCount>,
    "nodeSpec": {
      "disk": <DiskSize>,
      "diskType": "<DiskType>",
      "spec": "<Spec>"
    },
    "networkConfig": {
      "vpcId": "<VpcId>",
      "vswitchId": "<VswitchId>",
      "vsArea": "<ZoneId>",
      "type": "vpc"
    },
    "paymentType": "<postpaid|prepaid>"
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Required Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--es-admin-password` | string | Instance access password, must contain at least 3 of: uppercase letters, lowercase letters, numbers, special characters, length 8~32 |
| `--es-version` | string | Instance version, e.g., `7.10_with_X-Pack`, `7.16_with_X-Pack`, `8.5.1_with_X-Pack`, `8.15.1_with_X-Pack`, `8.17.0_with_X-Pack` |
| `--node-amount` | int | Number of data nodes, range 2~50 |
| `--network-config` | object | Network configuration, including vpcId, vswitchId, vsArea, type |
| `--client-token` | string | Idempotency token for safe retries, UUID format |


**networkConfig Parameter Format**
```json
{
    "networkConfig": {
      "vpcId": "<VpcId>",
      "vswitchId": "<VswitchId>",
      "vsArea": "<ZoneId>",
      "type": "vpc"
    }
}
```
Parameter type is fixed to vpc

Parameter vswitchId: Only supports one vswitchId. For multi-AZ instances, only one vswitchId needs to be provided.

Parameter vsArea: The availability zone where the vswitchId is located, only supports one.

Note: For multi-AZ instances, only the primary availability zone's vswitchId needs to be provided.


**Optional Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--node-spec` | object | Data node configuration: spec, disk (size in GB), diskType |
| `--payment-type` | string | Payment type: `postpaid` (pay-as-you-go), `prepaid` (subscription) |
| `--kibana-configuration` | object | Kibana node configuration |
| `--master-configuration` | object | Dedicated master node configuration |
| `--description` | string | Instance name |
| `--zone-count` | int | Number of availability zones, options: 1, 2, 3 |

**Response:**
```json
{
  "RequestId": "838D9D11-8EEF-46D8-BF0D-BC8FC2B0C2F3",
  "Result": {
    "instanceId": "es-cn-xxx****"
  }
}
```

---

### 2. DescribeInstance - Query Instance Details

> **⚠️ CRITICAL: Required User-Provided Parameters**
>
> When querying instance details, the following parameters **MUST be explicitly provided by the user**. Agents **MUST NOT guess or fabricate** these values:
>
> | Parameter | Description | Example |
> |------|------|------|
> | `--region` | Region where the instance is located | `cn-hangzhou` |
> | `--instance-id` | Instance ID | `es-cn-xxx****` |
>
> **Pre-execution Check Steps:**
> 1. Check if the user has provided region and instance ID
> 2. If region is missing, **immediately ask the user**:
>    ```
>    Please provide the region where the instance is located, e.g., cn-hangzhou, cn-shanghai, cn-beijing, etc.
>    ```
> 3. Wait for the user to explicitly provide before executing the query command
>
> **Prohibited Behaviors:**
> - ❌ Do NOT use a default region (such as cn-hangzhou) to replace the user-specified region
> - ❌ Do NOT guess region based on instance ID
> - ❌ Do NOT assume the instance is in a specific region

**CLI Command:**
```bash
aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Required Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--instance-id` | string | Instance ID |

**Response Fields:**

| Field | Type | Description |
|-------|------|-------------|
| `instanceId` | string | Instance ID |
| `description` | string | Instance name |
| `status` | string | Instance status |
| `esVersion` | string | Elasticsearch version |
| `nodeAmount` | int | Number of data nodes |
| `paymentType` | string | Payment type |
| `domain` | string | Internal access address |
| `port` | int | Access port |
| `kibanaDomain` | string | Kibana access address |
| `kibanaPort` | int | Kibana port |

---

### 3. ListInstance - List Instances

> **⚠️ CRITICAL: Required Parameters and Parameter Validation**
>
> **1. region Parameter (Required)**
>
> The `--region` parameter **MUST be explicitly provided by the user**. Agents **MUST NOT guess or use default values**.
>
> | Parameter | Description | Example |
> |------|------|------|
> | `--region` | Region where instances are located | `cn-hangzhou` |
>
> **Pre-execution Check Steps:**
> 1. Check if the user has provided a region
> 2. If region is missing, **immediately ask the user**:
>    ```
>    Please provide the region where instances are located, e.g., cn-hangzhou, cn-shanghai, cn-beijing, etc.
>    ```
> 3. Wait for the user to explicitly provide before executing the query command
>
> **Prohibited Behaviors:**
> - ❌ Do NOT use a default region (such as cn-hangzhou) to replace the user-specified region
> - ❌ Do NOT assume instances are in a specific region
>
> ---
>
> **2. status Parameter Validation**
>
> When the user specifies the `--status` parameter, Agents **MUST validate the parameter value**.
>
> **Valid Values (case-sensitive, only the following values are supported):**
> | Value | Description |
> |------|------|
> | `activating` | Activating (restarting or configuration changing) |
> | `active` | Running normally |
> | `inactive` | Stopped |
> | `invalid` | Invalid |
>
> **Pre-execution Check Steps:**
> 1. Check if the user-provided status value is one of the valid values above
> 2. If the value is invalid, **immediately prompt the user**:
>    ```
>    The status parameter value is invalid. Valid values are: activating, active, inactive, invalid
>    Please provide a valid status value.
>    ```
> 3. Wait for the user to provide a valid value before executing the query command
>
> **Prohibited Behaviors:**
> - ❌ Do NOT guess or transform the user-provided status value
> - ❌ Do NOT ignore the user-provided value and query directly

**CLI Command:**
```bash
aliyun elasticsearch list-instance \
  --region <RegionId> \
  --page <PageNumber> \
  --size <PageSize> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Optional Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--page` | int | Page number, starting from 1, default 1 |
| `--size` | int | Items per page, max 100, default 10 |
| `--description` | string | Instance name, supports fuzzy search |
| `--instance-id` | string | Instance ID |
| `--es-version` | string | Instance version |
| `--vpc-id` | string | VPC ID |
| `--zone-id` | string | Availability Zone ID |
| `--status` | string | Instance status, **only supports activating, active, inactive, invalid** |
| `--payment-type` | string | Payment type |

**Response:**
```json
{
  "RequestId": "5FFD9ED4-C2EC-4E89-B22B-1ACB6FE1****",
  "Headers": {
    "X-Total-Count": 10
  },
  "Result": [
    {
      "instanceId": "es-cn-xxx****",
      "description": "my-es-instance",
      "status": "active",
      "esVersion": "7.10_with_X-Pack",
      "nodeAmount": 2,
      "paymentType": "postpaid"
    }
  ]
}
```

---

### 4. RestartInstance - Restart Instance

When restarting, it is recommended to first check the instance status and only proceed with the restart operation when the instance status is active.

**API Style:** ROA (RESTful)


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

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

**Required Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--instance-id` | string | Instance ID |
| `--client-token` | string | Idempotency token for safe retries, UUID format |

**Optional Parameters (flags):**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--force` | bool | Whether to force restart, ignoring cluster status |

**Request Body Parameters (via --body):**

| Field | Type | Description |
|-------|------|-------------|
| `restartType` | string | Restart type: `instance` (instance restart), `nodeIp` (node restart) |
| `nodes` | list | Node IP list to restart (when nodeIp type) |
| `blueGreenDep` | bool | Whether to enable blue-green deployment |
| `batchCount` | double | Concurrency for force restart |
| `force` | bool | Whether to force restart |

**Examples:**

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

# Using flags
aliyun elasticsearch restart-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --force true \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills

# Using --body for simple 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

# Using --body for 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

# Using --body for restarting 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
```

**Response:**
```json
{
  "RequestId": "F99407AB-2FA9-489E-A259-40CF6DC****",
  "Result": {
    "instanceId": "es-cn-xxx****",
    "status": "activating"
  }
}
```

---

### 5. ListAllNode - Query Cluster Node Information

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

**Required Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--instance-id` | string | Instance ID |

**Optional Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--extended` | bool | Whether to return node monitoring information, default true |

**Response:**
```json
{
  "RequestId": "0D71B597-F3FF-5B56-88D7-74F9D3F7****",
  "Result": [
    {
      "host": "10.15.XX.XX",
      "nodeType": "WORKER",
      "health": "GREEN",
      "cpuPercent": "4.2%",
      "heapPercent": "21.6%",
      "diskUsedPercent": "1.0%",
      "loadOneM": "0.12",
      "zoneId": "cn-hangzhou-i",
      "port": 9200
    }
  ]
}
```

**Response Fields:**

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

**Node Type Reference:**

| Type | Description |
|------|-------------|
| `MASTER` | Dedicated master node |
| `WORKER` | Hot node (data node) |
| `WORKER_WARM` | Cold node |
| `COORDINATING` | Coordinating node |
| `KIBANA` | Kibana node |

---

### 6. UpdateInstance - Upgrade/Downgrade Instance Configuration

> **⚠️ CRITICAL: Pre-update Status Check and Constraints**
>
> **1. Instance Status Check (Required)**
>
> Before executing an update operation, you **MUST** first query the instance status using `describe-instance` and confirm it is `active`.
> - **Only when the instance status is `active` can you execute the update operation**
> - **If the instance status is `activating`, `inactive`, or `invalid`, update operation is prohibited**
>
> **2. Single Node Type Per Call**
>
> Each update call can only change **one type of node**. The supported node types are:
> - Data node (`nodeAmount` / `nodeSpec`)
> - Dedicated master node (`masterConfiguration`)
> - Cold data node (`warmNodeConfiguration`)
> - Coordinating node (`clientNodeConfiguration`)
> - Kibana node (`kibanaConfiguration`)
> - Elastic data node (`elasticDataNodeConfiguration`)
>
> You **CAN** change multiple attributes of the **same** node type in one call (e.g., both `amount` and `spec` for coordinating nodes).
>
> **3. Upgrade vs Downgrade Rules**
>
> | Rule | Upgrade (default) | Downgrade (`orderActionType=downgrade`) |
> |------|-------------------|----------------------------------------|
> | Storage size | Can increase | Cannot decrease |
> | Storage type | Can upgrade | Can downgrade |
> | Node count | Can increase | Cannot decrease (use ShrinkNode API) |
> | Spec (CPU/Memory) | Can increase | Can decrease |
> | Force change | Supported | Not supported |
> | updateType | Supported | Not supported (smart change only) |
>
> **Prohibited Behaviors:**
> - ❌ Do NOT attempt to change multiple node types in a single call
> - ❌ Do NOT reduce node count via UpdateInstance (use ShrinkNode instead)
> - ❌ Do NOT reduce storage size in either upgrade or downgrade
> - ❌ Do NOT disable already-enabled nodes
> - ❌ Do NOT guess node specifications - refer to [node-specifications-by-region.md](node-specifications-by-region.md)

**API Style:** ROA (RESTful)

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

```bash
# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

# Upgrade (default orderActionType=upgrade)
aliyun elasticsearch update-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_BODY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Downgrade (must set orderActionType=downgrade)
aliyun elasticsearch update-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --order-action-type downgrade \
  --body '<JSON_BODY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Required Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--instance-id` | string | Instance ID |
| `--client-token` | string | Idempotency token for safe retries, UUID format |

**Optional Parameters (query):**

| Parameter | Type | Description |
|-----------|------|-------------|
| `--order-action-type` | string | Change type: `upgrade` (default) or `downgrade` |
| `--force` | bool | Whether to force change (only for upgrade), default false |

**Request Body Parameters (via --body):**

| Field | Type | Description |
|-------|------|-------------|
| `nodeAmount` | int | Data node count (2~50) |
| `nodeSpec` | object | Data node configuration: `spec`, `disk`, `diskType`, `performanceLevel` |
| `masterConfiguration` | object | Dedicated master node config: `amount`, `spec`, `disk`, `diskType` |
| `clientNodeConfiguration` | object | Coordinating node config: `amount`, `spec`, `disk` |
| `warmNodeConfiguration` | object | Cold data node config: `amount`, `spec`, `disk`, `diskType` |
| `kibanaConfiguration` | object | Kibana node config: `amount`, `spec`, `disk` |
| `elasticDataNodeConfiguration` | object | Elastic data node config: `amount`, `spec`, `disk`, `diskType` |
| `updateType` | string | Change method: `blue_green` (blue-green), `normal` (in-place). Default is smart change (only for upgrade) |
| `force` | bool | Whether to force change (only for upgrade) |
| `dryRun` | bool | Pre-validation only, does not execute change |

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

| # | Scenario | Request Body (`--body`) |
|---|----------|------------------------|
| 1 | Data node disk upgrade/downgrade | `{"nodeSpec":{"disk":40}}` |
| 2 | Data node spec upgrade/downgrade | `{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new"}}` |
| 3 | Data node disk + spec together | `{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new","disk":40}}` |
| 4 | Data node count increase/decrease | `{"nodeAmount":4}` |
| 5 | Data node count + disk + spec together | `{"nodeAmount":4,"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new","disk":40}}` |
| 6 | Master node spec upgrade/downgrade | `{"masterConfiguration":{"spec":"elasticsearch.sn2ne.xlarge"}}` |
| 7 | Kibana node spec change | `{"kibanaConfiguration":{"spec":"elasticsearch.sn1ne.large"}}` |
| 8 | Coordinating node count + spec | `{"clientNodeConfiguration":{"amount":3,"spec":"elasticsearch.sn1ne.large"}}` |
| 9 | Cold node count + disk + spec | `{"warmNodeConfiguration":{"amount":3,"spec":"elasticsearch.sn1ne.large","disk":500}}` |

**CLI Examples:**

```bash
# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

# Example 1: Upgrade data node disk to 40GB
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"nodeSpec":{"disk":40}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 2: Upgrade data node spec
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

# Example 3: Upgrade data node disk and spec together
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new","disk":40}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 4: Increase data node count to 4
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"nodeAmount":4}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 5: Change data node count, disk, and spec together
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"nodeAmount":4,"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new","disk":40}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 6: Upgrade master node spec
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"masterConfiguration":{"spec":"elasticsearch.sn2ne.xlarge"}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 7: Change Kibana node spec
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"kibanaConfiguration":{"spec":"elasticsearch.sn1ne.large"}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 8: Change coordinating node count and spec
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"clientNodeConfiguration":{"amount":3,"spec":"elasticsearch.sn1ne.large"}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 9: Change cold node count, disk, and spec
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"warmNodeConfiguration":{"amount":3,"spec":"elasticsearch.sn1ne.large","disk":500}}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills

# Example 10: Downgrade data node spec (must set orderActionType=downgrade)
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

# Example 11: Dry-run pre-validation (does not execute)
aliyun elasticsearch update-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '{"nodeSpec":{"spec":"elasticsearch.sn2ne.xlarge.new"},"dryRun":true}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills
```

**Response:**
```json
{
  "RequestId": "F99407AB-2FA9-489E-A259-40CF6DC****",
  "Result": {
    "instanceId": "es-cn-xxx****",
    "status": "activating"
  }
}
```

---

## Instance Status Reference

| Status | Description |
|--------|-------------|
| `active` | Running normally |
| `activating` | Activating (restarting or configuration changing) |
| `inactive` | Stopped |
| `invalid` | Invalid |

## Elasticsearch Version Reference

| Version | Description |
|---------|-------------|
| `8.5.1_with_X-Pack` | Elasticsearch 8.5.1 Commercial Edition |
| `7.10_with_X-Pack` | Elasticsearch 7.10 Commercial Edition |
| `7.7_with_X-Pack` | Elasticsearch 7.7 Commercial Edition |
| `6.8_with_X-Pack` | Elasticsearch 6.8 Commercial Edition |
| `6.7_with_X-Pack` | Elasticsearch 6.7 Commercial Edition |
| `6.3_with_X-Pack` | Elasticsearch 6.3 Commercial Edition |

## Official Documentation

- [createInstance API](https://next.api.aliyun.com/api/elasticsearch/2017-06-13/createInstance)
- [DescribeInstance API](https://next.api.aliyun.com/api/elasticsearch/2017-06-13/DescribeInstance)
- [ListInstance API](https://next.api.aliyun.com/api/elasticsearch/2017-06-13/ListInstance)
- [RestartInstance API](https://next.api.aliyun.com/api/elasticsearch/2017-06-13/RestartInstance)
- [UpdateInstance API](https://next.api.aliyun.com/api/elasticsearch/2017-06-13/UpdateInstance)
- [Elasticsearch Pricing](https://www.aliyun.com/price/product#/elasticsearch/detail)


path: references/verification-method.md
content: # Verification Method - Elasticsearch Instance Management

This document describes how to verify the success of each operation in the Elasticsearch instance management workflow.

## Table of Contents

- [1. Verify Instance Creation](#1-verify-instance-creation)
- [2. Verify Instance Query (DescribeInstance)](#2-verify-instance-query-describeinstance)
- [3. Verify Instance List (ListInstance)](#3-verify-instance-list-listinstance)
- [4. Verify Instance Restart](#4-verify-instance-restart)
- [5. Verify List All Nodes](#5-verify-list-all-nodes)
- [6. Verify Instance Update (Upgrade/Downgrade)](#6-verify-instance-update-upgradedowngrade)
- [7. End-to-End Verification Script](#7-end-to-end-verification-script)
- [Error Handling](#error-handling)
- [References](#references)

---

## 1. Verify Instance Creation

After creating an Elasticsearch instance, verify the creation was successful:

### Step 1: Check the Creation Response

The `create-instance` command returns an `instanceId` if successful:

```json
{
  "RequestId": "838D9D11-8EEF-46D8-BF0D-BC8FC2B0C2F3",
  "Result": {
    "instanceId": "es-cn-xxx****"
  }
}
```

**Verification**: Ensure the response contains a valid `instanceId`.

### Step 2: Query Instance Status

```bash
aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Expected Status Progression:**
1. `activating` - Instance is being created
2. `active` - Instance is ready for use

### Step 3: Wait for Active Status

Poll the instance status until it becomes `active`:

```bash
# Check instance status (repeat until status is "active")
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result.status" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Success Criteria:**
- Response contains `instanceId`
- Instance status transitions to `active` (may take 10-30 minutes)
- `domain` and `kibanaDomain` fields are populated

---

## 2. Verify Instance Query (DescribeInstance)

### Verification Command

```bash
aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

### Success Criteria

1. **Response Status**: HTTP 200
2. **Required Fields Present**:
   - `instanceId`
   - `status`
   - `esVersion`
   - `domain`

### Example Verification

```bash
# Verify instance exists and check key fields
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result.{ID:instanceId,Status:status,Version:esVersion,Domain:domain}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Expected Output:**
```json
{
  "ID": "es-cn-xxx****",
  "Status": "active",
  "Version": "7.10_with_X-Pack",
  "Domain": "es-cn-xxx****.elasticsearch.aliyuncs.com"
}
```

---

## 3. Verify Instance List (ListInstance)

### Verification Command

```bash
aliyun elasticsearch list-instance \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

### Success Criteria

1. **Response Status**: HTTP 200
2. **Headers contain total count**: `X-Total-Count` field
3. **Result array**: Contains instance objects

### Example Verification

```bash
# List all instances and verify count
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --cli-query "length(Result)" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

### Verify Specific Instance in List

```bash
# Check if a specific instance is in the list
aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result[0].instanceId" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Success Criteria:**
- Returns the expected `instanceId`
- Instance is visible in the list

---

## 4. Verify Instance Restart

### Step 1: Execute Restart

```bash
aliyun elasticsearch restart-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

### Step 2: Check Response

**Expected Response:**
```json
{
  "RequestId": "F99407AB-2FA9-489E-A259-40CF6DC****",
  "Result": {
    "instanceId": "es-cn-xxx****",
    "status": "active"
  }
}
```

### Step 3: Monitor Restart Progress

```bash
# Poll status until back to "active"
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result.status" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Status Progression:**
1. `activating` - Restart in progress
2. `active` - Restart complete

### Success Criteria

1. Initial response contains `RequestId`
2. Instance status changes to `activating`
3. Instance status returns to `active` after restart completes
4. Instance is accessible after restart

---

## 5. Verify List All Nodes

### Verification Command

```bash
aliyun elasticsearch list-all-node \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

### Success Criteria

1. **Response Status**: HTTP 200
2. **Result array**: Contains node objects with required fields
3. **Node health**: All nodes should be GREEN for healthy cluster

### Example Verification

```bash
# List all nodes with summary
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result[].{Host:host,Type:nodeType,Health:health,CPU:cpuPercent}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Expected Output:**
```json
[
  {
    "Host": "10.15.XX.XX",
    "Type": "WORKER",
    "Health": "GREEN",
    "CPU": "4.2%"
  }
]
```

### Verify Node Count Matches Instance Configuration

```bash
# Get node count from instance info
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result.nodeAmount" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

# Compare with actual node count (WORKER nodes)
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "length(Result[?nodeType=='WORKER'])" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

---

## 6. Verify Instance Update (Upgrade/Downgrade)

### Step 1: Pre-check Instance Status

Before updating, verify the instance is in `active` status:

```bash
aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --cli-query "Result.status" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Expected**: `"active"`

### Step 2: Execute Update and Check Response

**Expected Response:**
```json
{
  "RequestId": "F99407AB-2FA9-489E-A259-40CF6DC****",
  "Result": {
    "instanceId": "es-cn-xxx****",
    "status": "activating"
  }
}
```

**Verification**: Ensure the response contains `RequestId` and `Result.instanceId`.

### Step 3: Monitor Update Progress

```bash
# Poll status until back to "active"
aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --cli-query "Result.{Status:status,Nodes:nodeAmount,Spec:nodeSpec}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

**Status Progression:**
1. `activating` - Configuration change in progress
2. `active` - Configuration change complete

### Step 4: Verify New Configuration

After the instance returns to `active`, verify the configuration has been updated:

```bash
# Check instance configuration details
aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --cli-query "Result.{NodeAmount:nodeAmount,NodeSpec:nodeSpec,Master:masterConfiguration,Warm:warmNodeConfiguration,Client:clientNodeConfiguration,Kibana:kibanaConfiguration}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

### Success Criteria

1. Pre-check confirms instance status is `active`
2. Update response contains `RequestId` and `Result.instanceId`
3. Instance status transitions to `activating` during update
4. Instance status returns to `active` after update completes
5. Instance configuration matches the requested changes

---

## 7. End-to-End Verification Script

Complete verification workflow:

```bash
#!/bin/bash

REGION="cn-hangzhou"
INSTANCE_ID="es-cn-xxx****"
USER_AGENT="--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage"

echo "=== Step 1: Verify Instance Exists ==="
aliyun elasticsearch describe-instance \
  --region $REGION \
  --instance-id $INSTANCE_ID \
  $USER_AGENT

echo ""
echo "=== Step 2: Verify Instance in List ==="
aliyun elasticsearch list-instance \
  --region $REGION \
  --instance-id $INSTANCE_ID \
  --cli-query "Result[0].{ID:instanceId,Status:status}" \
  $USER_AGENT

echo ""
echo "=== Step 3: Verify Instance Status ==="
STATUS=$(aliyun elasticsearch describe-instance \
  --region $REGION \
  --instance-id $INSTANCE_ID \
  --cli-query "Result.status" \
  $USER_AGENT | tr -d '"')

if [ "$STATUS" == "active" ]; then
  echo "✅ Instance is active and healthy"
else
  echo "⚠️ Instance status: $STATUS"
fi
```

---

## Error Handling

### Common Error Codes

| Error Code | Description | Resolution |
|------------|-------------|------------|
| `InstanceNotFound` | Instance does not exist | Verify instance ID is correct |
| `InstanceActivating` | Instance is not ready | Wait for instance to become active |
| `Forbidden.RAM` | Insufficient permissions | Check RAM policy |
| `InvalidParameter` | Invalid parameter value | Check parameter format |

### Troubleshooting Commands

```bash
# Check if CLI is configured correctly
aliyun configure list

# Test API connectivity
aliyun elasticsearch list-instance --region cn-hangzhou --size 1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage

# Debug with verbose logging
aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --log-level debug \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage
```

---

## References

- [Elasticsearch Status Codes](https://help.aliyun.com/document_detail/64893.html)
- [Error Handling](https://help.aliyun.com/document_detail/64913.html)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)