Alicloud Ack Ops

Alibaba Cloud ACK Operations Skill

Overview

Alibaba Cloud Container Service for Kubernetes (ACK) provides managed Kubernetes clusters with automated operations, multi-AZ availability, and deep integration with Alibaba Cloud infrastructure (SLB, NAS, OSS, RAM, VPC). This skill is an operational runbook for agents: explicit scope, credential rules, pre-flight checks, dual-path execution (official aliyun CLI primary, JIT Go SDK fallback), response validation, and failure recovery.

Execution surface — CLI-primary with JIT Go SDK fallback:

• Primary: aliyun cs — static Go binary, covers cluster CRUD,

node pool operations, and scaling.

• Fallback: JIT Go SDK (github.com/alibabacloud-go/cs-20151215/v4/client)

for APIs not exposed in CLI (e.g., some addon management, advanced network policies, or new API versions).

• Console click-paths are not an agent execution surface in SKILL.md.

Core resources managed by this skill (ManagedKubernetes / Kubernetes only):

• Cluster — the Kubernetes control plane and managed infrastructure.
• Node Pool — homogeneous groups of worker nodes with shared configuration.
• Addon — cluster components (e.g., ingress, metrics-server, logtail).

> Out of scope: ASK (Serverless Kubernetes, cluster_type=Ask) has no > nodes, no node pools, no node-level scaling — see > [alicloud-ask-ops](../alicloud-ask-ops/SKILL.md).

Runtime Rules

| Area | Rule | Reference | | --- | --- | --- | | CLI path | MANDATORY: Always prefer the SkillOpt wrapper ./scripts/ack-skillopt-wrapper.sh for all ACK CLI operations to enable automated self-repair and dynamic optimization; fallback to native aliyun cs only when the wrapper is unavailable or skillopt-lib.sh is missing. For runtime enforcement, source the shared shim: source ../../alicloud-skill-generator/scripts/skillopt-shim/aliyun-shim.sh. | [CLI](references/cli-usage.md), [SkillOpt](references/skillopt-integration.md), [Shim](file://../../alicloud-skill-generator/scripts/skillopt-shim/SHIM-README.md) | | Credentials | Read {{env.*}} only from environment; never ask user to paste or print secrets | [Integration](references/integration.md) | | GCL | All write operations MUST pass GCL adversarial review before execution | [GCL Rubric](references/rubric.md) |

Trigger & Scope (Agent-Readable)

SHOULD Use This Skill When

• User mentions "ACK", "Alibaba Cloud Kubernetes", "容器服务", "容器服务

Kubernetes版", "K8s", or "Kubernetes cluster on Alibaba Cloud"

• Task involves CRUD or lifecycle operations on Cluster or Node Pool

(create, describe, modify, delete, list, scale, upgrade)

• Task keywords: cluster, node pool, worker node, managed kubernetes,

pro kubernetes, addon, ingress, scaling, upgrade, kubeconfig — NOT triggered by Serverless / ASK / cluster_type=Ask / 按 Pod 弹性 / 无服务器 K8s / ECI Pod; those belong to alicloud-ask-ops

• User asks to deploy, configure, troubleshoot, or monitor ACK **via API, SDK,

CLI, or automation**

• 集群巡检场景: "检查K8s集群", "巡检ACK", "集群健康检查", "查看命名空间/Pod/Service",

"kubectl无法连接", "集群访问不了", "没有权限访问集群", "403 Forbidden" — 触发后先执行 [前置检查](references/inspection-access-patterns.md)确定访问方式，再选择标准巡检或降级方案

SHOULD NOT Use This Skill When

• Task is purely billing / account management → delegate to:

alicloud-billing-ops (when present)

• Task is RAM / permission model only → delegate to: alicloud-ram-ops (when

present)

• Task is about VPC / SLB / NAS / OSS underlying resources but not ACK

cluster lifecycle → delegate to: alicloud-vpc-ops, alicloud-slb-ops, etc.

• Task is about ECI / Serverless outside ACK context → delegate to:

[alicloud-eci-ops](../alicloud-eci-ops/SKILL.md)

• Cluster is Serverless Kubernetes (ASK, cluster_type=Ask) → delegate to:

[alicloud-ask-ops](../alicloud-ask-ops/SKILL.md)

• User insists on console-only flows with no API → state limitation; do not

invent undocumented HTTP steps

Delegation Rules

| 能力 | 委托目标 | 说明 | |------|----------|------| | GCL 质量门禁 | alicloud-gcl-runner-ops | 对写操作执行前，委托 GCL 循环进行对抗性评审 |

Variable Convention (Agent-Readable)

| Placeholder | Meaning | Agent Action | |-------------|---------|--------------| | {{env.ALIBABA_CLOUD_ACCESS_KEY_ID}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_REGION_ID}} | From runtime environment | Use documented default only if skill explicitly allows | | {{user.region}} | User-supplied region | Ask once; reuse | | {{user.cluster_name}} | User-supplied cluster name | Ask once; reuse | | {{user.cluster_id}} | User-supplied or output cluster ID | Ask if not from previous output | | {{user.vpc_id}} | VPC for cluster creation | Ask; validate via VPC skill if needed | | {{user.vswitch_ids}} | VSwitches for cluster nodes | Ask; comma-separated list | | {{output.cluster_id}} | From last CreateCluster response | Parse cluster_id from response | | {{output.node_pool_id}} | From last CreateNodePool response | Parse nodepool_id from response | | {{user.node_pool_id}} | User-supplied or output node pool ID | Ask if not from previous output | | {{user.key_pair}} | ECS Key Pair for SSH access to nodes | Ask once; optional for password auth |

