Alibabacloud Elasticsearch Instance Manage

Elasticsearch Instance & Config Management

Manage Alibaba Cloud Elasticsearch instances and instance-side configuration via the Aliyun CLI: instance lifecycle (create / describe / list / restart / upgrade / downgrade / node info) and instance config (snapshot backup, analyzer dictionaries).

This skill uses intent routing: this file identifies the user's intent and dispatches to the relevant module document. Read the matched module document fully before generating any CLI command.

Architecture

Alibaba Cloud Elasticsearch Management
├── Instance Lifecycle           --> references/instance-manage.md
│   ├── createInstance           (Create Instance)
│   ├── DescribeInstance         (Query Instance Details)
│   ├── ListInstance             (List Instances)
│   ├── RestartInstance          (Restart Instance)
│   ├── UpdateInstance           (Upgrade / Downgrade)
│   └── ListAllNode              (Query Cluster Node Info)
└── Instance Config              --> references/config-manage.md
    ├── Snapshot Management
    │   ├── UpdateSnapshotSetting    (Set auto-snapshot policy)
    │   ├── DescribeSnapshotSetting  (Query auto-snapshot policy)
    │   └── CreateSnapshot           (Trigger one-shot snapshot)
    └── Dict Management
        ├── ListDicts                (List analyzer dicts)
        ├── UpdateDict               (Cold-update IK dict)
        ├── UpdateHotIkDicts         (Hot-update IK dict)
        ├── UpdateSynonymsDicts      (Update synonyms dict)
        └── UpdateAliwsDict          (Update AliNLP dict)

---

Intent Routing

Match the user request to the FIRST matching row, then load the listed module doc and follow its API spec.

If multiple intents are present, handle them sequentially: route → execute → verify → next route.

If the intent does not match any row, ask the user to clarify; do NOT guess an API.

---

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

aliyun version
aliyun configure set --auto-plugin-install true
aliyun plugin update

---

Observability

[MUST] Every business aliyun CLI command invocation MUST carry the per-command flag:

```

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/{session-id}

```

where {session-id} is the per-skill-session identifier defined below. Identification of this skill is achieved exclusively via the per-command --user-agent flag on business CLI commands; no CLI-level / session-level user-agent injection mechanism is used.

session-id generation rule

Generate {session-id} ONCE at the start of the skill session and reuse it for every business CLI command in that session.

Format requirement: 32-character lowercase hexadecimal string (no hyphens) — e.g. 0123456789abcdef0123456789abcdef.

# Preferred (macOS / Linux, openssl is universally available):
SESSION_ID=$(openssl rand -hex 16)

# Fallback 1 — Python:
SESSION_ID=$(python3 -c 'import uuid; print(uuid.uuid4().hex)')

# Fallback 2 — pure shell (no external tool):
SESSION_ID=$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')

• Format: 32 lowercase hex characters, no hyphens, no prefix. uuidgen output (with hyphens) is NOT acceptable — strip hyphens via tr -d '-' | tr 'A-Z' 'a-z' if you fall back to it.
• The same SESSION_ID MUST be embedded in the --user-agent of EVERY business CLI command this session emits.
• Do NOT regenerate SESSION_ID on retry — only regenerate at session boundaries (a new skill invocation starts a new session).

per-command --user-agent format

---

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 one of 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 stored securely in the 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

