W3cubDocs

/Ansible

community.general.ali_instance – Create, Start, Stop, Restart or Terminate an Instance in ECS. Add or Remove Instance to/from a Security Group.

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.ali_instance.

Synopsis

  • Create, start, stop, restart, modify or terminate ecs instances.
  • Add or remove ecs instances to/from security group.

Requirements

The below requirements are needed on the host that executes this module.

  • footmark >= 1.19.0
  • python >= 3.6

Parameters

Parameter Choices/Defaults Comments
alicloud_access_key
string
Alibaba Cloud access key. If not set then the value of environment variable ALICLOUD_ACCESS_KEY, ALICLOUD_ACCESS_KEY_ID will be used instead.

aliases: access_key_id, access_key
alicloud_assume_role
dictionary
If provided with a role ARN, Ansible will attempt to assume this role using the supplied credentials.
The nested assume_role block supports alicloud_assume_role_arn, alicloud_assume_role_session_name, alicloud_assume_role_session_expiration and alicloud_assume_role_policy

aliases: assume_role
alicloud_assume_role_arn
string
The Alibaba Cloud role_arn. The ARN of the role to assume. If ARN is set to an empty string, it does not perform role switching. It supports environment variable ALICLOUD_ASSUME_ROLE_ARN. ansible will execute with provided credentials.

aliases: assume_role_arn
alicloud_assume_role_session_expiration
integer
The Alibaba Cloud session_expiration. The time after which the established session for assuming role expires. Valid value range 900-3600 seconds. Default to 3600 (in this case Alicloud use own default value). It supports environment variable ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION

aliases: assume_role_session_expiration
alicloud_assume_role_session_name
string
The Alibaba Cloud session_name. The session name to use when assuming the role. If omitted, 'ansible' is passed to the AssumeRole call as session name. It supports environment variable ALICLOUD_ASSUME_ROLE_SESSION_NAME

aliases: assume_role_session_name
alicloud_region
string / required
The Alibaba Cloud region to use. If not specified then the value of environment variable ALICLOUD_REGION, ALICLOUD_REGION_ID will be used instead.

aliases: region, region_id
alicloud_secret_key
string
Alibaba Cloud secret key. If not set then the value of environment variable ALICLOUD_SECRET_KEY, ALICLOUD_SECRET_ACCESS_KEY will be used instead.

aliases: secret_access_key, secret_key
alicloud_security_token
string
The Alibaba Cloud security token. If not specified then the value of environment variable ALICLOUD_SECURITY_TOKEN will be used instead.

aliases: security_token
allocate_public_ip
boolean
    Choices:
  • no ←
  • yes
Whether allocate a public ip for the new instance.

aliases: assign_public_ip
auto_renew
boolean
    Choices:
  • no ←
  • yes
Whether automate renew the charge of the instance.
auto_renew_period
integer
    Choices:
  • 1
  • 2
  • 3
  • 6
  • 12
The duration of the automatic renew the charge of the instance. Required when auto_renew=True.
availability_zone
string
Aliyun availability zone ID in which to launch the instance. If it is not specified, it will be allocated by system automatically.

aliases: alicloud_zone, zone_id
count
integer
Default:
1
The number of the new instance. An integer value which indicates how many instances that match count_tag should be running. Instances are either created or terminated based on this value.
count_tag
string
count determines how many instances based on a specific tag criteria should be present. This can be expressed in multiple ways and is shown in the EXAMPLES section. The specified count_tag must already exist or be passed in as the tags option. If it is not specified, it will be replaced by instance_name.
description
string
The description of ECS instance, which is a string of 2 to 256 characters. It cannot begin with http:// or https://.
dry_run
boolean
added in 0.2.0 of community.general
    Choices:
  • no ←
  • yes
Specifies whether to send a dry-run request.
If dry_run=True, Only a dry-run request is sent and no instance is created. The system checks whether the required parameters are set, and validates the request format, service permissions, and available ECS instances. If the validation fails, the corresponding error code is returned. If the validation succeeds, the DryRunOperation error code is returned.
If dry_run=False, A request is sent. If the validation succeeds, the instance is created.
ecs_role_name
string
The RAM Role Name attached on a ECS instance for API operations. You can retrieve this from the 'Access Control' section of the Alibaba Cloud console.
If you're running Ansible from an ECS instance with RAM Instance using RAM Role, Ansible will just access the metadata http://100.100.100.200/latest/meta-data/ram/security-credentials/<ecs_role_name> to obtain the STS credential. This is a preferred approach over any other when running in ECS as you can avoid hard coding credentials. Instead these are leased on-the-fly by Ansible which reduces the chance of leakage.

