alibabacloud-ack-cli

ACK（コンテナサービス）CLI エキスパート

aliyun cs プラグインを使って、ターミナルから Alibaba Cloud Container Service for 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 文字の小文字 16 進数文字列）を生成してください。セッション全体で一度だけ生成し、以下の {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 '-'）を実行します。
• 小文字の 16 進数 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 に使用してください。テンプレートと生成ルールについては、上記のオブザーバビリティを参照してください。

エンドツーエンドの検証では、1 回の呼び出しで 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 ID に、コマンドで必要な cs の Action がありません。適用するポリシーについては、ACK の RAM ドキュメントを参照してください。クラスター一覧（または空の一覧）が表示されれば、準備完了です。

インストール手順の詳細（macOS／Linux／Windows、6 種類すべての認証情報モード、複数プロファイルの管理、トラブルシューティング）については、./references/cli-plugin-installation-guide.mdを参照してください。

2. 常に cs プラグインコマンド（ケバブケース）を使用し、従来の OpenAPI 形式は使用しないでください

このスキルが出力するプラグインコマンドは、常にケバブケースのみです。Aliyun CLI は従来の PascalCase 形式の OpenAPI コマンドも受け付けますが、ここでは使用禁止です。パラメーターの大文字・小文字の規則に一貫性がなく、--help の情報も少なく、ルーティングにも違いがあるため、興味本位であっても組み立てないでください。ユーザー提供のテキストに PascalCase の例が含まれていた場合は、実行する前にケバブケースのプラグイン形式に変換してください。

# ✅ 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 には多数のサブコマンドがあり、パラメーターの形式は分かりにくいものです。特にクラスターの作成、アドオンの設定、ノードプールのスケーリングでは注意が必要です。コマンドを組み立てる前に --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 エンベロープをすぐに返しますが、実際の処理（クラスターの作成、アップグレード、スケーリング、アドオンのインストール）はバックグラウンドで続行されます。成功したかどうかを確認するには、タスクをポーリングする必要があります。

タスクを返す操作：

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

タスク ID はリージョンごとに異なるため、クラスターのリージョンに合った --region を指定してください。デフォルトのエンドポイント経由で検索すると、遅延が増加します。

タスクの応答には state（running／success／failed）と、失敗時の error フィールドが含まれます。ポーリングを開始するときは、長時間の待機ループを始める前にユーザーに確認してください。ポーリングはトークンを消費するため、ユーザーは後で状況を確認したいかもしれません。妥当なデフォルトとして、30 秒ごとにポーリングし、適切な上限（例：クラスター作成では 30 分、アドオンのインストールでは 5 分）を設定してください。タスクが失敗した場合は、error.message を表示してください。

付属のヘルパー ./scripts/wait-for-task.sh <task-id> <region-id> は、間隔を空けながらポーリングし、最終状態を出力します。ユーザーに確認した後で使用してください。タスク ID はリージョンごとに異なるため、リージョンの指定は必須です。

詳細については、状態遷移、エラーフィールド、操作ごとの一般的な所要時間、部分的な失敗を示す応答の解釈方法を説明した ./references/async-tasks.md を参照してください。

5. 複雑な JSON パラメーター — Terway、AutoMode、アドオン

ACK のパラメーターには、フラットなフラグではうまく表現できないものがあります。例：

複数の AZ にまたがるポッド用 VSwitch を使った 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 のベストプラクティスプロファイル — 1 つのフラグで有効になります）：

--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 呼び出し — 2 つのルール

ACK はリージョン単位のモデルに移行しました。次の 2 つのルールが適用されます。

ルール 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 には有効期限があります。更新するには、コマンドを再実行してください。
• 自動化では、~/.kube/config を上書きするのではなく、クラスターごとのファイルを KUBECONFIG に設定することをおすすめします。

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 で自動マージ

方式は 2 種類あります。カーソル（--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 が指定されていないか、誤っていることが原因です。

参考資料

参考ファイルは 4 つあり、すべて ACK 固有の内容です。汎用的な CLI の知識（--waiter / --header / --body / --secure などの非表示のグローバルフラグ、マルチバージョン API、セキュリティのベストプラクティス全般）は Aliyun CLI の管轄です。必要に応じて、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 とリージョンが必要）