community.general.ali_instance 模块 – 在 ECS 中创建、启动、停止、重启或终止实例；将实例添加到安全组或从安全组删除

注意

此模块是 community.general 集合（版本 10.1.0）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要进一步的要求才能使用此模块，有关详细信息，请参阅要求。

要在 playbook 中使用它，请指定：community.general.ali_instance。

概要

• 创建、启动、停止、重启、修改或终止 ECS 实例。

• 将 ECS 实例添加到安全组或从安全组删除。

要求

执行此模块的主机需要满足以下要求。

• Python >= 3.6

• footmark >= 1.19.0

参数

参数	注释
alicloud_access_key 别名: access_key_id, access_key 字符串	阿里云访问密钥。如果未设置，则将使用环境变量 ALICLOUD_ACCESS_KEY、ALICLOUD_ACCESS_KEY_ID 的值。
alicloud_assume_role 别名: assume_role 字典	如果提供了角色 ARN，Ansible 将尝试使用提供的凭据担任此角色。 嵌套的 assume_role 块支持 alicloud_assume_role_arn、alicloud_assume_role_session_name、alicloud_assume_role_session_expiration 和 alicloud_assume_role_policy。
alicloud_assume_role_arn 别名: assume_role_arn 字符串	阿里云 role_arn。要担任的角色的 ARN。如果 ARN 设置为空字符串，则不执行角色切换。它支持环境变量 ALICLOUD_ASSUME_ROLE_ARN。ansible 将使用提供的凭据执行。
alicloud_assume_role_session_expiration 别名: assume_role_session_expiration 整数	阿里云 session_expiration。担任角色的已建立会话过期的时间。有效值范围为 900-3600 秒。默认为 3600（在这种情况下，阿里云使用自己的默认值）。它支持环境变量 ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION。
alicloud_assume_role_session_name 别名: assume_role_session_name 字符串	阿里云 session_name。担任角色时要使用的会话名称。如果省略，则将 'ansible' 作为会话名称传递给 AssumeRole 调用。它支持环境变量 ALICLOUD_ASSUME_ROLE_SESSION_NAME。
alicloud_region 别名: region, region_id 字符串 / 必需	要使用的阿里云区域。如果未指定，则将使用环境变量 ALICLOUD_REGION、ALICLOUD_REGION_ID 的值。
alicloud_secret_key 别名: secret_access_key, secret_key 字符串	阿里云密钥。如果未设置，则将使用环境变量 ALICLOUD_SECRET_KEY、ALICLOUD_SECRET_ACCESS_KEY 的值。
alicloud_security_token 别名: security_token 字符串	阿里云安全令牌。如果未指定，则将使用环境变量 ALICLOUD_SECURITY_TOKEN 的值。
allocate_public_ip 别名: assign_public_ip 布尔值	是否为新实例分配公网 IP。 选项 false ← (默认) true
auto_renew 布尔值	是否自动续订实例费用。 选项 false ← (默认) true
auto_renew_period 整数	自动续订实例费用的时长。当 auto_renew=true 时为必需项。 选项 1 2 3 6 12
availability_zone 别名: alicloud_zone, zone_id 字符串	启动实例的阿里云可用区 ID。如果未指定，系统将自动分配。
count 整数	新实例的数量。一个整数值，表示应运行多少与 count_tag 匹配的实例。实例将根据此值创建或终止。 默认值: 1
count_tag 字符串	count 确定应存在多少基于特定标签标准的实例。这可以用多种方式表示，并在“示例”部分中显示。指定的 count_tag 必须已存在或作为 tags 选项传入。如果未指定，则将其替换为 instance_name。
description 字符串	ECS 实例的描述，长度为 2 到 256 个字符的字符串。不能以 http:// 或 https:// 开头。
dry_run 布尔值 在 community.general 0.2.0 中添加	指定是否发送试运行请求。 如果 dry_run=true，则仅发送试运行请求，不会创建任何实例。系统会检查是否设置了必需的参数，并验证请求格式、服务权限和可用的 ECS 实例。如果验证失败，则返回相应的错误代码。如果验证成功，则返回 DryRunOperation 错误代码。 如果 dry_run=false，则发送请求。如果验证成功，则创建实例。 选项 false ← (默认) true
ecs_role_name 别名: role_name 字符串	附加在 ECS 实例上的 RAM 角色名称，用于 API 操作。您可以从阿里云控制台的“访问控制”部分检索此名称。 如果您正在使用 RAM 角色从具有 RAM 实例的 ECS 实例运行 Ansible，则 Ansible 将仅访问元数据 http://100.100.100.200/latest/meta-data/ram/security-credentials/<ecs_role_name> 以获取 STS 凭据。当在 ECS 中运行时，这是一种优于任何其他方法的首选方法，因为您可以避免硬编码凭据。相反，这些凭据由 Ansible 动态租用，从而减少泄漏的机会。
force 布尔值	当前操作是否需要强制执行。 选项 false ← (默认) true
host_name 字符串	实例主机名。不支持有序主机名。
image_id 别名: image 字符串	用于启动实例的镜像 ID。当 state=present 并且创建新的 ECS 实例时为必需项。
include_data_disks 布尔值 在 community.general 0.2.0 中添加	更改实例计费类型时是否更改实例磁盘的计费类型。 选项 false true ← (默认)
instance_charge_type 字符串	实例的计费类型。 选项 "PrePaid" "PostPaid" ← (默认)
instance_ids 列表 / 元素=字符串	实例 ID 列表。需要操作现有实例时为必需项。如果指定了此项，则 count 将失效。
instance_name 别名: name 字符串	ECS 实例的名称，长度为 2 到 128 个中英文的字符串。必须以大写/小写字母或汉字开头，并且可以包含数字、“.”、“_”或“-”。不能以 http:// 或 https:// 开头。
instance_type 别名: type 字符串	用于启动实例的实例类型。当 state=present 并且创建新的 ECS 实例时为必需项。
internet_charge_type 字符串	ECS 实例的 Internet 计费类型。 选项 "PayByBandwidth" ← (默认) "PayByTraffic"
key_name 别名: keypair 字符串	用于通过 SSH 访问 ECS 实例的密钥对的名称。
max_bandwidth_in 整数	来自公网的最大传入带宽，以 Mbps（兆比特/秒）为单位衡量。 默认值: 200
max_bandwidth_out 整数	到公网的最大传出带宽，以 Mbps（兆比特/秒）为单位衡量。当 allocate_public_ip=true 时为必需项。当 allocate_public_ip=false 时将被忽略。 默认值: 0
password 字符串	用于登录实例的密码。重新启动实例后，修改后的密码将生效。
period 整数	实例的计费时长，以月为单位。当 instance_charge_type=PrePaid 时为必需项。 有效值为 [1-9, 12, 24, 36]。 默认值: 1
period_unit 字符串 在 community.general 0.2.0 中添加	您将购买资源的持续时间单位。当 instance_charge_type=PrePaid 时有效。 选项 "Month" ← (默认) "Week"
profile 字符串	这是在共享凭据文件中设置的阿里云配置文件名称。它也可以从 ALICLOUD_PROFILE 环境变量中获取。
purge_tags 布尔值 在 community.general 0.2.0 中添加	删除实例上未在任务中指定的任何标签。如果为 True，则意味着您必须在影响实例的每个任务上指定所有所需的标签。 选项 false ← (默认) true
ram_role_name 字符串 在 community.general 0.2.0 中添加	实例 RAM 角色的名称。
security_groups 别名: group_ids 列表 / 元素=字符串	安全组 ID 列表。
shared_credentials_file 字符串	这是共享凭据文件的路径。它也可以从 ALICLOUD_SHARED_CREDENTIALS_FILE 环境变量中获取。 如果未设置此项且指定了配置文件，则将使用 ~/.aliyun/config.json。
spot_price_limit 浮点数 在 community.general 0.2.0 中添加	抢占式实例的最高小时价格。此参数最多支持三位小数，并且当 SpotStrategy 参数设置为 SpotWithPriceLimit 时生效。
spot_strategy 字符串 在 community.general 0.2.0 中添加	按需付费实例的竞价模式。当 InstanceChargeType 设置为 PostPaid 时，此参数有效。 选项 "NoSpot" ← (默认) "SpotWithPriceLimit" "SpotAsPriceGo"
state 字符串	操作后实例的状态。 选项 "present" ← (默认) "running" "stopped" "restarted" "absent"
system_disk_category 字符串	系统盘的类别。 选项 "cloud_efficiency" ← (默认) "cloud_ssd"
system_disk_description 字符串	系统盘的描述。
system_disk_name 字符串	系统盘的名称。
system_disk_size 整数	系统盘的大小，以 GB 为单位。有效值为 40~500。 默认值: 40
tags 别名: instance_tags 字典 在 community.general 0.2.0 中添加	实例标签的哈希/字典，用于添加到新实例或通过标签启动/停止实例。{"key":"value"}
unique_suffix 布尔值 在 community.general 0.2.0 中添加	指定是否在主机名后添加顺序后缀。顺序后缀的范围为 001 到 999。 选项 false ← (默认) true
user_data 字符串	用户定义的数据，用于自定义 ECS 实例的启动行为并将数据传递到 ECS 实例中。仅在启动新的 ECS 实例时生效。
vswitch_id 别名: subnet_id 字符串	用于启动实例的子网 ID (VPC)。