aliases: role_name
force
boolean
    Choices:
  • no ←
  • yes
Whether the current operation needs to be execute forcibly.
host_name
string
Instance host name. Ordered hostname is not supported.
image_id
string
Image ID used to launch instances. Required when state=present and creating new ECS instances.

aliases: image
include_data_disks
boolean
added in 0.2.0 of community.general
    Choices:
  • no
  • yes ←
Whether to change instance disks charge type when changing instance charge type.
instance_charge_type
string
    Choices:
  • PrePaid
  • PostPaid ←
The charge type of the instance.
instance_ids
list / elements=string
A list of instance ids. It is required when need to operate existing instances. If it is specified, count will lose efficacy.
instance_name
string
The name of ECS instance, which is a string of 2 to 128 Chinese or English characters. It must begin with an uppercase/lowercase letter or a Chinese character and can contain numerals, ".", "_" or "-". It cannot begin with http:// or https://.

aliases: name
instance_type
string
Instance type used to launch instances. Required when state=present and creating new ECS instances.

aliases: type
internet_charge_type
string
    Choices:
  • PayByBandwidth ←
  • PayByTraffic
Internet charge type of ECS instance.
key_name
string
The name of key pair which is used to access ECS instance in SSH.

aliases: keypair
max_bandwidth_in
integer
Default:
200
Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second).
max_bandwidth_out
integer
Default:
0
Maximum outgoing bandwidth to the public network, measured in Mbps (Megabits per second). Required when allocate_public_ip=True. Ignored when allocate_public_ip=False.
password
string
The password to login instance. After rebooting instances, modified password will take effect.
period
integer
Default:
1
The charge duration of the instance, in month. Required when instance_charge_type=PrePaid.
The valid value are [1-9, 12, 24, 36].
period_unit
string
added in 0.2.0 of community.general
    Choices:
  • Month ←
  • Week
The duration unit that you will buy the resource. It is valid when instance_charge_type=PrePaid
profile
string
This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the ALICLOUD_PROFILE environment variable.
purge_tags
boolean
added in 0.2.0 of community.general
    Choices:
  • no ←
  • yes
Delete any tags not specified in the task that are on the instance. If True, it means you have to specify all the desired tags on each task affecting an instance.
ram_role_name
string
added in 0.2.0 of community.general
The name of the instance RAM role.
security_groups
list / elements=string
A list of security group IDs.

aliases: group_ids
shared_credentials_file
string
This is the path to the shared credentials file. It can also be sourced from the ALICLOUD_SHARED_CREDENTIALS_FILE environment variable.
If this is not set and a profile is specified, ~/.aliyun/config.json will be used.
spot_price_limit
float
added in 0.2.0 of community.general
The maximum hourly price for the preemptible instance. This parameter supports a maximum of three decimal places and takes effect when the SpotStrategy parameter is set to SpotWithPriceLimit.
spot_strategy
string
added in 0.2.0 of community.general
    Choices:
  • NoSpot ←
  • SpotWithPriceLimit
  • SpotAsPriceGo
The bidding mode of the pay-as-you-go instance. This parameter is valid when InstanceChargeType is set to PostPaid.
state
string
    Choices:
  • present ←
  • running
  • stopped
  • restarted
  • absent
The state of the instance after operating.
system_disk_category
string
    Choices:
  • cloud_efficiency ←
  • cloud_ssd
Category of the system disk.
system_disk_description
string
Description of the system disk.
system_disk_name
string
Name of the system disk.
system_disk_size
integer
Default:
40
Size of the system disk, in GB. The valid values are 40~500.
tags
dictionary
added in 0.2.0 of community.general
A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. {"key":"value"}

aliases: instance_tags
unique_suffix
boolean
added in 0.2.0 of community.general
    Choices:
  • no ←
  • yes
Specifies whether to add sequential suffixes to the host_name. The sequential suffix ranges from 001 to 999.
user_data
string
User-defined data to customize the startup behaviors of an ECS instance and to pass data into an ECS instance. It only will take effect when launching the new ECS instances.
vswitch_id
string
The subnet ID in which to launch the instances (VPC).

aliases: subnet_id

Notes

Note

  • If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ALICLOUD_ACCESS_KEY or ALICLOUD_ACCESS_KEY_ID, ALICLOUD_SECRET_KEY or ALICLOUD_SECRET_ACCESS_KEY, ALICLOUD_REGION or 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 or ALICLOUD_REGION_ID can be typically be used to specify the ALICLOUD region, when required, but this can also be configured in the footmark config file

