使用 ecctl 创建 ECS 实例

准备阿里云账号与权限

阿里云账号（主账号）拥有资源的所有权限，其 AccessKey 一旦泄露风险巨大。建议使用满足最小化权限需求的 RAM 用户的 AccessKey 来调用 ecctl。准备工作如下：

1. 创建 RAM 用户并获取 AccessKey（AccessKey ID 和 AccessKey Secret），具体操作请参见创建 RAM 用户和创建 AccessKey。

2. 给步骤一中创建的 RAM 用户授予操作云服务器 ECS 和专有网络 VPC 相关资源的权限，授权方式请参照为 RAM 用户新增授权。本文示例需要创建 ECS 实例、VPC、VSwitch、安全组、密钥对等资源，建议授予以下系统策略：

   云产品	授予权限
   专有网络 VPC	AliyunVPCFullAccess
   云服务器 ECS	AliyunECSFullAccess

安装 ecctl

如果是临时调试，也可使用阿里云提供的云命令行 Cloud Shell，无需在本地安装 CLI。

根据操作系统选择安装方式：

brew tap aliyun/ecctl https://github.com/aliyun/elastic-compute-control-cli
brew install ecctl

go install github.com/aliyun/elastic-compute-control-cli/cmd/ecctl@latest

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc && source ~/.bashrc

ecctl --version

配置凭据与地域

执行以下命令配置地域和 RAM 用户的 AccessKey 即可（<AccessKeyId>、<AccessKeySecret> 即步骤一中获取的 AccessKey）：

ecctl configure set region cn-hangzhou
ecctl configure set access-key-id <AccessKeyId>
ecctl configure set access-key-secret <AccessKeySecret>

更多配置项（输出格式、语言、profile、环境变量等）请参考 ecctl 配置文档。

查看命令（可选）

调用命令前可以查看命令说明：

# 查看命令说明（JSON 格式）
ecctl schema ecs.instance.create --brief

# 查看参数帮助
ecctl ecs instance create --help

• schema：输出结构化 JSON，方便 Agent 解析。其中 params 字段列出各参数的说明与是否必填，contract 字段声明 dry-run、幂等、等待等行为约定。

• --help：输出人类可读的帮助，包含用法示例（Examples）与参数列表（Resource Flags），必填参数以 * 标注。

• schema 支持逐层查询：ecctl schema ecs → ecctl schema ecs.instance，可逐层定位可用命令。

查询库存（可选）

创建前可先确认目标地域、可用区是否有对应规格与系统盘库存。以查询杭州地区的 ecs.g7.large 规格实例为例，该命令会返回在杭州哪些可用区存在可用库存。

# 查询实例规格库存
ecctl call ecs DescribeAvailableResource \
  --region cn-hangzhou \
  --DestinationResource InstanceType \
  --IoOptimized optimized \
  --InstanceType ecs.g7.large

确认目标实例规格和可用区库存后，可查询系统盘库存。使用 DestinationResource=SystemDisk 指定查询资源为系统盘，搭配 InstanceType、ZoneId 指定实例规格和可用区：

ecctl call ecs DescribeAvailableResource \
  --region cn-hangzhou \
  --ZoneId cn-hangzhou-b \
  --ResourceType instance \
  --DestinationResource SystemDisk \
  --InstanceType ecs.g7.large \
  --SystemDiskCategory cloud_essd

若创建时因库存不足失败，ecctl 会在错误信息中自动给出对应的 DescribeAvailableResource 查询命令，详见错误处理。

创建前置资源

创建实例前需要先准备网络和安全组等资源。以下命令按顺序创建 VPC、交换机、安全组，为安全组放通所需端口，以及密钥对（可选）；如果已有可用资源，可跳过此步骤，直接在创建实例时填入已有资源 ID：

# 1. 创建 VPC
ecctl vpc create --name demo-vpc --cidr 10.0.0.0/16 --region cn-hangzhou
# → 可通过 vpc.id 字段获取 VPC Id，如 vpc-bp1234567890example

# 2. 在 VPC 内创建交换机
ecctl vpc vswitch create \
  --vpc vpc-bp1234567890example \
  --zone cn-hangzhou-b \
  --cidr 10.0.1.0/24 \
  --name demo-vsw \
  --region cn-hangzhou
# → 可通过 vswitch.id 字段获取交换机 Id，如 vsw-bp1234567890example


# 3. 创建安全组
ecctl ecs sg create \
  --vpc vpc-bp1234567890example \
  --name demo-sg \
  --region cn-hangzhou
# → 可通过 security_group.id 字段获取安全组 Id，如 sg-bp1234567890example

# 4. 为安全组放通 SSH 登录所需的 22 端口入方向规则
ecctl ecs sg authorize sg-bp1234567890example --region cn-hangzhou --rule tcp:22@0.0.0.0/0