> {{env.*}} MUST NOT be collected from the user. {{user.*}} MUST be > collected interactively when missing.

> 凭据安全（强制）： 参考 [Credential Masking 规则](../alicloud-skill-generator/references/credential-masking.md)

API and Response Conventions (Agent-Readable)

• OpenAPI is canonical for path, query, body fields, enums, and response

shapes. ACK uses the CS-2015-12-15 API version.

• Errors: Map SDK/HTTP errors to code / status / message fields per spec.

Common ACK errors: ErrorClusterNotFound, ErrorClusterState, ErrorCheckAcl, QuotaExceeded.Cluster.

• Timestamps: ISO 8601 with timezone when the API returns strings.
• Idempotency: client_token can be used for CreateCluster; document

duplicate name behavior per API.

Response Field Table (ACK-Specific)

| Operation | JSON Path (CLI/SDK) | Type | Description | |-----------|---------------------|------|-------------| | CreateCluster | $.cluster_id | string | New cluster ID | | DescribeClusters | $.clusters[].cluster_id | array | Cluster IDs list | | DescribeClusterDetail | $.state | string | Cluster lifecycle state | | DescribeClusterNodes | $.nodes[].instance_id | array | Node ECS instance IDs | | CreateNodePool | $.nodepool_id | string | New node pool ID | | ScaleOutCluster | $.task_id | string | Async scaling task ID |

Expected State Transitions (ACK Cluster)

| Operation | Initial State | Target State | Poll Interval | Max Wait | |-----------|---------------|--------------|---------------|----------| | CreateCluster | — | running | 30s | 1800s (30min) | | UpgradeCluster | running | running | 30s | 3600s (60min) | | ScaleOutCluster | running | running | 30s | 1800s (30min) | | DeleteCluster | any stable state | absent / 404 | 30s | 1800s (30min) |

> Note: ACK cluster operations are long-running. Always poll state via > DescribeClusters or DescribeClusterDetail until terminal state.

Changelog

| Version | Date | Changes | |---------|------|---------| | 2.1.1 | 2026-06-11 | 新增巡检前置检查机制: ① 添加 inspection-access-patterns.md 文档 ② 更新 intelligent-inspection.md 增加前置检查脚本 ③ SKILL.md 增加巡检触发规则和前置检查操作章节 | | 1.0.0 | 2026-05-14 | Initial ACK skill with cluster and node pool operations |

> EXECUTION MANDATORY RULE: 所有 control-plane CLI 执行步骤 必须 通过 SkillOpt wrapper ./scripts/ack-skillopt-wrapper.sh 运行。 > 以下所有代码块中的 aliyun cs ... 命令在执行时应替换为 ./scripts/ack-skillopt-wrapper.sh ...。 > 仅在 wrapper 脚本不可用或 skillopt-lib.sh 缺失时，才退回到原生 aliyun cs CLI 调用。 > 参考 ## Runtime Rules 中的 CLI path 规则。

Execution Flows (Agent-Readable)

