alibabacloud-ack-cli：容器服务 ACK 命令行工具使用，覆盖 ACK 集群全生命周期管理

ACK（容器服务）CLI 专家

帮助用户使用 aliyun cs 插件从终端管理阿里云容器服务 Kubernetes 版（ACK）。通用阿里云 CLI 规则（插件 vs OpenAPI 风格、--help 纪律、结构化参数语法、输出过滤、调试）仍然适用——本 Skill 聚焦 ACK 特有的分层模式：异步任务、按地域单元化 API、JSON 中嵌 JSON 的形态、废弃 API 规避，以及几个高价值工作流（创建/扩缩容/插件/kubeconfig/升级）。

版本说明。 下面的具体 API/参数列表基于 aliyun-cli 3.3.2 + cs 插件 0.2.1 捕获。如果你的插件更新，重新运行本 Skill 中嵌入的自发现命令以刷新：
```bash
aliyun cs --help | grep -- '-for-region' # §6 ForRegion 列表
aliyun cs <cmd> --help | grep '废弃' # §7 逐命令废弃检查（CLI 仅用中文标记废弃）
aliyun cs --help | awk '/^ [a-z]/{print $1}' | while read c; do # §11 游标分页命令
aliyun cs "$c" --help 2>&1 | grep -q -- '--next-token' && echo "$c"
done
```

可观测性（每条 cs 命令必须遵循）

加载本 Skill 时，生成一个随机 session ID——32 位小写十六进制字符串——整个会话生成一次。下文用作 {session-id}。

规则：每条调用云 API 的 aliyun cs 命令都必须携带 --user-agent flag，格式精确如下：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id}

{session-id} 规则：

• 每会话生成一次，在第一条业务命令之前——绝不每条命令生成：uuidgen | tr -d '-' | tr 'A-F' 'a-f'（Linux 替代：cat /proc/sys/kernel/random/uuid | tr -d '-'）。
• 32 位小写十六进制字符，无连字符、无前缀、无截断。
• 该会话中后续每条 aliyun cs 调用都复用同一值，使后端分析可将整个工作流（创建 → 轮询任务 → 获取 kubeconfig）作为一个单元关联。
• 通过内联注入将同一 ID 传给捆绑脚本：SKILL_SESSION_ID=<session-id> ./scripts/wait-for-task.sh <task-id> <region>。
• 本 Skill 中的示例显示字面占位符 {session-id}——运行前替换为生成的值，绝不输出仍带占位符的命令。

范围：仅云 API（业务）命令。CLI 系统/实用命令（aliyun version、aliyun plugin ...、aliyun configure ...）和任何 --help 调用不得携带该 flag——那里不支持。

使用说明

1. 安装 cs 插件并确认 CLI 版本

从终端操作 ACK 需要 aliyun CLI（≥ 3.3.3）加 cs 插件。快速路径：

aliyun version                          # 需要 >= 3.3.3
aliyun plugin install --names cs        # 幂等
aliyun plugin update  --names cs        # 保持 cs 插件为最新
aliyun plugin list | grep cs            # 验证

或一条命令：

./scripts/check-cs-plugin.sh # ✓ ready / ✗ 退出码 1 并带修复提示

./scripts/install-cs-plugin.sh # 幂等（--update 用于非交互式）

