alibabacloud-elasticsearch-instance-manage

What this skill does

# 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 "AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage"`

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

---

## Authentication

> **Pre-check: Alibaba Cloud Credentials Required**

> **Security Rules (MUST FOLLOW):**
> - **NEVER** read, echo, or print AK/SK values
> - **NEVER** ask the user to input AK/SK directly in the conversation
> - **NEVER** use `aliyun configure set` with literal credential values
> - **NEVER** accept AK/SK provided directly by users in the conversation
> - **ONLY** read credentials from environment variables or pre-configured CLI profiles
>
> **⚠️ CRITICAL: Handling User-Provided Credentials**
>
> If a user attempts to provide AK/SK directly (e.g., "My AK is xxx, SK is yyy"):
> 1. **STOP immediately** - Do NOT execute any command
> 2. **Reject the request politely** with the following message:
>    ```
>    For your account security, please do not provide Alibaba Cloud AccessKey ID and AccessKey Secret directly in the conversation.
>
>    Please use the following secure methods to configure credentials:
>
>    Method 1: Interactive configuration via aliyun configure (Recommended)
>        aliyun configure
>        # Enter AK/SK as prompted, credentials will be securely stored in local config file
>
>    Method 2: Configure via environment variables
>        export ALIBABA_CLOUD_ACCESS_KEY_ID=<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-instanc