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:
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:
Generate once per session, before the first business command — never per command: (Linux alternative: ).
uuidgen | tr -d '-' | tr 'A-F' 'a-f'
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:
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 above for the template and the generation rule.
End-to-end verification — exercises CLI + plugin + auth in one call:
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.
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.
# ✅ 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.
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:
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
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:
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.
Some ACK parameters can't be expressed cleanly as flat flags. Examples:
Terway with multi-AZ pod vswitches (cluster create):
# 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):
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.
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.
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.
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:
# 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 §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:
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.
Response format guidance
When helping a user with cs commands:
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.
Show the full command with required parameters and explain non-obvious ones (--region, the JSON-string-inside-JSON for addon config, etc.).
For async ops, mention describe-task-info in the same response — and ask before busy-waiting.
Suggest --help and --log-level debug when the user is troubleshooting.
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.
./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.
./references/async-tasks.md — task_id lifecycle, state vocabulary, polling strategy, common error.code causes, partial-failure handling.
./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.
./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)
