Alicloud Eci Ops

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

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

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

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)

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.