Every operation: Pre-flight → Execute (CLI primary / SDK fallback) → Validate → Recover. Do not skip phases.

Operation: Create Cluster

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | CLI / deps | aliyun version | Exit code 0 | Document CLI install | | Credentials | Env vars or CLI config | Non-empty keys | HALT; user configures env | | Region | aliyun cs DescribeClusters --RegionId {{user.region}} (dry list) | HTTP 200 | Suggest valid region | | VPC / VSwitch | Validate {{user.vpc_id}} and {{user.vswitch_ids}} exist | Found | Delegate to VPC skill or ask | | Quota | aliyun cs DescribeClusters list length vs known quota | Sufficient | HALT; user raises quota |

Execution — CLI (aliyun cs) (Primary Path)

# Create a managed Kubernetes cluster (minimal example)
aliyun cs POST /clusters \
  --body "{
    \"cluster_type\": \"ManagedKubernetes\",
    \"name\": \"{{user.cluster_name}}\",
    \"region_id\": \"{{user.region}}\",
    \"vpc_id\": \"{{user.vpc_id}}\",
    \"vswitch_ids\": [{{user.vswitch_ids}}],
    \"worker_instance_types\": [\"ecs.g7.xlarge\"],
    \"num_of_nodes\": 2,
    \"key_pair\": \"{{user.key_pair}}\",
    \"service_cidr\": \"172.16.0.0/16\",
    \"pod_cidr\": \"10.0.0.0/8\"
  }"

> Note: ACK CreateCluster uses a POST /clusters REST-style API. The > aliyun CLI supports this via POST /clusters or aliyun cs CreateCluster > depending on CLI version. Verify with aliyun help cs before execution.

> Required fields (verify in OpenAPI): cluster_type, name, region_id, > vpc_id, vswitch_ids, worker_instance_types, num_of_nodes.

> Network plugin: Default is Flannel (pod_cidr required). For Terway > (ENI-based), omit pod_cidr and pass addons with [{"name":"terway-eniip"}]. > See [Core Concepts](references/core-concepts.md) for CNI differences.

> Idempotency: Pass client_token (unique string per request) in the request > body to prevent duplicate cluster creation on retry.

> JSON body from file: For complex requests, write body to a file and use: > aliyun cs POST /clusters --body file:///tmp/cluster.json

Execution — JIT Go SDK (Fallback Path)

When CLI does not support a specific cluster parameter or new API version:

JIT Go SDK fallback: 参见 [API & SDK Usage](references/api-sdk-usage.md)

Post-execution Validation

1. Extract {{output.cluster_id}} from response ($.cluster_id).
2. Poll until state == "running":

# 通用轮询，参数见 [references/polling-patterns.md](references/polling-patterns.md)（CreateCluster → running, 60×30s）

1. On success, report cluster_id, state, and api_server_endpoint.
2. On terminal failure (failed, deleting, timeout), go to Failure Recovery.

Failure Recovery

| Error pattern | Max retries | Backoff | Agent Action | |---------------|-------------|---------|--------------| | InvalidParameter / 400 | 0–1 | — | Fix args from OpenAPI; retry once if safe | | QuotaExceeded.Cluster | 0 | — | HALT; user raises quota | | InsufficientBalance | 0 | — | HALT | | ErrorCheckAcl / RAM | 0 | — | Delegate to RAM skill or user fixes policy | | Throttling / 429 | 3 | exponential | Back off; respect Retry-After | | InternalError / 5xx | 3 | 10s, 20s, 40s | Retry; then HALT with RequestId |

Operation: Describe Cluster

Execution — CLI

# Describe single cluster
aliyun cs GET /clusters/{{user.cluster_id}}

# List all clusters in region
aliyun cs GET /clusters --RegionId {{user.region}}

Present to User

| Field | Path | Notes | |-------|------|-------| | Cluster ID | $.cluster_id | Plain text | | Name | $.name | Plain text | | State | $.state | e.g., running, initial, failed, deleting | | Region | $.region_id | Plain text | | Kubernetes Version | $.current_version | e.g., 1.28.3-aliyun.1 | | API Server Endpoint | $.api_server.endpoint | Public or internal endpoint | | VPC ID | $.vpc_id | Plain text | | Created At | $.created | ISO 8601 |

Operation: Scale Out Cluster (Add Nodes)

Pre-flight

