amazon.aws.ec2 module – create, terminate, start or stop an instance in ec2
Note
This module is part of the amazon.aws collection (version 3.5.0).
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 amazon.aws.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: amazon.aws.ec2.
New in amazon.aws 1.0.0
DEPRECATED
- Removed in:
version 4.0.0
- Why:
The ec2 module is based upon a deprecated version of the AWS SDK.
- Alternative:
Synopsis
Creates or terminates ec2 instances.
Note: This module uses the older boto Python module to interact with the EC2 API. amazon.aws.ec2 will still receive bug fixes, but no new features. Consider using the amazon.aws.ec2_instance module instead. If amazon.aws.ec2_instance does not support a feature you need that is available in amazon.aws.ec2, please file a feature request.
Requirements
The below requirements are needed on the host that executes this module.
boto
boto3 >= 1.16.0
botocore >= 1.19.0
python >= 2.6
python >= 3.6
Parameters
Parameter |
Comments |
|---|---|
When provisioning within vpc, assign a public IP address. Boto library must be 2.13.0+. Choices:
|
|
If profile is set this parameter is ignored. Passing the aws_access_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. |
|
The location of a CA Bundle to use when validating SSL certificates. Not used by boto 2 based modules. Note: The CA Bundle is read ‘module’ side and may need to be explicitly copied from the controller if not run locally. |
|
A dictionary to modify the botocore configuration. Parameters can be found at https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config. Only the ‘user_agent’ key is used for boto modules. See http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto for more boto configuration. |
|
If profile is set this parameter is ignored. Passing the aws_secret_key and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. |
|
Number of instances to launch. Default: |
|
Used with exact_count to determine how many nodes based on a specific tag criteria should be running. This can be expressed in multiple ways and is shown in the EXAMPLES section. For instance, one can request 25 servers that are tagged with |
|
Use a botocore.endpoint logger to parse the unique (rather than total) “resource:action” API calls made during a task, outputing the set to the resource_actions key in the task results. Use the aws_resource_action callback to output to total list made during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also be used. Choices:
|
|
Whether instance is using optimized EBS volumes, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html. Choices:
|
|
URL to use to connect to EC2 or your Eucalyptus cloud (by default the module will use EC2 endpoints). Ignored for modules where region is required. Must be specified for all other modules if region is not used. If not set then the value of the EC2_URL environment variable, if any, is used. |
|
An integer value which indicates how many instances that match the ‘count_tag’ parameter should be running. Instances are either created or terminated based on this value. |
|
Security group (or list of groups) to use with the instance. |
|
Security group id (or list of ids) to use with the instance. |
|
Identifier for this instance or set of instances, so that the module will be idempotent with respect to EC2 instances. This identifier is valid for at least 24 hours after the termination of the instance, and should not be reused for another call later on. For details, see the description of client token at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html. |
|
ami ID to use for the instance. Required when state=present. |
|
list of instance ids, currently used for states: absent, running, stopped |
|
Set whether AWS will Stop or Terminate an instance on shutdown. This parameter is ignored when using instance-store. images (which require termination on shutdown). Choices:
|
|
Name of the IAM instance profile (i.e. what the EC2 console refers to as an “IAM Role”) to use. Boto library must be 2.5.0+. |
|
A hash/dictionary of tags to add to the new instance or for instances to start/stop by tag. For example |
|
Instance type to use for the instance, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html. Required when creating a new instance. |
|
Kernel eki to use for the instance. |
|
Key pair to use on the instance. The SSH key must already exist in AWS in order to use this argument. Keys can be created / deleted using the amazon.aws.ec2_key module. |
|
Enable detailed monitoring (CloudWatch) for the instance. Choices:
|
|
A list of existing network interfaces to attach to the instance at launch. When specifying existing network interfaces, none of the assign_public_ip, private_ip, vpc_subnet_id, group, or group_id parameters may be used. (Those parameters are for creating a new network interface at launch.) |
|
Placement group for the instance when using EC2 Clustered Compute. |
|
The private ip address to assign the instance (from the vpc subnet). |
|
Using profile will override aws_access_key, aws_secret_key and security_token and support for passing them at the same time as profile has been deprecated. aws_access_key, aws_secret_key and security_token will be made mutually exclusive with profile after 2022-06-01. |
|
Ramdisk eri to use for the instance. |
|
The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION environment variable, if any, is used. See http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region |
|
If profile is set this parameter is ignored. Passing the security_token and profile options at the same time has been deprecated and the options will be made mutually exclusive after 2022-06-01. Aliases aws_session_token and session_token have been added in version 3.2.0. |
|
Enable or Disable the Source/Destination checks (for NAT instances and Virtual Routers). When initially creating an instance the EC2 API defaults this to Choices:
|
|
Launch group for spot requests, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group. |
|
Maximum spot price to bid. If not set, a regular on-demand instance is requested. A spot request is made with this maximum bid. When it is filled, the instance is started. |
|
The type of spot request. After being interrupted a Choices:
|
|
How long to wait for the spot instance request to be fulfilled. Affects ‘Request valid until’ for setting spot request lifespan. Default: |
|
Create, terminate, start, stop or restart instances. When state=absent, instance_ids is required. When state=running, state=stopped or state=restarted then either instance_ids or instance_tags is required. Choices:
|
|
An instance with a tenancy of Note that to use dedicated tenancy you MUST specify a vpc_subnet_id as well. Dedicated tenancy is not available for EC2 “micro” instances. Choices:
|
|
Enable or Disable the Termination Protection. Defaults to Choices:
|
|
Opaque blob of data which is made available to the EC2 instance. |
|
When set to “no”, SSL certificates will not be validated for communication with the AWS APIs. Choices:
|
|
A list of hash/dictionaries of volumes to add to the new instance. |
|
Whether the volume should be automatically deleted when the instance is terminated. Choices:
|
|
A name for the device (For example |
|
Whether the volume should be encrypted using the ‘aws/ebs’ KMS CMK. Choices:
|
|
Whether the volume should be ephemeral. Data on ephemeral volumes is lost when the instance is stopped. Mutually exclusive with the snapshot parameter. |
|
The number of IOPS per second to provision for the volume. Required when volume_type=io1. |
|
The ID of an EBS snapshot to copy when creating the volume. Mutually exclusive with the ephemeral parameter. |
|
The size of the volume (in GiB). |
|
The type of volume to create. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumeTypes.html for more information on the available volume types. |
|
The subnet ID in which to launch the instance (VPC). |
|
Wait for the instance to reach its desired state before returning. Does not wait for SSH, see the ‘wait_for_connection’ example for details. Choices:
|
|
How long before wait gives up, in seconds. Default: |
|
AWS availability zone in which to launch the instance. |
Notes
Note
If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence
AWS_URLorEC2_URL,AWS_PROFILEorAWS_DEFAULT_PROFILE,AWS_ACCESS_KEY_IDorAWS_ACCESS_KEYorEC2_ACCESS_KEY,AWS_SECRET_ACCESS_KEYorAWS_SECRET_KEYorEC2_SECRET_KEY,AWS_SECURITY_TOKENorEC2_SECURITY_TOKEN,AWS_REGIONorEC2_REGION,AWS_CA_BUNDLEWhen no credentials are explicitly provided the AWS SDK (boto3) that Ansible uses will fall back to its configuration files (typically
~/.aws/credentials). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.Modules based on the original AWS SDK (boto) may read their default configuration from different files. See https://boto.readthedocs.io/en/latest/boto_config_tut.html for more information.
AWS_REGIONorEC2_REGIONcan be typically be used to specify the AWS region, when required, but this can also be defined in the configuration files.
Examples
# Note: These examples do not set authentication details, see the AWS Guide for details.
# Basic provisioning example
- amazon.aws.ec2:
key_name: mykey
instance_type: t2.micro
image: ami-123456
wait: yes
group: webserver
count: 3
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
# Advanced example with tagging and CloudWatch
- amazon.aws.ec2:
key_name: mykey
group: databases
instance_type: t2.micro
image: ami-123456
wait: yes
wait_timeout: 500
count: 5
instance_tags:
db: postgres
monitoring: yes
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
# Single instance with additional IOPS volume from snapshot and volume delete on termination
- amazon.aws.ec2:
key_name: mykey
group: webserver
instance_type: c3.medium
image: ami-123456
wait: yes
wait_timeout: 500
volumes:
- device_name: /dev/sdb
snapshot: snap-abcdef12
volume_type: io1
iops: 1000
volume_size: 100
delete_on_termination: true
monitoring: yes
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
# Single instance with ssd gp2 root volume
- amazon.aws.ec2:
key_name: mykey
group: webserver
instance_type: c3.medium
image: ami-123456
wait: yes
wait_timeout: 500
volumes:
- device_name: /dev/xvda
volume_type: gp2
volume_size: 8
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
count_tag:
Name: dbserver
exact_count: 1
# Multiple groups example
- amazon.aws.ec2:
key_name: mykey
group: ['databases', 'internal-services', 'sshable', 'and-so-forth']
instance_type: m1.large
image: ami-6e649707
wait: yes
wait_timeout: 500
count: 5
instance_tags:
db: postgres
monitoring: yes
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
# Multiple instances with additional volume from snapshot
- amazon.aws.ec2:
key_name: mykey
group: webserver
instance_type: m1.large
image: ami-6e649707
wait: yes
wait_timeout: 500
count: 5
volumes:
- device_name: /dev/sdb
snapshot: snap-abcdef12
volume_size: 10
monitoring: yes
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
# Dedicated tenancy example
- amazon.aws.ec2:
assign_public_ip: yes
group_id: sg-1dc53f72
key_name: mykey
image: ami-6e649707
instance_type: m1.small
tenancy: dedicated
vpc_subnet_id: subnet-29e63245
wait: yes
# Spot instance example
- amazon.aws.ec2:
spot_price: 0.24
spot_wait_timeout: 600
keypair: mykey
group_id: sg-1dc53f72
instance_type: m1.small
image: ami-6e649707
wait: yes
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
spot_launch_group: report_generators
instance_initiated_shutdown_behavior: terminate
# Examples using pre-existing network interfaces
- amazon.aws.ec2:
key_name: mykey
instance_type: t2.small
image: ami-f005ba11
network_interface: eni-deadbeef
- amazon.aws.ec2:
key_name: mykey
instance_type: t2.small
image: ami-f005ba11
network_interfaces: ['eni-deadbeef', 'eni-5ca1ab1e']
# Launch instances, runs some tasks
# and then terminate them
- name: Create a sandbox instance
hosts: localhost
gather_facts: False
vars:
keypair: my_keypair
instance_type: m1.small
security_group: my_securitygroup
image: my_ami_id
region: us-east-1
tasks:
- name: Launch instance
amazon.aws.ec2:
key_name: "{{ keypair }}"
group: "{{ security_group }}"
instance_type: "{{ instance_type }}"
image: "{{ image }}"
wait: true
region: "{{ region }}"
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
register: ec2
- name: Add new instance to host group
add_host:
hostname: "{{ item.public_ip }}"
groupname: launched
loop: "{{ ec2.instances }}"
- name: Wait for SSH to come up
delegate_to: "{{ item.public_dns_name }}"
wait_for_connection:
delay: 60
timeout: 320
loop: "{{ ec2.instances }}"
- name: Configure instance(s)
hosts: launched
become: True
gather_facts: True
roles:
- my_awesome_role
- my_awesome_test
- name: Terminate instances
hosts: localhost
tasks:
- name: Terminate instances that were previously launched
amazon.aws.ec2:
state: 'absent'
instance_ids: '{{ ec2.instance_ids }}'
# Start a few existing instances, run some tasks
# and stop the instances
- name: Start sandbox instances
hosts: localhost
gather_facts: false
vars:
instance_ids:
- 'i-xxxxxx'
- 'i-xxxxxx'
- 'i-xxxxxx'
region: us-east-1
tasks:
- name: Start the sandbox instances
amazon.aws.ec2:
instance_ids: '{{ instance_ids }}'
region: '{{ region }}'
state: running
wait: True
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
roles:
- do_neat_stuff
- do_more_neat_stuff
- name: Stop sandbox instances
hosts: localhost
gather_facts: false
vars:
instance_ids:
- 'i-xxxxxx'
- 'i-xxxxxx'
- 'i-xxxxxx'
region: us-east-1
tasks:
- name: Stop the sandbox instances
amazon.aws.ec2:
instance_ids: '{{ instance_ids }}'
region: '{{ region }}'
state: stopped
wait: True
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
#
# Start stopped instances specified by tag
#
- amazon.aws.ec2:
instance_tags:
Name: ExtraPower
state: running
#
# Restart instances specified by tag
#
- amazon.aws.ec2:
instance_tags:
Name: ExtraPower
state: restarted
#
# Enforce that 5 instances with a tag "foo" are running
# (Highly recommended!)
#
- amazon.aws.ec2:
key_name: mykey
instance_type: c1.medium
image: ami-40603AD1
wait: yes
group: webserver
instance_tags:
foo: bar
exact_count: 5
count_tag: foo
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
#
# Enforce that 5 running instances named "database" with a "dbtype" of "postgres"
#
- amazon.aws.ec2:
key_name: mykey
instance_type: c1.medium
image: ami-40603AD1
wait: yes
group: webserver
instance_tags:
Name: database
dbtype: postgres
exact_count: 5
count_tag:
Name: database
dbtype: postgres
vpc_subnet_id: subnet-29e63245
assign_public_ip: yes
#
# count_tag complex argument examples
#
# instances with tag foo
- amazon.aws.ec2:
count_tag:
foo:
# instances with tag foo=bar
- amazon.aws.ec2:
count_tag:
foo: bar
# instances with tags foo=bar & baz
- amazon.aws.ec2:
count_tag:
foo: bar
baz:
# instances with tags foo & bar & baz=bang
- amazon.aws.ec2:
count_tag:
- foo
- bar
- baz: bang
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
If the EC2 instance has changed. Returned: always Sample: |
|
The instances. Returned: always |
|
The AMI launch index, which can be used to find this instance in the launch group. Returned: always Sample: |
|
The architecture of the image. Returned: always Sample: |
|
Any block device mapping entries for the instance. Returned: always Sample: |
|
Information about the Capacity Reservation targeting option. Returned: always Sample: |
|
The idempotency token you provided when you launched the instance, if applicable. Returned: always Sample: |
|
The CPU options for the instance. Returned: always Sample: |
|
The public DNS name assigned to the instance. Returned: always Sample: |
|
Indicates whether the instance is optimized for Amazon EBS I/O. Returned: always Sample: |
|
Specifies whether enhanced networking with ENA is enabled. Returned: always Sample: |
|
Indicates whether the instance is enabled for AWS Nitro Enclaves. Returned: always Sample: |
|
One or more security groups. Returned: always Sample: |
|
Indicates whether the instance is enabled for hibernation. Returned: always Sample: |
|
The hypervisor type of the instance. Returned: always Sample: |
|
The ID of the AMI used to launch the instance. Returned: always Sample: |
|
The ID of the instance. Returned: always Sample: |
|
The instance type. Returned: always Sample: |
|
The kernel associated with this instance, if applicable. Returned: always Sample: |
|
The name of the key pair, if this instance was launched with an associated key pair. Returned: always Sample: |
|
The time the instance was launched. Returned: always Sample: |
|
The metadata options for the instance. Returned: always Sample: |
|
The monitoring for the instance. Returned: always Sample: |
|
The network interfaces for the instance. Returned: always Sample: |
|
The location where the instance launched, if applicable. Returned: always Sample: |
|
The private DNS hostname name assigned to the instance. Returned: always Sample: |
|
The private IPv4 address assigned to the instance. Returned: always Sample: |
|
The public DNS name assigned to the instance. Returned: always Sample: |
|
The public IPv4 address, or the Carrier IP address assigned to the instance, if applicable. Returned: always Sample: |
|
The RAM disk associated with this instance, if applicable. Returned: always Sample: |
|
The device name of the root device volume. Returned: always Sample: |
|
The root device type used by the AMI. Returned: always Sample: |
|
The security groups for the instance. Returned: always Sample: |
|
Indicates whether source/destination checking is enabled. Returned: always Sample: |
|
The current state of the instance. Returned: always Sample: |
|
The reason for the most recent state transition. Returned: always Sample: |
|
The reason for the most recent state transition. This might be an empty string. Returned: always Sample: |
|
The ID of the subnet in which the instance is running. Returned: always Sample: |
|
Any tags assigned to the instance. Returned: always Sample: |
|
The tenancy of the instance (if the instance is running in a VPC). Returned: always Sample: |
|
The virtualization type of the instance. Returned: always Sample: |
|
The ID of the VPC in which the instance is running. Returned: always Sample: |
Status
This module will be removed in version 4.0.0. [deprecated]
For more information see DEPRECATED.