> **提醒。** 在第一条业务命令之前，生成 session ID 并在每条 `aliyun cs` 调用的 `--user-agent` 中使用它——模板和生成规则见上方[可观测性](#可观测性)。

端到端验证——一次调用同时检验 CLI + 插件 + 认证：

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` → 重新运行安装。`InvalidAccessKeyId.NotFound` → 重新设置凭证。`Forbidden.RAM` → 调用方 RAM 身份缺少命令所需的 `cs` Action；查阅 ACK RAM 文档获取要附加的策略。集群列表（或空列表）→ 就绪。

完整安装引导（macOS/Linux/Windows、全部 6 种凭证模式、多 profile 管理、故障排查），见 [`./references/cli-plugin-installation-guide.md`](./references/cli-plugin-installation-guide.md)。

### 2. 始终使用 `cs` 插件命令（kebab-case）——绝不用遗留 OpenAPI 风格

本 Skill **只输出 kebab-case 插件命令**。阿里云 CLI 也接受遗留 PascalCase OpenAPI 形式，但此处不允许：参数大小写不一致、`--help` 较弱、路由差异，意味着你绝不应构造它——即使出于好奇也不行。如果在用户提供的文本中遇到 PascalCase 示例，在运行前翻译为 kebab-case 插件形式。

✅ 插件形式——本 Skill 唯一输出的形式

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}

插件给你一致的 `--kebab-case` 参数、带字段类型的结构化帮助和自动 JSON 展开——这就是你在输入任何内容之前需要的信息。无条件留在插件领域。

### 3. 构造任何 `cs` 命令之前运行 `--help`

ACK 有很多子命令且参数形态不明显——尤其是集群创建、插件配置和节点池扩缩容。构造命令前运行 `--help` 比猜测后得到参数校验错误便宜得多。

aliyun cs --help # 发现子命令（describe-*、create-*、scale-*、...）

aliyun cs describe-cluster-detail --help # 查看确切参数、类型、结构字段

aliyun cs create-cluster --help # 查看集群创建的巨大参数面

插件帮助告诉你参数是原始类型、列表、可重复键值还是复杂 JSON 结构——这就是你在输入任何内容之前需要的信息。

如果你需要检查**遗留内置（OpenAPI 风格）帮助**而非丰富的插件帮助——例如验证某个废弃的 PascalCase 参数是否仍存在——设置 `ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true`：

ALIBABA_CLOUD_ORIGINAL_PRODUCT_HELP=true aliyun cs --help

你很少会用到这个——插件帮助几乎总是你想要的。

### 4. 异步任务模式——`task_id` 和 `describe-task-info`

这是**让 ACK CLI 用户最意外的 #1 件事**。许多 ACK 操作是异步的：`cs` 命令快速返回包含 `task_id` 的 JSON 封装，但实际工作（集群创建、升级、扩缩容、插件安装）在后台继续。你必须轮询任务以知道是否成功。

返回任务的操作：

- `cs create-cluster`、`cs delete-cluster`
- `cs upgrade-cluster`（仅控制面；通过 `cs pause-task` / `cs resume-task` / `cs cancel-task` 控制）
- `cs modify-cluster-node-pool`（通过 `desired_size` 设置绝对节点数的首选方式；见 §7）、`cs scale-cluster-node-pool`（仅增量——不推荐，见 §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`
- 某些组件/迁移任务

一旦你有了 `task_id`，**任务控制命令在所有任务类型上统一工作**——不仅是升级。用以下命令暂停/恢复/取消任何进行中的 ACK 任务：

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}

用 `cancel-task` 中止卡住的插件安装、失控的节点池扩缩容或任何其他进行中的任务。

典型响应：

{

"cluster_id": "ce914461c0fb4901ae8908be4a10a7a1",

"request_id": "DDA4DB1A-A7E3-1455-A6FB-77F58F01A43E",

"task_id": "T-69ce1022aa09ae010300000b"

}

跟踪它：

aliyun cs describe-task-info --task-id T-69ce1022aa09ae010300000b --region cn-hangzhou \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id}

传与集群地域匹配的 `--region`——任务 ID 是地域范围的，通过默认 endpoint 查找会增加延迟。

任务响应携带 `state`（running / success / failed）和失败时的 `error` 字段。轮询时，**在开始长时间忙等循环前先询问用户**——轮询消耗 token，用户可能更愿意稍后检查。合理的默认是每 30 秒轮询一次并设置合理最大值（例如集群创建 30 分钟，插件安装 5 分钟），并在任务失败时暴露 `error.message`。

捆绑辅助脚本 `./scripts/wait-for-task.sh <task-id> <region-id>` 带退避轮询并打印最终状态——与用户确认后使用。地域是必需的，因为任务 ID 是地域范围的。

完整详情见 `./references/async-tasks.md`：状态机、错误字段、每个操作的典型持续时间，以及如何解读部分失败响应。

### 5. 复杂 JSON 参数——Terway、AutoMode、插件

某些 ACK 参数无法用扁平 flag 干净表达。例如：

**Terway 多可用区 Pod vswitch**（集群创建）：

以 JSON 传递 addons 数组。注意 config 内的嵌套 JSON 是字符串。

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} \

...

陷阱：`config` 是 JSON 文档内 JSON 编码的字符串。在文件或用 `jq` 中构建，而非手工转义——转义错误是此 API 返回 `InvalidParameter.Format` 的最常见原因。