• Confirm cluster state == "running".
• Validate {{user.vswitch_ids}} and instance types.

Execution — CLI

# Method A: REST-style path (verify with `aliyun help cs`)
aliyun cs POST /clusters/{{user.cluster_id}}/nodes \
  --body "{
    \"count\": {{user.node_count}},
    \"vswitch_ids\": [{{user.vswitch_ids}}],
    \"instance_types\": [\"{{user.instance_type}}\"],
    \"key_pair\": \"{{user.key_pair}}\"
  }"

# Method B: RPC-style operation (if supported by CLI version)
# aliyun cs ScaleOutCluster \
#   --ClusterId {{user.cluster_id}} \
#   --Count {{user.node_count}} \
#   --VswitchIds {{user.vswitch_ids}}

Validation

Poll DescribeClusterNodes until new nodes reach Ready state (or ECS Running and Kubernetes node Ready via kubectl if kubeconfig available).

Operation: Create Node Pool

Execution — CLI

> Field structure varies by API version. Verify exact field names via > aliyun help cs CreateNodePool or OpenAPI spec before execution.

aliyun cs POST /clusters/{{user.cluster_id}}/nodepools \
  --body "{
    \"name\": \"{{user.node_pool_name}}\",
    \"node_config\": {
      \"instance_types\": [\"ecs.g7.xlarge\"],
      \"vswitch_ids\": [{{user.vswitch_ids}}],
      \"key_pair\": \"{{user.key_pair}}\"
    },
    \"scaling_group\": {
      \"desired_size\": {{user.desired_size}},
      \"min_size\": {{user.min_size}},
      \"max_size\": {{user.max_size}}
    }
  }"

Validation

Extract {{output.node_pool_id}} from $.nodepool_id. Poll GET /clusters/{{user.cluster_id}}/nodepools/{{output.node_pool_id}} until status.state == "active" (or equivalent field per API version).

Operation: Upgrade Cluster

Pre-flight (Safety Gate)

• MUST obtain explicit user confirmation: upgrading Kubernetes version is

disruptive to running workloads (control plane brief unavailability, node rolling restart).

• Confirm current version vs target version via DescribeClusters.

Execution — CLI

aliyun cs PUT /clusters/{{user.cluster_id}}/upgrade \
  --body "{
    \"version\": \"{{user.target_version}}\",
    \"upgrade_mode\": \"standard\"
  }"

Validation

Poll GET /clusters/{{user.cluster_id}} until state == "running" and current_version == {{user.target_version}}. Max wait: 3600s.

Operation: Get kubeconfig

Execution — CLI

# Public endpoint kubeconfig
aliyun cs GET /k8s/{{user.cluster_id}}/user_config

# Internal endpoint kubeconfig (VPC-only access)
aliyun cs GET /k8s/{{user.cluster_id}}/user_config \
  --PrivateIpAddress true

Present to User

Save output to ~/.kube/config or custom path:

aliyun cs GET /k8s/{{user.cluster_id}}/user_config > ~/.kube/ack-{{user.cluster_id}}
export KUBECONFIG=~/.kube/ack-{{user.cluster_id}}
kubectl get nodes

---

Operation: Modify Node Pool

Pre-flight

• Confirm cluster state == "running".
• Confirm node pool exists: GET /clusters/{id}/nodepools/{pool_id}.

Execution — CLI

> Note: Modify operations may use PUT or POST depending on API version. > Verify with aliyun help cs.

# Scale node pool (adjust desired size)
aliyun cs PUT /clusters/{{user.cluster_id}}/nodepools/{{user.node_pool_id}} \
  --body "{
    \"scaling_group\": {
      \"desired_size\": {{user.desired_size}}
    }
  }"

# Enable auto-scaling (if supported)
# aliyun cs PUT /clusters/{id}/nodepools/{pool_id} \
#   --body "{\"auto_scaling\": {\"enable\": true, \"min_size\": 1, \"max_size\": 10}}"

Validation

Poll GET /clusters/{id}/nodepools/{pool_id} until node count matches desired size and status.state == "active".

---

Operation: Delete Node Pool

Pre-flight (Safety Gate)

• MUST obtain explicit confirmation: irreversible delet

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buhaiqing
• Source: buhaiqing/aliyun-skills
• License: MIT

Install and usage instructions live in the source repository linked above.