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
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)
AI-Mode declaration. Before issuing any aliyun business command from
this skill, declare AI-Mode and a stable User-Agent so the backend can
attribute traffic and apply AI-safe defaults. These three commands are
session-level configuration — set once, reused implicitly by all
subsequent business calls:
Every aliyun cs <verb> business command in this skill carries
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli
(shown explicitly in every example below).
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.
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
aliyun cs describe-cluster-detail --cluster-id ce123... --region cn-hangzhou \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli
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:
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):
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 \
...
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):
When AutoMode is enabled, ACK chooses sensible defaults for VPC, networking,
node pools, and addons — most other knobs become unnecessary. --cluster-spec
valid values are only ack.pro.small (Pro, recommended for AutoMode) and
ack.standard (default if omitted) — don't guess ack.pro.large or others.
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:
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 \
--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 \
--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 \
--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)
