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 2.5.1).
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
|
|
Whether allocate a public ip for the new instance.
aliases: assign_public_ip |
|
auto_renew
boolean
|
|
Whether automate renew the charge of the instance.
|
|
auto_renew_period
integer
|
|
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
|
|
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
|
|
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
|
|
Whether to change instance disks charge type when changing instance charge type.
|
|
instance_charge_type
string
|
|
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
|
|
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
|
|
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
|
|
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
|
|
The bidding mode of the pay-as-you-go instance. This parameter is valid when InstanceChargeType is set to PostPaid.
|
|
state
string
|
|
The state of the instance after operating.
|
|
system_disk_category
string
|
|
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
|
|
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_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:
Authors¶
He Guimin (@xiaozhu36)