```

Look for a valid profile (AK, STS, or OAuth identity). If none exists, STOP here.

---

Global Conventions

These conventions apply to EVERY CLI command produced by this skill, regardless of which module is routed.

Common CLI Arguments

Idempotency for Write Operations

For write APIs (createInstance, RestartInstance, UpdateInstance, CreateSnapshot, UpdateSnapshotSetting, UpdateDict, UpdateHotIkDicts, UpdateSynonymsDicts, UpdateAliwsDict) you MUST use --client-token.

• Format: UUID. Generate via uuidgen (or PowerShell [guid]::NewGuid()); fall back to idem-<timestamp>-<semantic> if uuidgen is unavailable. Never abort the workflow because of an unavailable command.
• On timeout / failure, retry with the same clientToken. Wait ~10 seconds before retrying.
• Duplicate calls with the same clientToken will not re-execute the operation.

CLIENT_TOKEN=$(uuidgen)   # reuse on retry

---

RAM Policy

The RAM principal needs the union of permissions for the modules it will use. See references/ram-policies.md for full policy JSON.

Minimum required actions:

Snapshot/Dict modules also need OSS read access to the bucket holding the dict files.

---

Success Verification

See references/verification-method.md for module-by-module verification steps.

Quick check after instance lifecycle changes:

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --cli-query "Result.status" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Expected status: active.

Quick check after snapshot/dict changes:

# Snapshot setting changed
aliyun elasticsearch describe-snapshot-setting \
  --region <RegionId> --instance-id <InstanceId> \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# Dict list refreshed (analyzerType: IK | IK_HOT | SYNONYMS | ALIWS)
aliyun elasticsearch list-dicts \
  --region <RegionId> --instance-id <InstanceId> \
  --analyzer-type <TYPE> \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

Reference Links

Acceptance Criteria: alibabacloud-elasticsearch-instance-manage

Scenario: Elasticsearch Instance Management Purpose: Skill testing acceptance criteria

Table of Contents

• Correct CLI Command Patterns
• Correct Common SDK Code Patterns (if applicable)
• Response Validation Criteria
• Security Criteria
• References

---

Correct CLI Command Patterns

1. Product — verify product name exists

✅ CORRECT

aliyun elasticsearch create-instance ...
aliyun elasticsearch describe-instance ...
aliyun elasticsearch list-instance ...
aliyun elasticsearch restart-instance ...
aliyun elasticsearch update-instance ...

❌ INCORRECT

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

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

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

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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT - create-instance

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

aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT - describe-instance

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

aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --page 1 \
  --size 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT - list-instance

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

✅ CORRECT - restart-instance

aliyun elasticsearch restart-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --force true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT - restart-instance

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

✅ CORRECT - list-all-node

aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# With extended parameter
aliyun elasticsearch list-all-node \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --extended false \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT - list-all-node

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

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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT - update-instance

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

aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

❌ INCORRECT

aliyun elasticsearch list-instance \
  --region cn-hangzhou
  # Missing: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

5. Parameter Values — verify format requirements

✅ CORRECT - network-config format

# 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

# 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

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

--es-version "7.10"           # Wrong: missing "_with_X-Pack"
--es-version "7.10-X-Pack"    # Wrong: incorrect format

✅ CORRECT - payment-type values

--payment-type postpaid    # Pay-as-you-go
--payment-type prepaid     # Subscription

❌ INCORRECT - payment-type values

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

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

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

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

# NEVER hardcode credentials
config = open_api_models.Config(
    access_key_id="LTAI5tXXXXXX",          # FORBIDDEN
    access_key_secret="8dXXXXXXXXXX"       # FORBIDDEN
)

3. Client Initialization

✅ CORRECT

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
• Elasticsearch API Reference

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
• macOS
• Linux
• Windows
• Configuration
• Quick Start
• Configuration Modes
• Environment Variables
• Managing Multiple Profiles
• Credential Priority
• Verification
• Test Authentication
• Debug Configuration
• Security Best Practices
• Troubleshooting
• Advanced Configuration
• Custom Endpoint
• Proxy Settings
• Timeout Settings
• Next Steps
• References

---

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

Using Binary

# 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

# 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

# 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

# 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

# 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 for secure credential setup.

Available Authentication Modes:

Configure using interactive mode (recommended):

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:

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:

# 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

aliyun ecs describe-instances --profile projectA

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

List and Switch Profiles

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

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

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

# 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

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

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

3. Rotate Access Keys Regularly

1. Create new access key in RAM Console 2. Update configuration using interactive mode:

   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:

aliyun configure --mode StsToken

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

5. Use ECS RAM Roles When Possible

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

6. Never Commit Credentials

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

# Use environment variables in CI/CD instead

7. Secure Config File

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

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# 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

# Error: Forbidden.RAM

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

Issue: STS Token Expired

# 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

# 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

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

Proxy Settings

# 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

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

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

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

Elasticsearch Config Management

Routing entry: ../SKILL.md

>

This document covers Snapshot (backup) management and Dict (analyzer dictionary) management for an existing Elasticsearch instance.

Global conventions (Authentication, Observability, common CLI args, idempotency, RAM rules) are defined in SKILL.md and apply to every command below.

Table of Contents

• Snapshot Management
• 1. UpdateSnapshotSetting
• 2. DescribeSnapshotSetting
• 3. CreateSnapshot
• Dict Management
• 4. ListDicts
• 5. UpdateDict
• 6. UpdateHotIkDicts
• 7. UpdateSynonymsDicts
• 8. UpdateAliwsDict
• Common Conventions
• Official Documentation

---

Common Conventions

The following short rules apply to every API in this document. Full text lives in SKILL.md.

---

Snapshot Management

1. UpdateSnapshotSetting

Update the automatic snapshot policy of the instance (cron + on/off).

• API: UpdateSnapshotSetting
• HTTP: POST|PUT /openapi/instances/[InstanceId]/snapshot-setting
• Idempotent: No (config-overwriting; safe to repeat)

Pre-check

• Instance status MUST be active.
• If enable=true, quartzRegex is REQUIRED.

Required Parameters

CLI Template

aliyun elasticsearch update-snapshot-setting \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --body '{"enable":true,"quartzRegex":"<cron>"}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example: enable daily snapshot at 01:00

aliyun elasticsearch update-snapshot-setting \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --body '{"enable":true,"quartzRegex":"0 0 01 ? * * *"}' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Response (Result struct): enable, quartzRegex.

---

2. DescribeSnapshotSetting

Query the current automatic snapshot configuration.

• API: DescribeSnapshotSetting
• HTTP: GET /openapi/instances/[InstanceId]/snapshot-setting

Required Parameters

CLI Template

aliyun elasticsearch describe-snapshot-setting \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example

aliyun elasticsearch describe-snapshot-setting \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --cli-query "Result.{Enable:Enable,Cron:QuartzRegex}" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Response (Result struct)

---

3. CreateSnapshot

Manually trigger a one-shot snapshot for the instance.

• API: CreateSnapshot
• HTTP: POST /openapi/instances/[InstanceId]/snapshots
• Idempotent: Yes — clientToken is REQUIRED.

Pre-check

• Instance status MUST be active.
• Automatic snapshot setting must already be configured (call DescribeSnapshotSetting first; if Enable=false and there is no OSS repo bound, configure via UpdateSnapshotSetting first).

Required Parameters

CLI Template

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch create-snapshot \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch create-snapshot \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Response: Result is true (success) / false (failure).

---

Dict Management

⚠️ MUST — Disambiguate the dict type BEFORE picking an API

>

The four analyzer dict families map to different APIs and have different update semantics:

>

| Dict family | analyzer-type | Update API | Notes |

|---|---|---|---|

| IK main / stopword (cold) | IK | UpdateDict | Cold update — always restarts the cluster (run during off-peak hours) |

| IK main / stopword (hot) | IK_HOT | UpdateHotIkDicts | Restart-free only when file content changes; any file-count or file-name change still restarts the cluster |

| Synonyms | SYNONYMS | UpdateSynonymsDicts | *.txt files |

| AliNLP / analysis-aliws | ALIWS | UpdateAliwsDict | File MUST be aliws_ext_dict.txt; nodes auto-load without cluster restart |

>

If the user does NOT explicitly state which dict family they want to update (e.g. only says "更新词典" / "update dictionaries" without naming IK / IK_HOT / synonyms / AliWS), STOP and ASK the user to clarify. Do NOT guess the dict family from file names, prior conversation, or defaults — choosing the wrong API will silently overwrite or delete unrelated dicts due to full-list semantics.

CRITICAL — Full-list semantics

>

All Update*Dict APIs use full-list overwrite semantics on the request body:

- The body MUST be a JSON array containing every dict file you want to keep AFTER the call.

- Files in the array with sourceType=OSS are uploaded/replaced from OSS.

- Existing files you want to keep MUST be re-listed with sourceType=ORIGIN.

- Any pre-existing file NOT listed in this call will be DELETED.

>

Workflow: call ListDicts first → build the full target list → submit it via UpdateDict / UpdateHotIkDicts / UpdateSynonymsDicts / UpdateAliwsDict.

4. ListDicts

Return the dict list for a given analyzer type, including a temporary public download URL (90s validity).

• API: ListDicts
• HTTP: GET /openapi/instances/[InstanceId]/dicts

Required Parameters

CLI Template

aliyun elasticsearch list-dicts \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --analyzer-type <IK|IK_HOT|SYNONYMS|ALIWS> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example: list IK hot-update dicts and project key fields

aliyun elasticsearch list-dicts \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --analyzer-type IK_HOT \
  --cli-query "Result[].{Name:name,Type:type,Source:sourceType,Size:fileSize}" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Response Fields

---

5. UpdateDict

Cold-update of the IK analyzer dicts (main / stopword). Triggers an instance restart-style change.

⚠️ Restart impact: A cold-update operation will restart the cluster. To avoid impacting your business, please perform this operation during off-peak hours; once the restart completes, the new dicts take effect automatically.

• API: UpdateDict
• HTTP: PUT /openapi/instances/[InstanceId]/dict
• Idempotent: Yes — pass clientToken.

⚠️ CRITICAL — Full-list semantics: This API performs a full replacement. The body MUST contain ALL dictionaries you want to keep. Any existing dictionary NOT included in the request body will be permanently deleted. To obtain the current cold-update dict list, call DescribeInstance and read Result.dictList. For dictionaries that already exist on the server and should be retained as-is, set sourceType to ORIGIN (no need to re-upload via OSS).

Pre-check

• Instance status MUST be active.
• For sourceType=OSS, the OSS object must exist and the bucket must be publicly readable.

Required Parameters

Body Item Schema

CLI Template

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-dict \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_ARRAY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example: add one custom MAIN dict from OSS while keeping system dicts

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-dict \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '[
    {"name":"my_main.dic","type":"MAIN","sourceType":"OSS","ossObject":{"bucketName":"my-bucket","key":"es/my_main.dic"}},
    {"name":"SYSTEM_MAIN.dic","type":"MAIN","sourceType":"ORIGIN"},
    {"name":"SYSTEM_STOPWORD.dic","type":"STOP","sourceType":"ORIGIN"}
  ]' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

6. UpdateHotIkDicts

Hot-update of the IK analyzer dicts (main / stopword).

⚠️ Restart conditions: Hot-update is restart-free only when only the file CONTENTS are changed (the new full-list keeps the same set of entries — same count AND same names — as the existing list, with sourceType=OSS only re-uploading the file content). If the dict file count OR any file name changes, the cluster will still be restarted. To avoid impacting your business, please perform such operations during off-peak hours; once the restart completes, the new dicts take effect automatically. Always call ListDicts --analyzer-type=IK_HOT (or DescribeInstance → Result.ikHotDicts) first to confirm the current entries before constructing the body.

• API: UpdateHotIkDicts
• HTTP: PUT /openapi/instances/{InstanceId}/ik-hot-dict
• Idempotent: Yes — pass clientToken.

⚠️ CRITICAL — Full-list semantics: This API performs a full replacement. The body MUST contain ALL dictionaries you want to keep. Any existing dictionary NOT included in the request body will be permanently deleted. To obtain the current hot IK dict list, call DescribeInstance and read Result.ikHotDicts.

Pre-check: same as UpdateDict. Body uses the same schema as UpdateDict (type ∈ MAIN | STOP).

`sourceType` values: OSS = upload new dict file from OSS; ORIGIN = retain an existing dictionary already on the server (no re-upload needed). When performing a full-list update, existing dicts you want to keep unchanged MUST be listed with "sourceType": "ORIGIN".

CLI Template

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-hot-ik-dicts \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_ARRAY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example: hot-replace IK STOP dict

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-hot-ik-dicts \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '[
    {"name":"hot_stop.dic","type":"STOP","sourceType":"OSS","ossObject":{"bucketName":"my-bucket","key":"es/hot_stop.dic"}},
    {"name":"SYSTEM_MAIN.dic","type":"MAIN","sourceType":"ORIGIN"},
    {"name":"SYSTEM_STOPWORD.dic","type":"STOP","sourceType":"ORIGIN"}
  ]' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

7. UpdateSynonymsDicts

Update the synonym dictionary (type is fixed to SYNONYMS, file MUST be *.txt).

• API: UpdateSynonymsDicts
• HTTP: PUT /openapi/instances/[InstanceId]/synonymsDict
• Idempotent: Yes — pass clientToken.

⚠️ CRITICAL — Full-list semantics: This API performs a full replacement. The body MUST contain ALL synonym dictionaries you want to keep. Any existing dictionary NOT included in the request body will be permanently deleted. To obtain the current synonyms dict list, call DescribeInstance and read Result.synonymsDicts.

Body Item Schema (per item; same full-list semantics)

Note on `ORIGIN`: For dictionaries that already exist on the server and should be kept unchanged, set "sourceType": "ORIGIN". You do NOT need to provide ossObject for these items.

CLI Template

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-synonyms-dicts \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_ARRAY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-synonyms-dicts \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '[
    {"name":"my_synonyms.txt","type":"SYNONYMS","sourceType":"OSS","ossObject":{"bucketName":"my-bucket","key":"es/my_synonyms.txt"}}
  ]' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

8. UpdateAliwsDict

Update the AliNLP analyzer dict (plugin analysis-aliws, type fixed to ALI_WS). The analysis-aliws plugin supports hot-updating the custom dictionary file aliws_ext_dict.txt. After upload, nodes will auto-load the dict file — takes effect WITHOUT cluster restart.

• API: UpdateAliwsDict
• HTTP: PUT /openapi/instances/[InstanceId]/aliws-dict
• Idempotent: Yes — pass clientToken.
• Constraint: Not supported on Elasticsearch 5.x.

ℹ️ Note: After installing the analysis-aliws plugin, the system does NOT ship any built-in dict file — you MUST upload one manually before the plugin becomes effective.

Dict File Requirements (MUST be satisfied BEFORE upload to OSS):

⚠️ CRITICAL — Full-list semantics: This API performs a full replacement. The body MUST contain ALL AliWS dictionaries you want to keep. Any existing dictionary NOT included in the request body will be permanently deleted. To obtain the current AliWS dict list, call DescribeInstance and read Result.aliwsDicts.

Body Item Schema

Note on `ORIGIN`: For dictionaries that already exist on the server and should be kept unchanged, set "sourceType": "ORIGIN". You do NOT need to provide ossObject for these items.

CLI Template

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-aliws-dict \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_ARRAY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch update-aliws-dict \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --body '[
    {"name":"aliws_ext_dict.txt","type":"ALI_WS","sourceType":"OSS","ossObject":{"bucketName":"my-bucket","key":"es/aliws_ext_dict.txt"}}
  ]' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

Error Handling

---

Official Documentation

• UpdateSnapshotSetting
• DescribeSnapshotSetting
• CreateSnapshot
• ListDicts
• UpdateDict
• UpdateHotIkDicts
• UpdateSynonymsDicts
• UpdateAliwsDict

Elasticsearch Instance Management

Routing entry: ../SKILL.md

>

This document covers the 6 instance lifecycle APIs: create, describe, list, restart, update (upgrade/downgrade), and node-info query.

Global conventions (Authentication, Observability, common CLI args, idempotency, RAM rules) are defined in SKILL.md and apply to every command below.

Table of Contents

• Common Conventions
• API Details
• 1. createInstance
• 2. DescribeInstance
• 3. ListInstance
• 4. RestartInstance
• 5. UpdateInstance
• 6. ListAllNode
• Instance Status Reference
• Elasticsearch Version Reference
• Official Documentation

---

Common Conventions

---

API Details

1. createInstance

Create a new Elasticsearch instance.

• API: createInstance
• HTTP: POST /openapi/instances
• Idempotent: Yes — clientToken is REQUIRED.

Pre-check (CRITICAL)

The following parameters MUST be explicitly provided by the user. Agents MUST NOT guess, fabricate or use defaults.

If any of the above is missing, immediately stop and ask the user with this checklist:

The following parameters are required to create an ES instance, please provide:
- [ ] Region (--region): ___
- [ ] Instance password (esAdminPassword): ___
- [ ] VPC ID (vpcId): ___
- [ ] VSwitch ID (vswitchId): ___
- [ ] Availability Zone (vsArea): ___
- [ ] Payment Type (paymentType): postpaid/prepaid

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
• Region format MUST start with cn- or ap- prefix; if the provided value is obviously invalid (empty, pure numbers, special characters), reject and ask again

Required Body Fields

Optional Body Fields

Multi-AZ Notes

1. networkConfig.vswitchId only takes the primary AZ vswitch; other AZs are auto-allocated. Do NOT pass zoneInfos to specify per-AZ vswitches manually — let the platform allocate. 2. zoneCount controls the AZ number. Multi-AZ MUST include masterConfiguration.

CLI Template

CLIENT_TOKEN=$(uuidgen)
aliyun elasticsearch create-instance \
  --region <RegionId> \
  --client-token $CLIENT_TOKEN \
  --body '<JSON_BODY>' \
  --connect-timeout 3 \
  --read-timeout 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example: Single-AZ instance

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 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example: Multi-AZ instance

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 30 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Error Handling

• "Order parameters do not meet validation conditions" → likely an invalid data node spec for the chosen region. Do NOT guess; refer the user to node-specifications-by-region.md.

Response: {"RequestId":"...","Result":{"instanceId":"es-cn-xxx****"}}.

---

2. DescribeInstance

Query full details of one instance.

• API: DescribeInstance
• HTTP: GET /openapi/instances/[InstanceId]

Pre-check

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
• If region is missing, immediately ask: "Please provide the region where the instance is located, e.g., cn-hangzhou, cn-shanghai, cn-beijing, etc."

CLI Template

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Key Example

aliyun elasticsearch describe-instance \
  --region cn-hangzhou \
  --instance-id es-cn-xxx**** \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Response Fields (selected)

---

3. ListInstance

List instances in a region with optional filters.

• API: ListInstance
• HTTP: GET /openapi/instances

Pre-check

Status Parameter Validation (CRITICAL):

When the user specifies --status, the agent MUST validate the value before executing: 1. Check if the user-provided status value is one of the 4 valid values above 2. If the value is invalid (e.g., "running", "stopped", "healthy"), immediately prompt:

   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

Prohibited Behaviors:

• Do NOT guess or transform the user-provided status value (e.g., do NOT silently convert "running" to "active")
• Do NOT ignore the user-provided invalid value and query without the filter
• Do NOT use a default region — if missing, ask immediately

Optional Parameters

CLI Template

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/${SESSION_ID}

Key Example: list active instances and project key fields

aliyun elasticsearch list-instance \
  --region cn-hangzhou \
  --status active \
  --size 50 \
  --cli-query "Result[].{Id:instanceId,Name:description,Version:esVersion,Status:status,Nodes:nodeAmount}" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

---

4. RestartInstance

Restart instance (whole instance, with optional force, or specific node IPs).

• API: RestartInstance
• HTTP: POST /openapi/instances/[InstanceId]/actions/restart
• Idempotent: Yes — clientToken is REQUIRED.

Pre-check (CRITICAL)

• Instance status MUST be active. Run describe-instance --cli-query "Result.status" first.
• If status is activating / inactive / invalid, REJECT the restart and inform the user.

Required Parameters

Optional Query Parameters (flag-style, NOT in `--body`)

Body Fields (`--body` JSON)

CLI Template

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/${SESSION_ID}

Key Examples

CLIENT_TOKEN=$(uuidgen)

# Normal restart (whole instance)
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/${SESSION_ID}

# Force restart — `force` is a QUERY parameter (--force flag), NOT a body field
# When force=true, batchCount MUST be set in (0, 100]
aliyun elasticsearch restart-instance \
  --region cn-hangzhou --instance-id es-cn-xxx**** \
  --client-token $CLIENT_TOKEN \
  --force true \
  --body '{"restartType":"instance","batchCount":50}' \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# Restart specific nodes (by IP) with blue-green deployment
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"],"blueGreenDep":true}' \
  --connect-timeout 3 --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Response: {"Result":{"instanceId":"es-cn-xxx****","status":"activating"}}.

---

5. UpdateInstance

Upgrade or downgrade configuration of an existing instance.

• API: UpdateInstance
• HTTP: POST /openapi/instances/[InstanceId]/actions/update
• Idempotent: Yes — clientToken is REQUIRED.

Pre-check (CRITICAL)

1. Instance status MUST be active — confirm via describe-instance first. 2. Each call may change ONLY ONE node type. Supported node types:

• Data node (nodeAmount / nodeSpec) — nodeAmount and nodeSpec are the SAME type; can be combined.
• Master node (masterConfiguration)
• Cold data node (warmNodeConfiguration)
• Coordinating node (clientNodeConfiguration)
• Kibana node (kibanaConfiguration)
• Elastic data node (elasticDataNodeConfiguration)

3. Upgrade vs Downgrade rules:

Prohibited

• Changing multiple node types in a single call
• Reducing node count via UpdateInstance
• Reducing storage size in either direction
• Disabling already-enabled nodes
• Guessing specs — refer to node-specifications-by-region.md

Required Parameters

Body Fields (`--body` JSON)

CLI Template

CLIENT_TOKEN=$(uuidgen)

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Body Cookbook

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.

CLI Examples

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

# 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/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Error Handling

1. "Order parameters do not meet validation conditions" → invalid spec for the region. Refer to node-specifications-by-region.md. 2. Status not active → ask the user to wait for recovery before retrying. 3. Multiple node types in one body → only ONE node type is allowed per call.

Response: {"Result":{"instanceId":"es-cn-xxx****","status":"activating"}}.

---

6. ListAllNode

List all cluster nodes with optional monitoring info.

• API: ListAllNode
• HTTP: GET /openapi/instances/[InstanceId]/nodes

Required Parameters

CLI Template

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/${SESSION_ID}

Key Example: project key 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/${SESSION_ID}

Response Fields

---

Instance Status Reference

Elasticsearch Version Reference

Official Documentation

• createInstance
• DescribeInstance
• ListInstance
• RestartInstance
• UpdateInstance
• ListAllNode
• Elasticsearch Pricing

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
• Data Node Specifications
• Dedicated Master Node Specifications
• Kibana Node Specifications
• Coordinating Node Specifications
• Cold Data Node (Warm Node) Specifications
• Specification Selection Recommendations for Creating Instances
• Related Documentation

---

Node Role Description

---

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

Cloud Disk Specifications

Beijing, Shanghai, Hangzhou, Shenzhen, Zhangjiakou do not support cloud disk specifications

---

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

Cloud Disk Specifications

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

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

---

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

---

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

---

Specification Selection Recommendations for Creating Instances

Data Node Selection

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
• ES Instance Node Configuration Instructions
• Create Elasticsearch Instance API

RAM Policies - Elasticsearch Instance & Config Management

This document lists the RAM (Resource Access Management) permissions required for the two modules of this skill:

• Instance Lifecycle (referenced by instance-manage.md)
• Instance Config — Snapshot + Dict (referenced by config-manage.md)

Table of Contents

• Required Permissions Overview
• Minimum Required Policy
• Permissions by Module
• Instance Lifecycle Module
• Snapshot Module
• Dict Module
• Resource-Level Policy (Recommended)
• Region-Specific Policy
• Read-Only Policy
• Additional Permissions for VPC Resources
• Additional Permissions for OSS (Dict / Snapshot)
• System Policies
• Attach System Policy via CLI
• Policy Best Practices
• References

---

Required Permissions Overview

Instance Lifecycle

Snapshot Management

Dict Management

Snapshot module additionally requires OSS access on the snapshot repository bucket; Dict module additionally requires OSS read access on the dict-source bucket. See Additional Permissions for OSS.

---

Minimum Required Policy

Grant the union of the actions for whichever modules will be used. Below is the full union for both modules:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance",
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:ListAllNode",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance",
        "elasticsearch:UpdateSnapshotSetting",
        "elasticsearch:DescribeSnapshotSetting",
        "elasticsearch:CreateSnapshot",
        "elasticsearch:ListDicts",
        "elasticsearch:UpdateDict",
        "elasticsearch:UpdateHotIkDicts",
        "elasticsearch:UpdateSynonymsDicts",
        "elasticsearch:UpdateAliwsDict"
      ],
      "Resource": "*"
    }
  ]
}

---

Permissions by Module

When the principal only uses one module, grant just that module's actions.

Instance Lifecycle Module

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

Snapshot Module

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:UpdateSnapshotSetting",
        "elasticsearch:DescribeSnapshotSetting",
        "elasticsearch:CreateSnapshot"
      ],
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

DescribeInstance is included so the agent can run the mandatory pre-check (instance status must be active).

Dict Module

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListDicts",
        "elasticsearch:UpdateDict",
        "elasticsearch:UpdateHotIkDicts",
        "elasticsearch:UpdateSynonymsDicts",
        "elasticsearch:UpdateAliwsDict"
      ],
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

---

Resource-Level Policy (Recommended)

For better security, restrict permissions to specific resources. CreateInstance cannot bind to a specific instance ID and must use Resource: *.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:ListAllNode",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance",
        "elasticsearch:UpdateSnapshotSetting",
        "elasticsearch:DescribeSnapshotSetting",
        "elasticsearch:CreateSnapshot",
        "elasticsearch:ListDicts",
        "elasticsearch:UpdateDict",
        "elasticsearch:UpdateHotIkDicts",
        "elasticsearch:UpdateSynonymsDicts",
        "elasticsearch:UpdateAliwsDict"
      ],
      "Resource": "acs:elasticsearch:*:*:instances/*"
    }
  ]
}

---

Region-Specific Policy

Restrict operations to specific regions (example: cn-hangzhou):

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:CreateInstance",
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:ListAllNode",
        "elasticsearch:RestartInstance",
        "elasticsearch:UpdateInstance",
        "elasticsearch:UpdateSnapshotSetting",
        "elasticsearch:DescribeSnapshotSetting",
        "elasticsearch:CreateSnapshot",
        "elasticsearch:ListDicts",
        "elasticsearch:UpdateDict",
        "elasticsearch:UpdateHotIkDicts",
        "elasticsearch:UpdateSynonymsDicts",
        "elasticsearch:UpdateAliwsDict"
      ],
      "Resource": "acs:elasticsearch:cn-hangzhou:*:instances/*"
    }
  ]
}

---

Read-Only Policy

For users who only need to view instance information, snapshot settings, and dict listings:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "elasticsearch:DescribeInstance",
        "elasticsearch:ListInstance",
        "elasticsearch:ListAllNode",
        "elasticsearch:DescribeSnapshotSetting",
        "elasticsearch:ListDicts"
      ],
      "Resource": "*"
    }
  ]
}

---

Additional Permissions for VPC Resources

When creating Elasticsearch instances, you may also need VPC-related permissions to look up VPC / VSwitch information:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcs",
        "vpc:DescribeVSwitches"
      ],
      "Resource": "*"
    }
  ]
}

---

Additional Permissions for OSS (Dict / Snapshot)

Dict and Snapshot modules rely on OSS:

• Dict module: when sourceType=OSS, the ES service reads dict files from your OSS bucket. The bucket MUST be in the same region as the ES instance and publicly readable, or you must grant the ES service role read access.
• Snapshot module: snapshots are stored in an OSS repository configured for the instance.

Minimum OSS permissions for the principal that operates these APIs (so it can verify and stage files before calling the ES API):

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:GetObject",
        "oss:GetBucketInfo",
        "oss:ListObjects"
      ],
      "Resource": [
        "acs:oss:*:*:<your-dict-bucket>",
        "acs:oss:*:*:<your-dict-bucket>/*",
        "acs:oss:*:*:<your-snapshot-bucket>",
        "acs:oss:*:*:<your-snapshot-bucket>/*"
      ]
    }
  ]
}

Replace <your-dict-bucket> / <your-snapshot-bucket> with the actual bucket names. If you also need to upload dict files via OSS APIs, additionally grant oss:PutObject on the dict bucket.

---

System Policies

Alibaba Cloud provides built-in system policies for Elasticsearch:

Attach System Policy via CLI

`--user-agent` applies ONLY to business API commands (e.g. aliyun elasticsearch ...); such commands MUST pass --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID} (see SKILL.md#observability for SESSION_ID generation rule). System / tool commands (aliyun configure, aliyun version, aliyun plugin update, aliyun help, aliyun ram ..., etc.) MUST NOT carry --user-agent — they do not support the flag.

# 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/${SESSION_ID}

# 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/${SESSION_ID}

---

Policy Best Practices

1. Principle of Least Privilege: Grant only the minimum permissions required for the modules in use. 2. Use Resource-Level Restrictions: Restrict to specific instances / buckets when possible. 3. Separate Read and Write: Use different policies for different operation types (e.g. Read-Only Policy for monitoring agents). 4. Module Isolation: For multi-tenant use, grant only the relevant module's actions (instance vs snapshot vs dict). 5. Regular Auditing: Review and audit permissions periodically. 6. Use RAM Roles: For applications, use RAM roles / STS rather than hardcoded credentials.

---

References

• Elasticsearch RAM Policies
• RAM Policy Structure
• RAM Console
• OSS Permission Reference

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
• 2. Verify Instance Query (DescribeInstance)
• 3. Verify Instance List (ListInstance)
• 4. Verify Instance Restart
• 5. Verify List All Nodes
• 6. Verify Instance Update (Upgrade/Downgrade)
• 7. End-to-End Verification Script
• Error Handling
• 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:

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

Verification: Ensure the response contains a valid instanceId.

Step 2: Query Instance Status

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

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:

# 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/${SESSION_ID}

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

aliyun elasticsearch describe-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Success Criteria

1. Response Status: HTTP 200 2. Required Fields Present:

• instanceId
• status
• esVersion
• domain

Example Verification

# 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/${SESSION_ID}

Expected Output:

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

aliyun elasticsearch list-instance \
  --region <RegionId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Success Criteria

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

Example Verification

# 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/${SESSION_ID}

Verify Specific Instance in List

# 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/${SESSION_ID}

Success Criteria:

• Returns the expected instanceId
• Instance is visible in the list

---

4. Verify Instance Restart

Step 1: Execute Restart

aliyun elasticsearch restart-instance \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

Step 2: Check Response

Expected Response:

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

Step 3: Monitor Restart Progress

# 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/${SESSION_ID}

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

aliyun elasticsearch list-all-node \
  --region <RegionId> \
  --instance-id <InstanceId> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

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

# 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/${SESSION_ID}

Expected Output:

[
  {
    "Host": "10.15.XX.XX",
    "Type": "WORKER",
    "Health": "GREEN",
    "CPU": "4.2%"
  }
]

Verify Node Count Matches Instance Configuration

# 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/${SESSION_ID}

# 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/${SESSION_ID}

---

6. Verify Instance Update (Upgrade/Downgrade)

Step 1: Pre-check Instance Status

Before updating, verify the instance is in active status:

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

Expected: "active"

Step 2: Execute Update and Check Response

Expected Response:

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

# 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/${SESSION_ID}

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:

# 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/${SESSION_ID}

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:

#!/bin/bash

REGION="cn-hangzhou"
INSTANCE_ID="es-cn-xxx****"

echo "=== Step 1: Verify Instance Exists ==="
aliyun elasticsearch describe-instance \
  --region $REGION \
  --instance-id $INSTANCE_ID \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

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}" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID}

echo ""
echo "=== Step 3: Verify Instance Status ==="
STATUS=$(aliyun elasticsearch describe-instance \
  --region $REGION \
  --instance-id $INSTANCE_ID \
  --cli-query "Result.status" \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID} | tr -d '"')

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

---

Error Handling

Common Error Codes

Troubleshooting Commands

# 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/${SESSION_ID}

# 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/${SESSION_ID}

---

References

• Elasticsearch Status Codes
• Error Handling