Examples

# 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 }}'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
ids
list / elements=string
always
List of ECS instance IDs

Sample:
['i-12345er', 'i-3245fs']
instances
complex
always
List of ECS instances
availability_zone
string
always
The availability zone of the instance is in.

Sample:
cn-beijing-a
block_device_mappings
complex
always
Any block device mapping entries for the instance.
attach_time
string
always
The time stamp when the attachment initiated.

Sample:
2018-06-25T04:08:26Z
delete_on_termination
boolean
always
Indicates whether the volume is deleted on instance termination.

Sample:
True
device_name
string
always
The device name exposed to the instance (for example, /dev/xvda).

Sample:
/dev/xvda
status
string
always
The attachment state.

Sample:
in_use
volume_id
string
always
The ID of the cloud disk.

Sample:
d-2zei53pjsi117y6gf9t6
cpu
integer
always
The CPU core count of the instance.

Sample:
4
creation_time
string
always
The time the instance was created.

Sample:
2018-06-25T04:08Z
description
string
always
The instance description.

Sample:
my ansible instance
eip
complex
always
The attribution of EIP associated with the instance.
allocation_id
string
always
The ID of the EIP.

Sample:
eip-12345
internet_charge_type
string
always
The internet charge type of the EIP.

Sample:
paybybandwidth
ip_address
string
always
EIP address.

Sample:
42.10.2.2
expired_time
string
always
The time the instance will expire.

Sample:
2099-12-31T15:59Z
gpu
complex
always
The attribution of instance GPU.
amount
integer
always
The count of the GPU.
spec
string
always
The specification of the GPU.
host_name
string
always
The host name of the instance.

Sample:
iZ2zewaoZ
id
string
always
Alias of instance_id.

Sample:
i-abc12345
image_id
string
always
The ID of the image used to launch the instance.

Sample:
m-0011223344
inner_ip_address
string
always
The inner IPv4 address of the classic instance.

Sample:
10.0.0.2
instance_charge_type
string
always
The instance charge type.

Sample:
PostPaid
instance_id
string
always
ECS instance resource ID.

Sample:
i-abc12345
instance_name
string
always
The name of the instance.

Sample:
my-ecs
instance_type
string
always
The instance type of the running instance.

Sample:
ecs.sn1ne.xlarge
instance_type_family
string
always
The instance type family of the instance belongs.

Sample:
ecs.sn1ne
internet_charge_type
string
always
The billing method of the network bandwidth.

Sample:
PayByBandwidth
internet_max_bandwidth_in
integer
always
Maximum incoming bandwidth from the internet network.

Sample:
200
internet_max_bandwidth_out
integer
always
Maximum incoming bandwidth from the internet network.

Sample:
20
io_optimized
boolean
always
Indicates whether the instance is optimized for EBS I/O.
memory
integer
always
Memory size of the instance.

Sample:
8192
network_interfaces
complex
always
One or more network interfaces for the instance.
mac_address
string
always
The MAC address.

Sample:
00:11:22:33:44:55
network_interface_id
string
always
The ID of the network interface.

Sample:
eni-01234567
primary_ip_address
string
always
The primary IPv4 address of the network interface within the vswitch.

Sample:
10.0.0.1
osname
string
always
The operation system name of the instance owned.

Sample:
CentOS
ostype
string
always
The operation system type of the instance owned.

Sample:
linux
private_ip_address
string
always
The IPv4 address of the network interface within the subnet.

Sample:
10.0.0.1
public_ip_address
string
always
The public IPv4 address assigned to the instance or eip address

Sample:
43.0.0.1
resource_group_id
string
always
The id of the resource group to which the instance belongs.

Sample:
my-ecs-group
security_groups
list / elements=dictionary
always
One or more security groups for the instance.
group_id
string
always
The ID of the security group.

Sample:
sg-0123456
group_name
string
always
The name of the security group.

Sample:
my-security-group
spot_price_limit
float
always
The maximum hourly price for the preemptible instance.

Sample:
0.97
spot_strategy
string
always
The bidding mode of the pay-as-you-go instance.

Sample:
NoSpot
status
string
always
The current status of the instance.

Sample:
running
tags
dictionary
always
Any tags assigned to the instance.
user_data
dictionary
always
User-defined data.
vpc_id
string
always
The ID of the VPC the instance is in.

Sample:
vpc-0011223344
vswitch_id
string
always
The ID of the vswitch in which the instance is running.

Sample:
vsw-dew00abcdef


Authors

  • He Guimin (@xiaozhu36)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/ali_instance_module.html