**Flannel**（需要 `container_cidr`，无 `PodVswitchId`）：

--addons '[{"name":"flannel"}]' \

--container-cidr 172.20.0.0/16 \

--service-cidr 172.21.0.0/20

**AutoMode**（ACK 最佳实践 profile——单个 flag 即可开启）：

--profile Default \

--cluster-spec ack.pro.small \

--auto-mode '{"enable":true}'

启用 AutoMode 时，ACK 为 VPC、网络、节点池和插件选择合理默认值——大多数其他旋钮变得不必要。

**带配置的插件安装**：

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}

嵌套 JSON 作为字符串的模式几乎出现在每次插件安装中。先阅读插件的 `config_schema`（`cs list-addons --cluster-id ...` 获取完整列表，或 `cs describe-addon --cluster-id ... --addon-name ...` 获取单个）以了解有效键。完整示例见 `./references/cs-scenarios.md`。

### 6. 按地域单元化 API 调用——两条规则

ACK 已迁移到按地域单元化模型。两条规则适用：

**规则 A —— 优先 `*ForRegion` API 变体**（`describe-clusters-for-region`、`describe-events-for-region`、`list-operation-plans-for-region`）。更快、配额更高、全局聚合器降级时更稳健。用 `aliyun cs --help | grep -- '-for-region'` 重新发现。这些 API 接受 `--biz-region-id`（业务参数，必填），**不是** `--region`。

**规则 B —— 在每个集群 ID 范围的调用上传递 `--region <region>`**（`describe-cluster-detail`、`modify-cluster-node-pool` 等），一旦你知道地域。直接路由到地域 endpoint，避免默认 endpoint 跳转。

`--region`（CLI 全局，endpoint 路由）和 `--biz-region-id`（API 业务参数）取相同值但扮演不同角色。没有 `--region-id` flag。始终先 `--help` 查看命令期望哪个。

按地域单元化 + 直接路由组合

REGION=cn-hangzhou

aliyun cs describe-clusters-for-region --biz-region-id $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 规则 A

aliyun cs describe-cluster-detail --cluster-id <cid> --region $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 规则 B

aliyun cs describe-cluster-node-pools --cluster-id <cid> --region $REGION --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 规则 B

### 7. 检测逐命令的废弃参数

CLI 在 `--help` 中用中文字符串 `【该参数已废弃】` 标记废弃参数（无英文对应——必须字面匹配）。构造任何命令前运行本文件顶部的片段（`aliyun cs <cmd> --help | grep '废弃'`）——它会暴露废弃字段和建议替代（例如 `请使用 next_version 参数替代`）。将该行引用给用户；绝不静默替换。

### 8. 常用高价值命令

示例假设集群地域已知（通过规则 A 发现或来自用户），并按 §6 规则 B 传 `--region`。将 `<region>` 替换为实际值。

集群

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}

节点池

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}

调整到绝对节点数：使用带 desired_size 的 modify-cluster-node-pool。

（scale-cluster-node-pool --count N 添加 N 个节点——它是增量，不是

绝对目标，很少是用户说“扩到 5”的意思。见 §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}

插件

aliyun cs list-addons --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 可用项 + config_schema

aliyun cs describe-addon --cluster-id <cid> --addon-name <name> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 单个插件元数据 + config_schema

aliyun cs list-cluster-addon-instances --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 已安装（版本、状态）

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}

任务（任务 ID 是地域范围的——传集群地域）

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} # 集群下所有任务

aliyun cs describe-cluster-events --cluster-id <cid> --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 运维事件：创建、扩缩容、插件安装

aliyun cs describe-cluster-events --cluster-id <cid> --region <region> --task-id <tid> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} # 过滤到单个任务的事件

对于“此集群最近发生了什么？”/“上周升级为什么失败？”——`describe-cluster-tasks` 和 `describe-cluster-events` 是答案。它们是分页的（`--page-number` / `--page-size`）；用 `--pager` 自动跨页合并。

对于其中任何一个，附加 `--help` 查看完整参数集和结构。

更完整的工作流见 `./references/cs-scenarios.md`。

### 9. Kubeconfig 获取和 `kubectl` 交接

默认 kubeconfig（内网 endpoint，取决于集群网络）

aliyun cs describe-cluster-user-kubeconfig --cluster-id <cid> --region <region> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} \

