community.general.ali_instance module – Create, Start, Stop, Restart or Terminate an Instance in ECS; Add or Remove Instance to/from a Security Group
Note
This module is part of the community.general collection (version 6.6.2).
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.
You need further requirements to be able to use this module,
see Requirements for details.
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 |
Comments |
|---|---|
Alibaba Cloud access key. If not set then the value of environment variable |
|
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 |
|
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. |
|
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 |
|
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 |
|
The Alibaba Cloud region to use. If not specified then the value of environment variable |
|
Alibaba Cloud secret key. If not set then the value of environment variable |
|
The Alibaba Cloud security token. If not specified then the value of environment variable |
|
Whether allocate a public ip for the new instance. Choices:
|
|
Whether automate renew the charge of the instance. Choices:
|
|
The duration of the automatic renew the charge of the instance. Required when auto_renew=true. Choices:
|
|
Aliyun availability zone ID in which to launch the instance. If it is not specified, it will be allocated by system automatically. |
|
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. Default: |
|
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. |
|
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. Choices:
|
|
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. |
|
Whether the current operation needs to be execute forcibly. Choices:
|
|
Instance host name. Ordered hostname is not supported. |
|
Image ID used to launch instances. Required when state=present and creating new ECS instances. |
|
Whether to change instance disks charge type when changing instance charge type. Choices:
|
|
The charge type of the instance. Choices:
|
|
A list of instance ids. It is required when need to operate existing instances. If it is specified, count will lose efficacy. |
|
Instance type used to launch instances. Required when state=present and creating new ECS instances. |
|
Internet charge type of ECS instance. Choices:
|
|
The name of key pair which is used to access ECS instance in SSH. |
|
Maximum incoming bandwidth from the public network, measured in Mbps (Megabits per second). Default: |
|
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. Default: |
|
The password to login instance. After rebooting instances, modified password will take effect. |
|
The charge duration of the instance, in months. Required when instance_charge_type=PrePaid. The valid value are [1-9, 12, 24, 36]. Default: |
|
The duration unit that you will buy the resource. It is valid when instance_charge_type=PrePaid. Choices:
|
|
This is the Alicloud profile name as set in the shared credentials file. It can also be sourced from the ALICLOUD_PROFILE environment variable. |
|
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. Choices:
|
|
The name of the instance RAM role. |
|
A list of security group IDs. |
|
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. |
|
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. |
|
The bidding mode of the pay-as-you-go instance. This parameter is valid when InstanceChargeType is set to PostPaid. Choices:
|
|
The state of the instance after operating. Choices:
|
|
Category of the system disk. Choices:
|
|
Description of the system disk. |
|
Name of the system disk. |
|
Size of the system disk, in GB. The valid values are 40~500. Default: |
|
A hash/dictionaries of instance tags, to add to the new instance or for starting/stopping instance by tag. |
|
Specifies whether to add sequential suffixes to the host_name. The sequential suffix ranges from 001 to 999. Choices:
|
|
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. |
|
The subnet ID in which to launch the instances (VPC). |
Attributes
Attribute |
Support |
Description |
|---|---|---|
Support: none |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence
ALICLOUD_ACCESS_KEYorALICLOUD_ACCESS_KEY_ID,ALICLOUD_SECRET_KEYorALICLOUD_SECRET_ACCESS_KEY,ALICLOUD_REGIONorALICLOUD_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_REGIONorALICLOUD_REGION_IDcan 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 |
Description |
|---|---|
List of ECS instance IDs Returned: always Sample: |
|
List of ECS instances Returned: always |
|
The availability zone of the instance is in. Returned: always Sample: |
|
Any block device mapping entries for the instance. Returned: always |
|
The time stamp when the attachment initiated. Returned: always Sample: |
|
Indicates whether the volume is deleted on instance termination. Returned: always Sample: |
|
The device name exposed to the instance (for example, /dev/xvda). Returned: always Sample: |
|
The attachment state. Returned: always Sample: |
|
The ID of the cloud disk. Returned: always Sample: |
|
The CPU core count of the instance. Returned: always Sample: |
|
The time the instance was created. Returned: always Sample: |
|
The instance description. Returned: always Sample: |
|
The attribution of EIP associated with the instance. Returned: always |
|
The ID of the EIP. Returned: always Sample: |
|
The internet charge type of the EIP. Returned: always Sample: |
|
EIP address. Returned: always Sample: |
|
The time the instance will expire. Returned: always Sample: |
|
The attribution of instance GPU. Returned: always |
|
The count of the GPU. Returned: always Sample: |
|
The specification of the GPU. Returned: always Sample: |
|
The host name of the instance. Returned: always Sample: |
|
Alias of instance_id. Returned: always Sample: |
|
The ID of the image used to launch the instance. Returned: always Sample: |
|
The inner IPv4 address of the classic instance. Returned: always Sample: |
|
The instance charge type. Returned: always Sample: |
|
ECS instance resource ID. Returned: always Sample: |
|
The name of the instance. Returned: always Sample: |
|
The instance type of the running instance. Returned: always Sample: |
|
The instance type family of the instance belongs. Returned: always Sample: |
|
The billing method of the network bandwidth. Returned: always Sample: |
|
Maximum incoming bandwidth from the internet network. Returned: always Sample: |
|
Maximum incoming bandwidth from the internet network. Returned: always Sample: |
|
Indicates whether the instance is optimized for EBS I/O. Returned: always Sample: |
|
Memory size of the instance. Returned: always Sample: |
|
One or more network interfaces for the instance. Returned: always |
|
The MAC address. Returned: always Sample: |
|
The ID of the network interface. Returned: always Sample: |
|
The primary IPv4 address of the network interface within the vswitch. Returned: always Sample: |
|
The operation system name of the instance owned. Returned: always Sample: |
|
The operation system type of the instance owned. Returned: always Sample: |
|
The IPv4 address of the network interface within the subnet. Returned: always Sample: |
|
The public IPv4 address assigned to the instance or eip address Returned: always Sample: |
|
The id of the resource group to which the instance belongs. Returned: always Sample: |
|
One or more security groups for the instance. Returned: always |
|
The ID of the security group. Returned: always Sample: |
|
The name of the security group. Returned: always Sample: |
|
The maximum hourly price for the preemptible instance. Returned: always Sample: |
|
The bidding mode of the pay-as-you-go instance. Returned: always Sample: |
|
The current status of the instance. Returned: always Sample: |
|
Any tags assigned to the instance. Returned: always |
|
User-defined data. Returned: always |
|
The ID of the VPC the instance is in. Returned: always Sample: |
|
The ID of the vswitch in which the instance is running. Returned: always Sample: |
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication