# Alicloud Eci Ops

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-buhaiqing-aliyun-skills-alicloud-eci-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-eci-ops

## Install

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

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

## About

# Alibaba Cloud ECI (Elastic Container Instance) Operations Skill

## ✅ OpenAPI 验证状态 (VERIFIED 2026-06-02)

> **Status: 已通过** `https://api.aliyun.com/meta/v1/products/ECI/versions/2018-08-08/api-docs.json`
> + `aliyun eci  --help` + `aliyun help eci` 验证。
> 详见 [`references/openapi-verify-checklist.md`](references/openapi-verify-checklist.md)
> 和 [`references/api-sdk-usage.md`](references/api-sdk-usage.md)。
>
> **重大修正（修正训练知识错误）：**
> - ⚠️ **配额命令是 `ListUsage`**，不是 `DescribeContainerGroupQuota`（后者不存在）
> - **CPU pinning** 字段是 `CpuOptionsCore` + `CpuOptionsThreadsPerCore`（不是 `CpuOptions`）
> - **`ImageRegistryCredential`** 形状是 `{Server, UserName, Password}`（注意 `UserName` 不是 `Username`）
> - **`ExecContainerCommand`** 的 `--Command` 必须是 **JSON 数组**（不是字符串）
> - **`RestartPolicy` 默认是 `Always`**，**永远要确认**（误用 = 无限计费）
> - **支持 `InstanceType`**：可指定 ECS 规格（如 `ecs.c5.xlarge`）
> - **支持 `InitContainer`**（init 容器数组，K8s 风格）
> - **支持 Spot**（`SpotStrategy` / `SpotPriceLimit` / `SpotDuration` / `StrictSpot`）
> - **支持 EIP**（`EipInstanceId` / `AutoCreateEip` / `EipBandwidth` / `EipISP`）
> - **支持 IPv6**（`Ipv6AddressCount` / `Ipv6GatewayBandwidth`）
> - **支持镜像缓存**（`ImageSnapshotId` / `CreateImageCache` / `AutoMatchImageCache`）
> - **支持数据缓存**（`DataCacheBucket` / `DataCachePL` 等）
> - **Volume 类型完整**：`EmptyDirVolume` / `NFSVolume` / `ConfigFileVolume` / `FlexVolume` / `HostPathVolume`（白名单）/ `DiskVolume`（不推荐）
> - **Probes / Lifecycle hooks 完整支持**（HttpGet / TcpSocket / Exec / postStart / preStop）

---

## Overview

Alibaba Cloud **Elastic Container Instance (ECI)** is a **Serverless container
runtime**: each ECI (a.k.a. **ContainerGroup**) is a pod-equivalent unit that
runs in your VPC, billed per-second by vCPU + memory (and optional GPU), with
**no node to manage**.

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 eci ` — static Go binary, covers
  ContainerGroup CRUD, exec, quota, image cache, data cache, virtual node.
- **Fallback:** JIT Go SDK
  (`github.com/alibabacloud-go/eci-20180808/client`)
  for advanced fields and any field not covered by the CLI.
- **Console click-paths** are not an agent execution surface in `SKILL.md`.

**Core resources managed by this skill:**
- **ContainerGroup** — the ECI unit (≡ K8s Pod). Identified by
  `ContainerGroupId`. Can contain 1..N containers sharing
  network/volume/lifecycle.
- **Container** — individual container inside a ContainerGroup.
- **ImageCache** — pre-pulled image data to accelerate ECI startup.
- **DataCache** — pre-staged data (model files, datasets) to accelerate ECI.
- **VirtualNode** — bridges non-ASK K8s clusters to ECI via virtual-kubelet.

**When to use this skill vs `alicloud-ask-ops`:**

| Need | Use |
|------|-----|
| Run a one-off batch job / short-lived container | `alicloud-eci-ops` (this) |
| Manage a K8s cluster of type `cluster_type=ManagedKubernetes` + `profile=Serverless` (ASK) | `alicloud-ask-ops` |
| Schedule long-lived workloads with HPA/CronHPA via K8s API | `alicloud-ask-ops` |
| Direct ECI management without K8s | `alicloud-eci-ops` (this) |
| Create a VirtualNode to bridge a self-managed K8s cluster to ECI | `alicloud-eci-ops` (this) |
| Create ImageCache / DataCache to accelerate cold start | `alicloud-eci-ops` (this) |

> **Relationship to ASK:** ASK's internal Pods **are** ECI ContainerGroups.
> This skill manages them directly; `alicloud-ask-ops` manages
> them through the K8s API. Don't run both on the same workload.

## Trigger & Scope (Agent-Readable)

### SHOULD Use This Skill When

- User mentions "ECI", "弹性容器实例", "ContainerGroup", "按 vCPU 秒计费容器",
  "跑个一次性任务", "在阿里云上跑个容器 Job"
- Task is ContainerGroup lifecycle: create, describe, list, update, delete,
  exec into
- Task is ECI quota pre-flight or quota change request
- User wants to run a **batch / CI / Spark / short-lived** workload on
  Alibaba Cloud **without** managing a K8s cluster
- User asks to attach GPU to a container on demand
- User asks for direct ECI exec (e.g. `docker exec`-like)
- User wants to create ImageCache or DataCache
- User wants to create a VirtualNode for their self-managed K8s cluster

### SHOULD NOT Use This Skill When

- Cluster is K8s-based (`cluster_type=ManagedKubernetes` + `profile=Serverless` for ASK, or `ManagedKubernetes` alone for managed) → delegate to
  [`alicloud-ask-ops`](../alicloud-ask-ops/SKILL.md)
  or [`alicloud-ack-ops`](../alicloud-ack-ops/SKILL.md)
- Task is about **bare ECS instances** → delegate to `alicloud-ecs-ops`
- Task is **container image build / registry** (ACR) → delegate to
  `alicloud-acr-ops` (when present)
- Task is **VPC / VSwitch / SecurityGroup** creation only →
  `alicloud-vpc-ops`
- Task is **K8s-level workload management on ASK** (Deployment, Service,
  HPA) → `alicloud-ask-ops` (kubectl through kubeconfig)
- Task is purely billing / account management → `alicloud-billing-ops`
- Task is RAM / permission model only → `alicloud-ram-ops`
- 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.container_group_name}}` | User-supplied ContainerGroup name | Ask once; reuse |
| `{{user.container_group_id}}` | User-supplied or output ID | Ask if not from previous output |
| `{{user.image}}` | Container image (e.g. `nginx:1.25` or ACR URL) | Ask once |
| `{{user.vswitch_id}}` | VSwitch for ECI ENI | Ask; validate via VPC skill |
| `{{user.security_group_id}}` | SecurityGroup for ECI ENI | Ask; validate via VPC/ECS skill |
| `{{user.cpu}}` / `{{user.memory}}` | ECI spec | Ask; respect ECI min/max |
| `{{output.container_group_id}}` | From last CreateContainerGroup response | Parse from response |
| `{{output.container_group_ip}}` | ECI ENI IP | Parse from response |