export KUBECONFIG=~/.kube/config.ack

kubectl get nodes

注意事项：

- 某些集群只暴露内网 API server endpoint；你获取的 kubeconfig 只能在 VPC 内工作。两者都存在时，用 `--private-ip-address true|false` 在内网和公网 endpoint 之间选择。
- 基于临时 STS 的 kubeconfig 会过期——重新运行命令刷新。
- 自动化时，优先将 `KUBECONFIG` 设为一个每集群文件，而非覆盖 `~/.kube/config`。

### 10. 过滤和格式化输出

与 CLI 其余部分相同的模式：`--cli-query`（JMESPath）加 `--output`。在 ACK 中很有用，因为集群/节点池/插件列表响应是嵌套的：

仅运行中的集群 ID 和名称

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

该地域最近的操作计划（自动升级、AutoMode、CVE 修复）

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}"

仅节点池 ID 和当前规模

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. 分页——优先游标，用 `--pager` 自动合并

两种风格：**游标**（`--next-token` / `--max-results`，并发写入下稳定——首选）和**偏移**（`--page-number` / `--page-size`，扫描中途可能偏移）。检查 `--help` 看命令支持哪种——两者都列出时游标胜出。

CLI 的 `--pager` flag 自动合并任一风格的页面；几乎总是用户想要的。`--pager` 语法和手写游标循环示例见 [`./references/cs-scenarios.md`](./references/cs-scenarios.md) §9。

### 12. 调试——任何写操作前先 dry-run

ACK 写操作会开通真实云资源，许多不可逆。参数集非平凡时，**始终先用 `--cli-dry-run` 运行写命令**——它序列化确切负载并验证参数解析而不实际调用：

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

当 `cs` 命令确实失败时，`--log-level debug` 暴露完整请求/响应，让你看到 endpoint、body、状态和原始错误：

aliyun cs describe-cluster-detail --cluster-id <cid> --region <region> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} --log-level debug

具体错误模式和首要动作配方（插件/参数/格式/地域/认证/RAM/异步任务失败，外加示例 dry-run 输出），见 [`./references/error-catalogue.md`](./references/error-catalogue.md)。

响应格式指导

帮助用户使用 cs 命令时：

1. 先读意图。 他们是在调查（"describe / list"）、修改（"scale / upgrade / install"）还是创建？修改/创建流程几乎总是产生 task_id——尽早暴露该模式。
2. 展示完整命令，带必需参数并解释非显而易见的（--region、插件配置的 JSON 中嵌 JSON 等）。
3. 异步操作在同一响应中提及 describe-task-info——并在忙等前询问。
4. 用户排查时建议 --help 和 --log-level debug。
5. 引用集群地域——大多数“命令在 cn-hangzhou 能用但在 cn-shanghai 不能用”的问题都是缺少/错误的 --region。

参考

四个参考文件，都是 ACK 特有的。通用 CLI 知识（隐藏全局 flag 如 --waiter / --header / --body / --secure、多版本 API、完整安全最佳实践）是阿里云 CLI 自身的责任——需要时查阅其自己的文档。

1. ./references/cs-scenarios.md —— 日常最有用。 端到端示例：发现、kubeconfig、节点池、插件、集群升级、删除、create→wait→kubeconfig 流水线。
2. ./references/async-tasks.md —— task_id 生命周期、状态词汇、轮询策略、常见 error.code 原因、部分失败处理。
3. ./references/cli-plugin-installation-guide.md —— 阿里云 CLI 安装（macOS/Linux/Windows）、凭证模式摘要、cs 插件安装、端到端验证、故障排查。设置时读一次；遇到“我无法通过 Forbidden.RAM”类问题再回来。
4. ./references/ram-policies.md —— 本 Skill 的 aliyun cs 调用所需的 RAM Action 和策略模板（集群/节点池/插件/任务范围）。

脚本：

• ./scripts/check-cs-plugin.sh —— 验证 aliyun CLI ≥ 3.3.3 且 cs 插件已安装
• ./scripts/install-cs-plugin.sh —— 安装或更新 cs 插件（幂等；支持 --update 非交互式）
• ./scripts/wait-for-task.sh —— 轮询 describe-task-info 直到终态（需要 task ID + region）

文档 4 / 7：alibabacloud-flink-instance-manage