# Alicloud Ack Ops

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-buhaiqing-aliyun-skills-alicloud-ack-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [buhaiqing](https://agentstack.voostack.com/s/buhaiqing)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** https://github.com/buhaiqing/aliyun-skills/tree/main/alicloud-ack-ops

## Install

```sh
agentstack add skill-buhaiqing-aliyun-skills-alicloud-ack-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

```bash
# 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"`:

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

3. On success, report `cluster_id`, `state`, and `api_server_endpoint`.
4. 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

```bash
# 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

```bash
# 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.

```bash
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

```bash
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

```bash
# 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:

```bash
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`.

```bash
# 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](https://github.com/buhaiqing)
- **Source:** [buhaiqing/aliyun-skills](https://github.com/buhaiqing/aliyun-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-buhaiqing-aliyun-skills-alicloud-ack-ops
- Seller: https://agentstack.voostack.com/s/buhaiqing
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.