> **`{{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, response
  shapes. ECI uses **`ECI-2018-08-08`** API version (verified).
- **Errors:** Map SDK/HTTP errors to `code` / `status` / message fields per
  spec. Common ECI errors: `QuotaExceeded`, `InvalidParameter.CPU.Memory`,
  `InvalidParameter.DuplicatedName`, `InvalidParameter.DuplicatedVolumeName`,
  `ImageSnapshot.NotFound`, `InvalidVSwitchId.IpNotEnough`,
  `OperationDenied.SecurityGroupMisMatch`, `OperationDenied.VswZoneMisMatch`.
- **Timestamps:** ISO 8601 with timezone when the API returns strings.
- **Idempotency:** `ClientToken` can be used for CreateContainerGroup (≤64 ASCII).

### Response Field Table (ECI-Specific)

| Operation | JSON Path | Type | Description |
|-----------|-----------|------|-------------|
| CreateContainerGroup | `$.ContainerGroupId` | string | New ECI ID |
| CreateContainerGroup | `$.RequestId` | string | Request ID |
| DescribeContainerGroups | `$.ContainerGroups[].ContainerGroupId` | array | ECI IDs |
| DescribeContainerGroups | `$.ContainerGroups[].Status` | enum | ECI lifecycle state |
| DescribeContainerGroup | `$.Status` | string | ECI state |
| DescribeContainerGroup | `$.Containers[].Name` | string | Container names |
| DescribeContainerGroup | `$.Containers[].Image` | string | Container image |
| DescribeContainerGroup | `$.IntranetIp` | string | ECI ENI private IP |
| DescribeContainerGroup | `$.RegionId` / `$.VpcId` / `$.VSwitchId` | string | Network binding |
| ListUsage | (verify per region) | varies | Quota usage (CPU, memory, instance count) |

### Expected State Transitions (ContainerGroup)

| Operation | Initial | Target | Poll Interval | Max Wait |
|-----------|---------|--------|---------------|----------|
| CreateContainerGroup | — | `Running` / `Succeeded` / `Failed` | 5s | 300s |
| DeleteContainerGroup | any | absent / 404 | 5s | 120s |
| UpdateContainerGroup | `Running` | `Running` | 5s | 120s |
| RestartContainerGroup | any | `Running` | 5s | 120s |

### Polling Strategy

> **Note:** `aliyun eci` does **not** support `--waiter` subcommands. All polling must use manual shell loops with `DescribeContainerGroup(s)` and `sleep`. See full templates and per-operation parameters at [`references/polling-patterns.md`](references/polling-patterns.md).

### ContainerGroup Status Reference

| Status | Meaning | Actionable? |
|--------|---------|--------------|
| `Pending` | Provisioning ENI / pulling image | Wait; investigate if > 60s |
| `Scheduling` | Awaiting ECI quota / VSwitch IP | Check quota; raise if needed |
| `Running` | At least 1 container running | Yes — can Exec |
| `Succeeded` | All containers exited 0 (RestartPolicy=Never/OnFailure) | Yes — can delete |
| `Failed` | At least 1 container exited non-zero | Yes — read logs; consider recreate |
| `SchedulingFailed` | Quota exhausted, cannot schedule | Raise quota; retry |

## Quick Start

### What This Skill Does
This skill creates, describes, updates, deletes, and execs into Alibaba Cloud
Elastic Container Instances (ECI) via `aliyun eci ...` (primary) or JIT Go SDK
(fallback). It also handles ECI quota pre-flight checks via `ListUsage`.

### Prerequisites
- [ ] `aliyun` CLI installed (or Go runtime for JIT fallback)
- [ ] Credentials configured: `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- [ ] Region set: `ALIBABA_CLOUD_REGION_ID`
- [ ] VPC + VSwitch + SecurityGroup exist in the target region
- [ ] **⚠️** Run the [OpenAPI verify status](#✅-openapi-验证状态-verified-2026-06-02)
      at the top of this file before first CreateContainerGroup

### Verify Setup
```bash
aliyun version
test -n "$ALIBABA_CLOUD_ACCESS_KEY_ID" && echo "✅ AK set"
test -n "$ALIBABA_CLOUD_ACCESS_KEY_SECRET" && echo "✅ SK set (length only)"
aliyun eci ListUsage --body '{"RegionId":"'"$ALIBABA_CLOUD_REGION_ID"'"}' 2>&1 | head -30
```

### Your First Command
```bash
# Check ECI quota in region
aliyun eci ListUsage --body '{"RegionId":"'"$ALIBABA_CLOUD_REGION_ID"'"}'

# List current ContainerGroups
aliyun eci DescribeContainerGroups --RegionId $ALIBABA_CLOUD_REGION_ID \
  --output cols=ContainerGroupId,Status,Name \
  rows=ContainerGroups[].{ContainerGroupId:ContainerGroupId,Status:Status,Name:Name}
```

## Capabilities at a Glance

| Operation | Description | Complexity | Risk Level |
|-----------|-------------|------------|------------|
| CreateContainerGroup | Create a new ECI (one or more containers) | Medium | Low (transient) |
| DescribeContainerGroup(s) | List / inspect ECIs | Low | None |
| UpdateContainerGroup | Update image / spec | Medium | Medium |
| ExecContainerCommand | Run a command inside a container | Low | Low |
| DeleteContainerGroup | Remove ECI (irreversible, kills workloads) | Low | **High** |
| RestartContainerGroup | Restart a ContainerGroup | Low | Medium |
| **ListUsage** | **Region-level quota usage (verified command)** | Low | None |
| DescribeContainerGroupPrice | ECI price query | Low | None |
| DescribeAvailableResource | ECS instance families available per region/zone | Low | None |
| CreateImageCache | Pre-pull images for fast startup | Medium | Low |
| CreateDataCache | Pre-stage data (models, datasets) | Medium | Low |
| CreateVirtualNode | Bridge self-managed K8s cluster to ECI | High | Medium |

## Runtime Rules
**MANDATORY: Always prefer the SkillOpt wrapper for all CLI operations.**

| Rule | Requirement |
|------|-------------|
| **CLI Path** | `./scripts/eci-skillopt-wrapper.sh eci  [params]` |
| **Fallback** | Use native `aliyun eci  [params]` **only** when the wrapper script is missing or cannot be sourced |
| **SkillOpt Enabled** | Set `SKILLOPT_ENABLED=true` to enable automated self-repair, retries, and Langfuse tracing |
| **Session ID** | Pass `--skillopt-session-id ` to enable multi-skill trace correlation |

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2026-06-02 | Initial ECI skill. Covers ContainerGroup lifecycle, exec, quota, image cache, data cache, virtual node. |
| 1.1.0 | 2026-06-02 | **Major corrections after OpenAPI verification**: quota command is `ListUsage` (not `DescribeContainerGroupQuota`); `CpuOptions` is actually `CpuOptionsCore`+`CpuOptionsThreadsPerCore`; `ImageRegistryCredential` is `{Server,UserName,Password}`; `ExecContainerCommand` takes JSON array; added ImageCache/DataCache/VirtualNode/Spot/EIP/IPv6 sections. |

---

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

## Execution Flows (Agent-Readable)

> **⚠️ MANDATORY NOTE**: All CLI examples in this document MUST be executed via the SkillOpt wrapper script (`./scripts/eci-skillopt-wrapper.sh`). Fallback to native `aliyun eci` commands is permitted **only** when the wrapper script is missing or cannot be sourced.

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

### Operation: CreateContainerGroup

#### 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 eci DescribeContainerGroups --RegionId {{user.region}}` | HTTP 200 | Suggest valid region |
| **ECI quota** | `aliyun eci ListUsage --body '{"RegionId":"{{user.region}}"}'` | Quota not exhausted | HALT; user raises quota in ECI console |
| VPC / VSwitch | Validate `{{user.vswitch_id}}` exists | Found | Delegate to VPC skill or ask |
| SecurityGroup | Validate `{{user.security_group_id}}` exists | Found | Delegate to VPC/ECS skill or ask |
| Image | If private registry, ensure `ImageRegistryCredential` ready | Set in request | Delegate to ACR or ask |
| **VSwitch free IPs** | `aliyun vpc DescribeVSwitches --VSwitchId {{user.vswitch_id}}` → check `AvailableIpAddress` | ≥ requested count | Expand VSwitch CIDR or pick another |

#### Execution — CLI (`aliyun eci`) (Primary Path)

> **CLI supports two styles**:
> 1. `--Container.N.*` array parameters (for simple cases)
> 2. `--body '{...}'` for complex requests

**Style 1: Simple array params (single container, no image cache)**
```bash
aliyun eci CreateContainerGroup \
  --RegionId "{{user.region}}" \
  --ContainerGroupName "{{user.container_group_name}}" \
  --Container.1.Name "app" \
  --Container.1.Image "{{user.image}}" \
  --Container.1.Cpu "1" \
  --Container.1.Memory "2" \
  --Cpu "{{user.cpu}}" \
  --Memory "{{user.memory}}" \
  --VSwitchId "{{user.vswitch_id}}" \
  --SecurityGroupId "{{user.security_group_id}}" \
  --RestartPolicy "Never"
```

**Style 2: JSON body (complex, multi-container, with private registry)**
```bash
aliyun eci CreateContainerGroup --body '{
  "RegionId": "{{user.region}}",
  "ContainerGroupName": "{{user.container_group_

…

## 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-eci-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%.