alibabacloud-ack-cli

ACK（容器服务）CLI 专家

使用 aliyun cs 插件，帮助用户在终端管理阿里云容器服务 Kubernetes 版（ACK）。通用 Aliyun CLI 规则（插件与 OpenAPI 风格的区别、--help 使用规范、结构化参数语法、输出筛选、调试）仍然适用。本技能重点介绍其上的 ACK 特定模式：异步任务、按地域划分的 API、JSON 中嵌套 JSON 字符串的结构、避免使用已弃用 API，以及少数高价值工作流（创建／扩缩容／组件／kubeconfig／升级）。

版本说明。 以下具体的 API／参数列表是基于 aliyun-cli 3.3.2 + cs 插件 0.2.1 收集的。如果你的插件版本较新，请重新运行本技能中嵌入的自发现命令以刷新信息：

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 命令都必须遵守）

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

规则：每条调用云 API 的 aliyun cs 命令都必须带上 --user-agent 标志，格式必须如下：

--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>。
• 本技能中的示例都使用字面占位符 {session-id}——运行前请替换为生成的值，绝不能运行仍带有占位符的命令。

适用范围：仅限云 API（业务）命令。CLI 系统／工具命令（aliyun version、aliyun plugin ...、aliyun configure ...）以及任何 --help 调用都不得带此标志——这些命令不支持该标志。

说明

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

在终端使用 ACK 需要安装 aliyun CLI（≥ 3.3.3）和 cs 插件。快速安装：

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)

提醒。 在第一条业务命令之前，生成会话 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 种凭证模式、多配置文件管理、故障排除），请参阅 ./references/cli-plugin-installation-guide.md。

2. 始终使用 cs 插件命令（kebab-case）——切勿使用旧版 OpenAPI 风格

此技能只会生成 kebab-case 插件命令。Aliyun CLI 也接受旧版 PascalCase OpenAPI 格式，但此处禁止使用：参数大小写不一致、--help 信息较少，而且路由方式不同，因此切勿自行编写此类命令——即使只是出于好奇也不行。如果用户提供的文本中出现 PascalCase 示例，请先将其转换为 kebab-case 插件格式，再运行。

# ✅ 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}

该插件提供一致的 --kebab-case 参数、包含字段类型的结构化帮助信息，以及自动 JSON 展开功能——这些正是你在输入任何内容前需要了解的信息。始终使用插件命令。

3. 编写任何 cs 命令前先运行 --help

ACK 有许多子命令，参数结构并不直观——尤其是创建集群、配置 addon 和扩缩节点池。编写命令前先运行 --help，远比猜测后遇到参数验证错误省事。

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

插件帮助信息会告诉你参数是基本类型、列表、可重复的键值参数，还是复杂的 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 用户意外的一点。许多 ACK 操作都是异步的：cs 命令会快速返回一个包含 task_id 的 JSON 封装，但实际工作（创建集群、升级、扩缩容、安装 addon）会在后台继续进行。你必须轮询任务，才能知道操作是否成功。

会返回任务的操作：

• 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 中止卡住的 addon 安装、失控的节点池扩容或任何其他正在执行的任务。

典型响应：