属性

属性	支持	描述
check_mode	支持: 无	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标。
diff_mode	支持: 无	在 diff 模式下，将返回有关已更改（或可能需要在 check_mode 中更改）的内容的详细信息。

注意

注意

• 如果未在模块中设置参数，则可以按优先级降序使用以下环境变量：ALICLOUD_ACCESS_KEY 或 ALICLOUD_ACCESS_KEY_ID， ALICLOUD_SECRET_KEY 或 ALICLOUD_SECRET_ACCESS_KEY， ALICLOUD_REGION 或 ALICLOUD_REGION_ID， ALICLOUD_SECURITY_TOKEN， ALICLOUD_ECS_ROLE_NAME， ALICLOUD_SHARED_CREDENTIALS_FILE， ALICLOUD_PROFILE， ALICLOUD_ASSUME_ROLE_ARN， ALICLOUD_ASSUME_ROLE_SESSION_NAME， ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION。

• ALICLOUD_REGION 或 ALICLOUD_REGION_ID 通常可用于指定阿里云区域（如果需要），但也可以在 footmark 配置文件中配置。

示例

# basic provisioning example vpc network
- name: Basic provisioning example
  hosts: localhost
  vars:
    alicloud_access_key: <your-alicloud-access-key-id>
    alicloud_secret_key: <your-alicloud-access-secret-key>
    alicloud_region: cn-beijing
    image: ubuntu1404_64_40G_cloudinit_20160727.raw
    instance_type: ecs.n4.small
    vswitch_id: vsw-abcd1234
    assign_public_ip: true
    max_bandwidth_out: 10
    host_name: myhost
    password: mypassword
    system_disk_category: cloud_efficiency
    system_disk_size: 100
    internet_charge_type: PayByBandwidth
    security_groups: ["sg-f2rwnfh23r"]

    instance_ids: ["i-abcd12346", "i-abcd12345"]
    force: true

  tasks:
    - name: Launch ECS instance in VPC network
      community.general.ali_instance:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        image: '{{ image }}'
        system_disk_category: '{{ system_disk_category }}'
        system_disk_size: '{{ system_disk_size }}'
        instance_type: '{{ instance_type }}'
        vswitch_id: '{{ vswitch_id }}'
        assign_public_ip: '{{ assign_public_ip }}'
        internet_charge_type: '{{ internet_charge_type }}'
        max_bandwidth_out: '{{ max_bandwidth_out }}'
        tags:
            Name: created_one
        host_name: '{{ host_name }}'
        password: '{{ password }}'

    - name: With count and count_tag to create a number of instances
      community.general.ali_instance:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        image: '{{ image }}'
        system_disk_category: '{{ system_disk_category }}'
        system_disk_size: '{{ system_disk_size }}'
        instance_type: '{{ instance_type }}'
        assign_public_ip: '{{ assign_public_ip }}'
        security_groups: '{{ security_groups }}'
        internet_charge_type: '{{ internet_charge_type }}'
        max_bandwidth_out: '{{ max_bandwidth_out }}'
        tags:
            Name: created_one
            Version: 0.1
        count: 2
        count_tag:
            Name: created_one
        host_name: '{{ host_name }}'
        password: '{{ password }}'

    - name: Start instance
      community.general.ali_instance:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        instance_ids: '{{ instance_ids }}'
        state: 'running'

    - name: Reboot instance forcibly
      ecs:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        instance_ids: '{{ instance_ids }}'
        state: 'restarted'
        force: '{{ force }}'

    - name: Add instances to an security group
      ecs:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        instance_ids: '{{ instance_ids }}'
        security_groups: '{{ security_groups }}'

