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 使用自己的默认值）。它支持环境变量 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实例上用于API操作的RAM角色名称。您可以在阿里云控制台的“访问控制”部分中检索此信息。 如果您从使用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实例的互联网计费类型。 选项 "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 字符串	启动实例（VPC）所在的子网 ID。

属性

属性	支持	描述
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 通常可用于指定阿里云区域（如果需要），但也可以在脚印配置文件中配置。

示例

# 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 字符串	实例描述。 返回值：始终 示例："my ansible instance"
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 字符串	分配给实例的公共 IPv4 地址或 eip 地址 返回值：始终 示例："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"
tags 字典	分配给实例的任何标签。 返回值：始终
user_data 字典	用户定义数据。 返回值：始终
vpc_id 字符串	实例所在的 VPC 的 ID。 返回值：始终 示例："vpc-0011223344"
vswitch_id 字符串	实例在其上运行的 vswitch 的 ID。 返回值：始终 示例："vsw-dew00abcdef"

作者

• 何贵敏 (@xiaozhu36)

集合链接

• 问题追踪器
• 代码仓库
• 寻求帮助
• 提交错误报告
• 请求功能
• 通信