alibabacloud-ack-cli — Claude Code skill: manage ACK clusters from CLI
alibabacloud-ack-cli — a skill that drives Alibaba Cloud ACK from the terminal: clusters, node pools, addons, kubeconfig via aliyun cs. Handy when kubectl won't connect or RAM answers Forbidden.RAM.
Apache-2.0 196 installs ★ 300 updated 2026-10-23
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a claude-codeWhat alibabacloud-ack-cli does
The skill gives the agent a working map of ACK through the cs plugin of the aliyun CLI: cluster lifecycle, node pools, addons, kubeconfig and RBAC for RAM users, CVE scanning and repair, audit logging, inspections, plus async tasks you can track, pause, resume or cancel. Commands stay in the kebab-case plugin form. The older PascalCase OpenAPI shape is off limits here.
Before composing anything it runs --help, since parameter shapes for cluster creation and addon config are easy to get wrong. Every business call carries --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id}, with one id reused for the whole session. Scripts under ./scripts/ check and install the plugin, and wait on a task-id in a given region.
You need aliyun CLI 3.3.3 or newer with the cs plugin (aliyun plugin install --names cs), jq for the helper scripts, kubectl to use the kubeconfig it fetches, and network access to *.aliyuncs.com. Leave the plugin out and nothing runs: plugin 'cs' not found.
What it helps with
- create an ACK cluster and poll the async task to completion
- patch a node CVE without opening the console
- issue a kubeconfig to a RAM user, then revoke it
- find out why kubectl cannot reach the cluster
- upgrade an addon without hitting a deprecated API
Example prompts for the agent
- Create an ACK cluster in
cn-hangzhouand follow the task until it finishes. - Revoke the kubeconfig issued to a RAM user and confirm kubectl can no longer connect.
- Show which addons in the cluster are outdated and update them one at a time.
How to install alibabacloud-ack-cli
1Skills CLI (Vercel)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a claude-code2Manually: put the files in place
~/.claude/skills/alibabacloud-ack-cli/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/alibabacloud-ack-cli/
1Skills CLI (Vercel)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a codex2Manually: put the files in place
.agents/skills/alibabacloud-ack-cli/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a cursor2Manually: put the files in place
.cursor/skills/alibabacloud-ack-cli/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aliyun/alibabacloud-aiops-skills skills/container/csk/alibabacloud-ack-cli2Manually: put the files in place
.github/skills/alibabacloud-ack-cli/SKILL.md1Skills CLI (Vercel)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a gemini-cli2Platform CLI
gemini skills install https://github.com/aliyun/alibabacloud-aiops-skills --path skills/container/csk/alibabacloud-ack-cliManually: put the files in place
.devin/skills/alibabacloud-ack-cli/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about alibabacloud-ack-cli
How do I install Anthropic-ack-cli in Claude Code?
Run npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ack-cli -a claude-code. The skill lands in ~/.claude/skills/alibabacloud-ack-cli/SKILL.md.
What does alibabacloud-ack-cli do?
It turns ACK tasks into aliyun cs commands: creating and upgrading clusters, scaling node pools, installing addons, issuing kubeconfig and RBAC, running inspections, tracking async tasks.
What do I need before the skill can run?
aliyun CLI 3.3.3 or newer with the cs plugin, jq for the bundled scripts, and kubectl if you plan to connect with a fetched kubeconfig. Network access to *.aliyuncs.com is required too.
Source text
SKILL.md · Apache-2.0
--- name: alibabacloud-ack-cli description: > Use when the user operates Alibaba Cloud Container Service for Kubernetes (ACK). Covers cluster lifecycle (create / modify / delete / upgrade), node pools & nodes (create, modify, delete, repair, fix CVE), addons (install / upgrade / uninstall), KubeConfig & RBAC (issue for RAM user, grant / revoke), security & policy (CVE scan/fix, policy governance, KMS, delete protection), logging / audit / alerting, intelligent O&M (check / inspect / diagnosis / auto-repair), async tasks (track / pause / resume / cancel), templates, autoscaling, tags & quotas. Triggers: create / upgrade / delete ACK cluster, migrate to Pro, scale nodepool, fix node CVE, install / remove addon, get / revoke kubeconfig, grant RBAC, enable audit log, run inspection, diagnose cluster, track task_id, debug cs error, Forbidden.RAM, kubectl cannot connect. Terms: ACK, container service, k8s cluster, nodepool, addon, AutoMode, Terway, Flannel, ForRegion, kubeconfig, RBAC, CVE. license: Apache-2.0 metadata: domain: aiops owner: ack-team contact: [email protected] compatibility: > Requires aliyun CLI >= 3.3.3 with the cs plugin (aliyun plugin install --names cs). Helper scripts use jq; kubeconfig retrieval pairs with kubectl. Network access to *.aliyuncs.com OpenAPI endpoints required. allowed-tools: Bash --- # ACK (Container Service) CLI Expert Help users manage Alibaba Cloud Container Service for Kubernetes (ACK) from the terminal using the `aliyun cs` plugin. Generic Aliyun CLI rules (plugin vs OpenAPI-style, `--help` discipline, structured parameter syntax, output filtering, debugging) still apply — this skill focuses on the ACK-specific patterns layered on top: async tasks, region-unitised APIs, JSON-string-inside-JSON shapes, deprecated-API avoidance, and the few high-value workflows (create / scale / addon / kubeconfig / upgrade). > **Version note.** Concrete API/parameter lists below were captured against `aliyun-cli` 3.3.2 + `cs` plugin 0.2.1. If your plugin is newer, re-run the self-discovery commands embedded throughout this skill to refresh: > > ```bash > aliyun cs --help | grep -- '-for-region' # §6 ForRegion list > aliyun cs <cmd> --help | grep '废弃' # §7 deprecated check per command (CLI marks deprecation only in Chinese) > aliyun cs --help | awk '/^ [a-z]/{print $1}' | while read c; do # §11 cursor-paginated commands > aliyun cs "$c" --help 2>&1 | grep -q -- '--next-token' && echo "$c" > done > ``` ## Observability (MUST follow for every `cs` command) Upon loading this skill, generate a random session ID — a 32-character lowercase hex string — **once for the entire session**. Use it as `{session-id}` below. **Rule: every `aliyun cs` command that calls a cloud API MUST carry the `--user-agent` flag, in exactly this form:** --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} `{session-id}` rules: - **Generate once per session**, before the first business command — never per command: `uuidgen | tr -d '-' | tr 'A-F' 'a-f'` (Linux alternative: `cat /proc/sys/kernel/random/uuid | tr -d '-'`). - **32 lowercase hex characters**, no dashes, no prefix, no truncation. - **Reuse the identical value** in every subsequent `aliyun cs` call of that session, so backend analytics can correlate the whole workflow (create → poll task → fetch kubeconfig) as one unit. - Pass the same id to the bundled scripts by injecting it inline: `SKILL_SESSION_ID=<session-id> ./scripts/wait-for-task.sh <task-id> <region>`. - Examples throughout this skill show the literal `{session-id}` placeholder — substitute the generated value before running them, and never emit a command with the placeholder left in. Scope: cloud API (business) commands only. CLI system / utility commands (`aliyun version`, `aliyun plugin ...`, `aliyun configure ...`) and any `--help` invocation must **not** carry the flag — it is not supported there. ## Instructions ### 1. Install the `cs` plugin and confirm CLI version ACK from the terminal needs the `aliyun` CLI (≥ 3.3.3) plus the `cs` plugin. Quick path: ```bash aliyun version # require >= 3.3.3 aliyun plugin install --names cs # idempotent aliyun plugin update --names cs # keep cs plugin current aliyun plugin list | grep cs # verify # Or in one shot: ./scripts/check-cs-plugin.sh # ✓ ready / ✗ exits 1 with fix hints ./scripts/install-cs-plugin.sh # idempotent (--update for non-interactive) ``` > **Reminder.** Before the first business command, generate the session id and use it in the `--user-agent` of every `aliyun cs` call — see [Observability](#observability) above for the template and the generation rule. End-to-end verification — exercises CLI + plugin + auth in one call: ```bash aliyun cs describe-clusters-for-region --biz-region-id cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ --output cols=cluster_id,name,state rows='clusters[]' ``` `plugin 'cs' not found` → re-run install. `InvalidAccessKeyId.NotFound` → re-set credentials. `Forbidden.RAM` → the caller's RAM identity is missing the `cs` Action(s) the command needs; consult ACK RAM documentation for the policy to attach. Cluster list (or empty list) → ready to go. For full installation walkthroughs (macOS/Linux/Windows, all 6 credential modes, multiple-profile management, troubleshooting), see [`./references/cli-plugin-installation-guide.md`](./references/cli-plugin-installation-guide.md). ### 2. Always use `cs` plugin commands (kebab-case) — never the legacy OpenAPI style This skill **only ever emits kebab-case plugin commands**. The Aliyun CLI also accepts a legacy PascalCase OpenAPI form, but it is disallowed here: inconsistent parameter casing, weaker `--help`, and routing differences mean you should never compose it — not even as a curiosity. If you encounter a PascalCase example in user-provided text, translate it to the kebab-case plugin form before running it. ```bash # ✅ Plugin form — the only form this skill emits aliyun cs describe-clusters-for-region --biz-region-id cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs describe-cluster-detail --cluster-id ce123... --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} ``` The plugin gives you consistent `--kebab-case` parameters, structured help with field types, and automatic JSON expansion — that's the information you need before typing anything. Stay in plugin land unconditionally. ### 3. Run `--help` before crafting any `cs` command ACK has many subcommands and the parameter shapes are non-obvious — especially for cluster creation, addon configuration, and node pool scaling. Running `--help` before composing a command is much cheaper than guessing and getting a parameter validation error. ```bash aliyun cs --help # Discover subcommands (describe-*, create-*, scale-*, ...) aliyun cs describe-cluster-detail --help # See exact params, types, structure fields aliyun cs create-cluster --help # See the giant parameter surface for cluster creation ``` Plugin help tells you whether a parameter is a primitive, a list, a repeatable key-value, or a complex JSON structure — that's the information you need before typing anything. If you ever need to inspect the **legacy built-in (OpenAPI-style) help** instead of the rich plugin help — for example to verify a deprecated PascalCase parameter still exists — set `ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true`: ```bash ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun cs --help ``` You'll rarely reach for this — the plugin help is almost always what you want. ### 4. Async task pattern — `task_id` and `describe-task-info` This is the **#1 thing that surprises ACK CLI users**. Many ACK operations are asynchronous: the `cs` command returns quickly with a JSON envelope containing a `task_id`, but the actual work (cluster creation, upgrade, scaling, addon install) continues in the background. You must poll the task to know whether it succeeded. Operations that return a task: - `cs create-cluster`, `cs delete-cluster` - `cs upgrade-cluster` (control plane only; control via `cs pause-task` / `cs resume-task` / `cs cancel-task`) - `cs modify-cluster-node-pool` (the preferred way to set absolute node count via `desired_size`; see §7), `cs scale-cluster-node-pool` (delta only — discouraged, see §7), `cs upgrade-cluster-nodepool`, `cs create-cluster-node-pool`, `cs delete-cluster-nodepool` - `cs install-cluster-addons`, `cs upgrade-cluster-addons`, `cs un-install-cluster-addons` - Some component / migration tasks Once you have a `task_id`, the **task-control commands work uniformly across task types** — not just upgrades. Pause / resume / cancel any in-flight ACK task with: ```bash aliyun cs pause-task --task-id <tid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs resume-task --task-id <tid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs cancel-task --task-id <tid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} ``` Use `cancel-task` to abort a stuck addon install, a runaway node pool scale, or any other in-flight task. Typical response: ```json { "cluster_id": "ce914461c0fb4901ae8908be4a10a7a1", "request_id": "DDA4DB1A-A7E3-1455-A6FB-77F58F01A43E", "task_id": "T-69ce1022aa09ae010300000b" } ``` Track it with: ```bash aliyun cs describe-task-info --task-id T-69ce1022aa09ae010300000b --region cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} ``` Pass `--region` matching the cluster's region — task IDs are region-scoped and looking them up via the default endpoint adds latency. The task response carries `state` (running / success / failed) and an `error` field on failure. When polling, **ask the user before starting a long busy-wait loop** — polling burns tokens and the user may prefer to check back later. A reasonable default is to poll every 30s with a sensible max (e.g. 30 minutes for cluster create, 5 minutes for addon install) and surface the `error.message` if the task fails. The bundled helper `./scripts/wait-for-task.sh <task-id> <region-id>` polls with backoff and prints the final state — use it after confirming with the user. Region is required because task IDs are region-scoped. See `./references/async-tasks.md` for full details: state machine, error fields, typical durations per operation, and how to interpret partial-failure responses. ### 5. Complex JSON parameters — Terway, AutoMode, addons Some ACK parameters can't be expressed cleanly as flat flags. Examples: **Terway with multi-AZ pod vswitches** (cluster create): ```bash # Pass the addons array as JSON. Note the nested JSON inside `config` is a STRING. aliyun cs create-cluster \ --biz-region-id cn-beijing \ --region cn-beijing \ --cluster-type ManagedKubernetes \ --addons '[{"name":"terway-eniip","config":"{\"PodVswitchId\":{\"cn-beijing-l\":[\"vsw-a\"],\"cn-beijing-h\":[\"vsw-b\"]}}"}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ ... ``` The trap: `config` is a JSON-encoded string inside a JSON document. Build it in a file or via `jq` rather than hand-escaping — escape errors are the most common cause of `InvalidParameter.Format` from this API. **Flannel** (requires `container_cidr`, no `PodVswitchId`): ```bash --addons '[{"name":"flannel"}]' \ --container-cidr 172.20.0.0/16 \ --service-cidr 172.21.0.0/20 ``` **AutoMode** (ACK best-practice profile — single flag turns it on): ```bash --profile Default \ --cluster-spec ack.pro.small \ --auto-mode '{"enable":true}' ``` When AutoMode is enabled, ACK chooses sensible defaults for VPC, networking, node pools, and addons — most other knobs become unnecessary. **Addon install with config**: ```bash aliyun cs install-cluster-addons --cluster-id <cid> --region <region> \ --body '[{"name":"logtail-ds","config":"{\"sls_project_name\":\"k8s-log\"}"}]' \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} ``` The nested-JSON-as-string pattern shows up in nearly every addon install. Read the addon's `config_schema` first (`cs list-addons --cluster-id ...` for the full list, or `cs describe-addon --cluster-id ... --addon-name ...` for one) to know valid keys. For full examples, see `./references/cs-scenarios.md`. ### 6. Region-unitised API calling — two rules ACK has moved to a region-unitised model. Two rules apply: **Rule A — Prefer `*ForRegion` API variants** (`describe-clusters-for-region`, `describe-events-for-region`, `list-operation-plans-for-region`). Faster, higher quotas, resilient when global aggregator degrades. Re-discover with `aliyun cs --help | grep -- '-for-region'`. These APIs take `--biz-region-id` (business parameter, required), **not** `--region`. **Rule B — Pass `--region <region>` on every cluster-id-scoped call** (`describe-cluster-detail`, `modify-cluster-node-pool`, etc.) once you know the region. Routes directly to the regional endpoint, avoids default-endpoint hop. `--region` (CLI global, endpoint routing) and `--biz-region-id` (API business parameter) take the same value but play different roles. There is no `--region-id` flag. Always `--help` first to see which a command expects. ```bash # Region-unitised + direct routing combined REGION=cn-hangzhou aliyun cs describe-clusters-for-region --biz-region-id $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Rule A aliyun cs describe-cluster-detail --cluster-id <cid> --region $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Rule B aliyun cs describe-cluster-node-pools --cluster-id <cid> --region $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Rule B ``` ### 7. Detect deprecated parameters per command The CLI marks deprecated parameters in `--help` with the Chinese string `【该参数已废弃】` (no English equivalent — has to be matched literally). Run the snippet from the top of this file (`aliyun cs <cmd> --help | grep '废弃'`) before composing any command — it surfaces both the deprecated field and the suggested replacement (e.g. `请使用 next_version 参数替代`). Quote that line back to the user; never silently substitute. ### 8. Common high-value commands Examples assume the cluster's region is already known (via Rule A discovery or from the user) and pass it as `--region` per §6 Rule B. Substitute `<region>` with the actual value. ```bash # Clusters aliyun cs describe-clusters-for-region --biz-region-id <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs describe-cluster-detail --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs describe-cluster-user-kubeconfig --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} > kubeconfig.yaml aliyun cs upgrade-cluster --cluster-id <cid> --region <region> --next-version 1.30.1-aliyun.1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Node pools aliyun cs describe-cluster-node-pools --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs describe-cluster-node-pool-detail --cluster-id <cid> --nodepool-id <npid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Resize to an ABSOLUTE node count: use modify-cluster-node-pool with desired_size. # (`scale-cluster-node-pool --count N` adds N nodes — it's a delta, not an # absolute target, and is rarely what users mean by "scale to 5". See §7.) aliyun cs modify-cluster-node-pool --cluster-id <cid> --nodepool-id <npid> --region <region> \ --scaling-group desired_size=5 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs upgrade-cluster-nodepool --cluster-id <cid> --nodepool-id <npid> --kubernetes-version <ver> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Addons aliyun cs list-addons --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # what's available + config_schema aliyun cs describe-addon --cluster-id <cid> --addon-name <name> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # one addon's metadata + config_schema aliyun cs list-cluster-addon-instances --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # what's installed (versions, status) aliyun cs install-cluster-addons --cluster-id <cid> --region <region> --body '[{"name":"logtail-ds","config":"{}"}]' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs upgrade-cluster-addons --cluster-id <cid> --region <region> --body '[{"component_name":"logtail-ds","next_version":"1.8.0"}]' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs un-install-cluster-addons --cluster-id <cid> --region <region> --body '[{"name":"logtail-ds"}]' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # Tasks (task IDs are region-scoped — pass the cluster's region) aliyun cs describe-task-info --task-id <tid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} aliyun cs describe-cluster-tasks --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # all tasks under a cluster aliyun cs describe-cluster-events --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # operational events: creates, scales, addon installs aliyun cs describe-cluster-events --cluster-id <cid> --region <region> --task-id <tid> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # filter to one task's events ``` For "what's been happening on this cluster recently?" / "why did the upgrade last week fail?", `describe-cluster-tasks` and `describe-cluster-events` are the answer. They're paginated (`--page-number` / `--page-size`); use `--pager` for auto-merge across pages. For any of these, append `--help` to see the full parameter set and structure. See `./references/cs-scenarios.md` for fuller workflows. ### 9. Kubeconfig retrieval and `kubectl` handoff ```bash # Default kubeconfig (intranet endpoint depending on cluster network) aliyun cs describe-cluster-user-kubeconfig --cluster-id <cid> --region <region> \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ | jq -r '.config' > ~/.kube/config.ack export KUBECONFIG=~/.kube/config.ack kubectl get nodes ``` Notes: - Some clusters expose only an intranet API server endpoint; the kubeconfig you fetch will only work from inside the VPC. Use `--private-ip-address true|false` to choose between intranet and public endpoints when both exist. - Temporary STS-based kubeconfigs expire — re-run the command to refresh. - For automation, prefer setting `KUBECONFIG` to a per-cluster file rather than overwriting `~/.kube/config`. ### 10. Filter and format output Same pattern as the rest of the CLI: `--cli-query` (JMESPath) plus `--output`. Useful with ACK because cluster/nodepool/addon list responses are nested: ```bash # Just running cluster IDs and names aliyun cs describe-clusters-for-region --biz-region-id cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ --cli-query "clusters[?state=='running'].{id:cluster_id,name:name,version:current_version}" \ --output table # Recent operation plans (auto-upgrade, AutoMode, CVE fixes) for the region aliyun cs list-operation-plans-for-region --biz-region-id cn-hangzhou \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ --cli-query "plans[].{id:plan_id,type:type,state:state,scheduled:scheduled_time}" # Just node pool IDs and current size aliyun cs describe-cluster-node-pools --cluster-id <cid> --region <region> \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ --cli-query "nodepools[].{id:nodepool_info.nodepool_id,name:nodepool_info.name,size:status.total_nodes}" ``` ### 11. Pagination — prefer cursor, auto-merge with `--pager` Two styles: **cursor** (`--next-token` / `--max-results`, stable under concurrent writes — preferred) and **offset** (`--page-number` / `--page-size`, can shift mid-scan). Check `--help` to see which a command supports — cursor wins if both are listed. The CLI's `--pager` flag auto-merges pages either way; almost always what users want. See [`./references/cs-scenarios.md`](./references/cs-scenarios.md) §9 for `--pager` syntax and a hand-rolled cursor loop example. ### 12. Debugging — and dry-run before any write ACK write operations provision real cloud resources and many are irreversible. **Always run a write command with `--cli-dry-run` first** when the parameter set is non-trivial — it serialises the exact payload and validates parameter parsing without spending the call: ```bash aliyun cs create-cluster --biz-region-id cn-beijing --region cn-beijing \ --cluster-type ManagedKubernetes \ --profile Default --cluster-spec ack.pro.small --auto-mode '{"enable":true}' \ --name my-ack-cluster --kubernetes-version 1.30.1-aliyun.1 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \ --cli-dry-run aliyun cs modify-cluster-node-pool --cluster-id <cid> --nodepool-id <npid> \ --region <region> --scaling-group desired_size=10 \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} --cli-dry-run ``` When a `cs` command does fail, `--log-level debug` reveals the full request/response so you can see endpoint, body, status, and the raw error: ```bash aliyun cs describe-cluster-detail --cluster-id <cid> --region <region> \ --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} --log-level debug ``` For specific error patterns and first-action recipes (plugin / parameter / format / region / auth / RAM / async-task failures, plus a sample dry-run output), see [`./references/error-catalogue.md`](./references/error-catalogue.md). ## Response format guidance When helping a user with `cs` commands: 1. **Read intent first.** Are they investigating ("describe / list"), modifying ("scale / upgrade / install"), or creating? Modify/create flows almost always produce a `task_id` — surface that pattern early. 2. **Show the full command** with required parameters and explain non-obvious ones (`--region`, the JSON-string-inside-JSON for addon config, etc.). 3. **For async ops, mention `describe-task-info`** in the same response — and ask before busy-waiting. 4. **Suggest `--help` and `--log-level debug`** when the user is troubleshooting. 5. **Cite the cluster's region** — most "command works in cn-hangzhou but not cn-shanghai" issues are missing/wrong `--region`. ## References Four reference files, all ACK-specific. Generic CLI knowledge (hidden global flags like `--waiter` / `--header` / `--body` / `--secure`, multi-version API, full security best practices) is the Aliyun CLI's responsibility — consult its own documentation when needed. 1. `./references/cs-scenarios.md` — **Most useful day-to-day.** Worked end-to-end examples: discovery, kubeconfig, node pools, addons, cluster upgrade, delete, the create→wait→kubeconfig pipeline. 2. `./references/async-tasks.md` — `task_id` lifecycle, state vocabulary, polling strategy, common `error.code` causes, partial-failure handling. 3. `./references/cli-plugin-installation-guide.md` — Aliyun CLI install (macOS/Linux/Windows), credential modes summary, `cs` plugin install, end-to-end verification, troubleshooting. Read once at setup; come back for "I can't get past `Forbidden.RAM`"-class issues. 4. `./references/ram-policies.md` — RAM Actions and policy templates required by this skill's `aliyun cs` calls (cluster / nodepool / addon / task scopes). Scripts: - `./scripts/check-cs-plugin.sh` — Verify aliyun CLI ≥ 3.3.3 and the `cs` plugin is installed - `./scripts/install-cs-plugin.sh` — Install or update the `cs` plugin (idempotent; supports `--update` for non-interactive) - `./scripts/wait-for-task.sh` — Poll `describe-task-info` until terminal state (requires task ID + region)
© aliyun · Apache-2.0 · aliyun/alibabacloud-aiops-skills