/alibabacloud-ack-cli

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: ack-team@alibabacloud.com
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:

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:

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