# 5.（可选）创建密钥对，用于后续 SSH 登录
# 生成密钥文件
ssh-keygen -t rsa -b 2048 -f <本地密钥文件路径>
# 导入已有密钥对， --public-key 需以 @ 开头并指向公钥文件（后缀为.pub）。
ecctl ecs keypair create \
  --name web-key \
  --region cn-hangzhou \
  --public-key "@<本地公钥文件路径>"

创建实例

把前置流程中得到的vSwitch、安全组 ID 填入 --vswitch、--sg。正式创建前，可先在命令末尾加上 --dry-run 触发服务端校验而不真正创建（仅支持 1 台实例，请不要设置 --amount参数）：

ecctl ecs instance create \
  --region cn-hangzhou \
  --type ecs.g7.large \
  --image aliyun_3 \
  --sg sg-bp1234567890example \
  --vswitch vsw-bp1234567890example

该命令会：

1. 先发起 RunInstances 创建请求（自动携带幂等 ClientToken）；

2. 轮询 DescribeInstances，等待实例状态变为 Running；

3. 返回实例的最终视图。

上述幂等与等待均为默认行为，可按需调整：

• --idempotency-key：显式指定幂等标识（默认自动生成）；

• --no-wait：创建后立即返回，不等待实例进入 Running；

• --timeout：修改等待上限（默认等待实例进入 Running，超时 300s），如 --timeout 10m。

常用参数

下表列出创建实例时常用的参数。完整参数可执行 ecctl ecs instance create --help 查看，或参见 create 完整参数。ecctl 还内置镜像名称解析等 ECS 专项优化。

# 系统盘：磁盘类型、容量（GiB）、ESSD 性能等级
--system-disk '{
  "category": "cloud_essd",
  "size": 40,
  "performance_level": "PL1"
}'

# 数据盘：磁盘类型、容量（GiB）
--data-disk '{
  "category": "cloud_essd",
  "size": 100
}'

结果与查询

创建成功时，ecctl 返回结构化 JSON（--output json 为默认输出模式），包含以下三部分：

• actions：本次命令实际调用过的每个 OpenAPI 及其 request_id，可用于排查问题或提交工单。等待阶段会轮询多次 DescribeInstances，因此数组中通常包含多条记录；

• ecctl_capabilities_used：本次命令用到的 ecctl 内置能力，如 auto_wait（自动等待实例就绪）；

• instance：实例创建完成后的完整视图，包含 id、status、网络配置等字段，后续操作（连接、释放）所需的实例 ID 即从这里获取。

输出示例（仅保留关键字段）：

{
  "actions": [
    {"action_name": "RunInstances", "request_id": "A1B2C3D4-..."},
    {"action_name": "DescribeInstances", "request_id": "B2C3D4E5-..."}
  ],
  "ecctl_capabilities_used": ["auto_wait"],
  "instance": {
    "id": "i-bp1234567890example",
    "name": "web-01",
    "status": "Running"
    // 其余字段省略
  }
}

创建完成后，也可以随时查询实例信息：get 按实例 Id 查看单台实例的详情，list 分页列出实例并通过 --filter 按状态、标签等条件过滤：

ecctl ecs instance get i-bp1234567890example --region cn-hangzhou

ecctl ecs instance list --region cn-hangzhou \
  --filter status=Running --filter tag.env=prod

完整示例

创建一台开通公网 IP、使用密钥对、挂载系统盘和数据盘、配置了标签和资源组的实例：

ecctl ecs instance create \
  --region cn-hangzhou \
  --zone cn-hangzhou-b \
  --type ecs.g7.large \
  --image aliyun_3 \
  --sg sg-bp1234567890example \
  --vswitch vsw-bp1234567890example \
  --name web-01 \
  --host-name web-01 \
  --key-pair web-key \
  --system-disk '{"category":"cloud_essd","size":40,"performance_level":"PL1"}' \
  --data-disk '{"category":"cloud_essd","size":100}' \
  --internet-charge-type PayByTraffic \
  --internet-bandwidth-out 10 \
  --tag env=prod --tag app=web \
  --resource-group rg-bp1234567890example

SSH 登录

--internet-charge-type PayByTraffic \
--internet-bandwidth-out <带宽（单位Mbps）>

ecctl ecs instance update i-bp1234567890example \
--region cn-hangzhou \
--internet-bandwidth-out 5 \
--allocate-public-ip

ecctl ecs instance list --region cn-hangzhou --filter id=i-bp1234567890example

{
  "instances": [
    {
      "id": "i-bp1234567890example",
      "public_ip_addresses": [
        "47.xx.xx.xx"
      ]
      // 其余字段省略
    }
  ]
}

通过云助手执行命令（无需公网 IP）

ecctl 通过云助手在实例内执行命令，自动等待执行完成并返回结果：

ecctl ecs instance exec i-bp1234567890example --region cn-hangzhou --command 'uname -a'

参数对照表

aliyun ecs RunInstances（部分）与 ecctl ecs instance create 参数对应关系：