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.
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.
bash
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:
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.
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
Command kind
--user-agent?
Value
Business API CLI (e.g. aliyun elasticsearch create-instance, aliyun elasticsearch list-dicts, …)
These commands do NOT support --user-agent — never attach the flag.
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"):
STOP immediately — do NOT execute any command
Reject the request politely with the following message:
text
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.
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.
REQUIRED and MUST be explicitly provided by the user. NEVER guess. NEVER use a default region.
--instance-id
REQUIRED for any per-instance operation. MUST be explicitly provided by the user.
--user-agent
Scope: business API commands ONLY (e.g. aliyun elasticsearch ...). Such commands MUST explicitly pass --user-agent AlibabaCloud-Agent-Skills/alibabacloud-elasticsearch-instance-manage/${SESSION_ID} (see Observability). System / tool commands (aliyun configure, aliyun version, aliyun plugin update, aliyun help, etc.) MUST NOT carry --user-agent — these commands do not support the flag.
--body
All ROA APIs accept --body '<JSON>' for complex request bodies. Use --body $(cat payload.json) to read from a file.
--cli-query
Prefer JMESPath projection (--cli-query "Result[].{...}") for readable outputs in list-style APIs.
Idempotency for Write Operations
For write APIs (createInstance, RestartInstance, UpdateInstance, CreateSnapshot, UpdateSnapshotSetting, UpdateDict, UpdateHotIkDicts, UpdateSynonymsDicts, UpdateAliwsDict, UpdateKibanaSettings, UpdateInstanceSettings, InstallSystemPlugin, UninstallPlugin, UpdateInstanceChargeType, UpgradeEngineVersion) 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 sameclientToken. Wait ~10 seconds before retrying.
Duplicate calls with the same clientToken will not re-execute the operation.
bash
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.