{
  "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 按区域划分，通过默认端点查询会增加延迟。

任务响应包含 state（running / success / failed），失败时还会包含 error 字段。轮询时，启动长时间忙等循环前请先询问用户——轮询会消耗 token，用户可能更愿意稍后再查看。合理的默认值是每隔 30s 轮询一次，并设置适当的上限（例如，创建集群为 30 分钟，安装 addon 为 5 分钟）；如果任务失败，则显示 error.message。

随附的辅助脚本 ./scripts/wait-for-task.sh <task-id> <region-id> 会采用退避策略进行轮询，并输出最终状态——征得用户确认后再使用。区域参数为必填项，因为任务 ID 按区域划分。

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

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

某些 ACK 参数无法简洁地表示为扁平标志。例如：

使用多可用区 Pod 交换机的 Terway（创建集群）：

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

注意：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 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 等）。这会直接路由到地域端点，避免经过默认端点。

--region（CLI 全局参数，用于端点路由）和 --biz-region-id（API 业务参数）取值相同，但用途不同。没有 --region-id 标志。请始终先运行 --help，确认命令需要哪一个参数。

# 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. 检测各命令的废弃参数

CLI 会在 --help 中使用中文字符串 【该参数已废弃】 标记废弃参数（没有对应的英文字符串——必须按原文匹配）。在编写任何命令前，运行本文件开头的代码片段（aliyun cs <cmd> --help | grep '废弃'），以显示废弃字段及建议的替代项（例如 请使用 next_version 参数替代）。请将该行原样引用给用户；切勿默默替换。

8. 常用高价值命令

示例假设已知集群所在地域（通过规则 A 查找或由用户提供），并按照 §6 规则 B 传入 --region。请将 <region> 替换为实际值。

# 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

对于“这个集群最近发生了什么？”/“为什么上周升级失败了？”，应使用 describe-cluster-tasks 和 describe-cluster-events。这两个命令的结果是分页的（--page-number / --page-size）；使用 --pager 自动合并所有分页结果。

对于以上任何命令，追加 --help 可查看完整的参数集和结构。

更完整的工作流请参阅 ./references/cs-scenarios.md。

9. 获取 Kubeconfig 并交接给 kubectl

# 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

说明：

• 有些集群只提供内网 API 服务器端点；获取的 Kubeconfig 只能在 VPC 内使用。如果内网和公网端点都存在，请使用 --private-ip-address true|false 在二者之间选择。
• 基于临时 STS 的 Kubeconfig 会过期——请重新运行命令以刷新。
• 对于自动化，建议将 KUBECONFIG 设置为每个集群单独的文件，而不是覆盖 ~/.kube/config。

10. 筛选和格式化输出

与 CLI 的其他部分采用相同模式：使用 --cli-query（JMESPath）和 --output。这对 ACK 很有用，因为集群、节点池和插件的列表响应都采用嵌套结构：

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

有两种方式：游标（--next-token / --max-results，在并发写入时保持稳定——优先使用）和偏移量（--page-number / --page-size，扫描过程中可能发生偏移）。查看 --help 了解命令支持哪种方式——如果两种都列出，优先使用游标。

CLI 的 --pager 标志可以自动合并两种方式的分页结果；这几乎总是用户想要的效果。--pager 语法和手动编写的游标循环示例，请参阅 ./references/cs-scenarios.md §9。

12. 调试——任何写入操作前先试运行

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 会显示完整的请求/响应，方便你查看端点、请求正文、状态和原始错误：

aliyun cs describe-cluster-detail --cluster-id <cid> --region <region> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-ack-cli/{session-id} --log-level debug

有关特定错误模式和首选处理方案（插件 / 参数 / 格式 / 区域 / 身份验证 / RAM / 异步任务失败，以及试运行输出示例），请参阅 ./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 知识（隐藏的全局标志，如 --waiter / --header / --body / --secure、多版本 API、完整的安全最佳实践）由 Aliyun CLI 负责——必要时请查阅其自身文档。

1. ./references/cs-scenarios.md — 日常最实用的资料。 端到端示例：发现资源、kubeconfig、节点池、插件、集群升级、删除，以及创建→等待→kubeconfig 的流程。
2. ./references/async-tasks.md — task_id 生命周期、状态术语、轮询策略、常见的 error.code 原因，以及部分失败的处理。
3. ./references/cli-plugin-installation-guide.md — Aliyun CLI 安装（macOS/Linux/Windows）、凭证模式摘要、cs 插件安装、端到端验证和故障排查。设置时阅读一次；遇到“无法解决 Forbidden.RAM”之类的问题时再查阅。
4. ./references/ram-policies.md — 此技能的 aliyun cs 调用所需的 RAM Actions 和策略模板（集群 / 节点池 / 插件 / 任务范围）。

脚本：

• ./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，直到任务进入终态（需要任务 ID + 区域）