返回值

通用返回值记录在此处：此处，以下是此模块特有的字段

键	描述
ids 列表 / 元素=字符串	ECS 实例 ID 列表 返回: 始终 示例: ["i-12345er", "i-3245fs"]
instances 复杂类型	ECS 实例列表 返回: 始终
availability_zone 字符串	实例所在的可用区。 返回: 始终 示例: "cn-beijing-a"
block_device_mappings 复杂类型	实例的任何块设备映射条目。 返回: 始终
attach_time 字符串	启动挂载的时间戳。 返回: 始终 示例: "2018-06-25T04:08:26Z"
delete_on_termination 布尔值	指示是否在实例终止时删除卷。 返回: 始终 示例: true
device_name 字符串	暴露给实例的设备名称（例如，/dev/xvda）。 返回: 始终 示例: "/dev/xvda"
status 字符串	挂载状态。 返回: 始终 示例: "in_use"
volume_id 字符串	云盘的 ID。 返回: 始终 示例: "d-2zei53pjsi117y6gf9t6"
cpu 整数	实例的 CPU 核心数。 返回: 始终 示例: 4
creation_time 字符串	创建实例的时间。 返回: 始终 示例: "2018-06-25T04:08Z"
description 字符串	实例描述。 返回: 始终 示例: "我的 ansible 实例"
eip 复杂类型	与实例关联的 EIP 的属性。 返回: 始终
allocation_id 字符串	EIP 的 ID。 返回: 始终 示例: "eip-12345"
internet_charge_type 字符串	EIP 的互联网计费类型。 返回: 始终 示例: "paybybandwidth"
ip_address 字符串	EIP 地址。 返回: 始终 示例: "42.10.2.2"
expired_time 字符串	实例到期时间。 返回: 始终 示例: "2099-12-31T15:59Z"
gpu 复杂类型	实例 GPU 的属性。 返回: 始终
amount 整数	GPU 的数量。 返回: 始终 示例: 0
spec 字符串	GPU 的规格。 返回: 始终 示例: ""
host_name 字符串	实例的主机名。 返回: 始终 示例: "iZ2zewaoZ"
id 字符串	instance_id 的别名。 返回: 始终 示例: "i-abc12345"
image_id 字符串	用于启动实例的镜像 ID。 返回: 始终 示例: "m-0011223344"
inner_ip_address 字符串	经典实例的内部 IPv4 地址。 返回: 始终 示例: "10.0.0.2"
instance_charge_type 字符串	实例的计费类型。 返回: 始终 示例: "PostPaid"
instance_id 字符串	ECS 实例资源 ID。 返回: 始终 示例: "i-abc12345"
instance_name 字符串	实例的名称。 返回: 始终 示例: "my-ecs"
instance_type 字符串	正在运行的实例的实例类型。 返回: 始终 示例: "ecs.sn1ne.xlarge"
instance_type_family 字符串	实例所属的实例类型族。 返回: 始终 示例: "ecs.sn1ne"
internet_charge_type 字符串	网络带宽的计费方式。 返回: 始终 示例: "PayByBandwidth"
internet_max_bandwidth_in 整数	来自互联网网络的最大入站带宽。 返回: 始终 示例: 200
internet_max_bandwidth_out 整数	来自互联网网络的最大入站带宽。 返回: 始终 示例: 20
io_optimized 布尔值	指示实例是否针对 EBS I/O 进行了优化。 返回: 始终 示例: false
memory 整数	实例的内存大小。 返回: 始终 示例: 8192
network_interfaces 复杂类型	实例的一个或多个网络接口。 返回: 始终
mac_address 字符串	MAC 地址。 返回: 始终 示例: "00:11:22:33:44:55"
network_interface_id 字符串	网络接口的 ID。 返回: 始终 示例: "eni-01234567"
primary_ip_address 字符串	vswitch 内网络接口的主要 IPv4 地址。 返回: 始终 示例: "10.0.0.1"
osname 字符串	实例拥有的操作系统名称。 返回: 始终 示例: "CentOS"
ostype 字符串	实例拥有的操作系统类型。 返回: 始终 示例: "linux"
private_ip_address 字符串	子网内网络接口的 IPv4 地址。 返回: 始终 示例: "10.0.0.1"
public_ip_address 字符串	分配给实例或 EIP 地址的公共 IPv4 地址 返回: 始终 示例: "43.0.0.1"
resource_group_id 字符串	实例所属的资源组的 ID。 返回: 始终 示例: "my-ecs-group"
security_groups 列表 / 元素=字典	实例的一个或多个安全组。 返回: 始终
group_id 字符串	安全组的 ID。 返回: 始终 示例: "sg-0123456"
group_name 字符串	安全组的名称。 返回: 始终 示例: "my-security-group"
spot_price_limit 浮点数	抢占式实例的每小时最高价格。 返回: 始终 示例: 0.97
spot_strategy 字符串	按量付费实例的竞价模式。 返回: 始终 示例: "NoSpot"
status 字符串	实例的当前状态。 返回: 始终 示例: "running"
标签 字典	分配给实例的任何标签。 返回: 始终
user_data 字典	用户定义的数据。 返回: 始终
vpc_id 字符串	实例所在的 VPC 的 ID。 返回: 始终 示例: "vpc-0011223344"
vswitch_id 字符串	实例运行所在的 vswitch 的 ID。 返回: 始终 示例: "vsw-dew00abcdef"

作者

• 何桂敏 (@xiaozhu36)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助
• 提交错误报告
• 请求新功能
• 通信