Try Spottercreate, terminate, start or stop an instance in ec2
| "added in version" 0.9 of ansible.builtin"
Authors: Tim Gerla (@tgerla), Lester Wade (@lwade), Seth Vidal
stableinterface | supported by core
pipInstall with pip install ansible==2.5.10
Creates or terminates ec2 instances.
# Note: These examples do not set authentication details, see the AWS Guide for details.
# Basic provisioning example
- 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
- 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
- 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
- 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
- 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
- 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
- local_action:
module: 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
- 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
# Examples using pre-existing network interfaces
- ec2:
key_name: mykey
instance_type: t2.small
image: ami-f005ba11
network_interface: eni-deadbeef
- 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:
key_name: my_keypair
instance_type: m1.small
security_group: my_securitygroup
image: my_ami_id
region: us-east-1
tasks:
- name: Launch instance
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
with_items: "{{ ec2.instances }}"
- name: Wait for SSH to come up
wait_for:
host: "{{ item.public_dns_name }}"
port: 22
delay: 60
timeout: 320
state: started
with_items: "{{ 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
connection: local
tasks:
- name: Terminate instances that were previously launched
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
connection: local
vars:
instance_ids:
- 'i-xxxxxx'
- 'i-xxxxxx'
- 'i-xxxxxx'
region: us-east-1
tasks:
- name: Start the sandbox instances
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
connection: local
vars:
instance_ids:
- 'i-xxxxxx'
- 'i-xxxxxx'
- 'i-xxxxxx'
region: us-east-1
tasks:
- name: Stop the sandbox instances
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
#
- local_action:
module: ec2
instance_tags:
Name: ExtraPower
state: running
#
# Restart instances specified by tag
#
- local_action:
module: ec2
instance_tags:
Name: ExtraPower
state: restarted
#
# Enforce that 5 instances with a tag "foo" are running
# (Highly recommended!)
#
- 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"
#
- 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
- ec2:
count_tag:
foo:
# instances with tag foo=bar
- ec2:
count_tag:
foo: bar
# instances with tags foo=bar & baz
- ec2:
count_tag:
foo: bar
baz:
# instances with tags foo & bar & baz=bang
- ec2:
count_tag:
- foo
- bar
- baz: bang
id:
aliases: []
default: null
description:
- 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 U(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Run_Instance_Idempotency.html).
required: false
version_added: '1.1'
version_added_collection: ansible.builtin
wait:
aliases: []
choices:
- 'yes'
- 'no'
default: 'no'
description:
- wait for the instance to reach its desired state before returning. Does not wait
for SSH, see 'wait_for' example for details.
required: false
zone:
aliases:
- aws_zone
- ec2_zone
default: null
description:
- AWS availability zone in which to launch the instance
required: false
version_added: '1.2'
version_added_collection: ansible.builtin
count:
aliases: []
default: 1
description:
- number of instances to launch
required: false
group:
aliases:
- groups
default: null
description:
- security group (or list of groups) to use with the instance
required: false
image:
aliases: []
default: null
description:
- I(ami) ID to use for the instance
required: true
state:
aliases: []
choices:
- present
- absent
- running
- restarted
- stopped
default: present
description:
- create, terminate, start, stop or restart instances. The state 'restarted' was added
in 2.2
required: false
version_added: '1.3'
version_added_collection: ansible.builtin
kernel:
aliases: []
default: null
description:
- kernel I(eki) to use for the instance
required: false
region:
aliases:
- aws_region
- ec2_region
default: null
description:
- The AWS region to use. Must be specified if ec2_url is not used. If not specified
then the value of the EC2_REGION environment variable, if any, is used. See U(http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region)
required: false
version_added: '1.2'
version_added_collection: ansible.builtin
profile:
aliases:
- aws_profile
description:
- A named AWS profile to use for authentication.
- See the AWS documentation for more information about named profiles U(https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html).
- The C(AWS_PROFILE) environment variable may also be used.
- The I(profile) option is mutually exclusive with the I(aws_access_key), I(aws_secret_key)
and I(security_token) options.
type: str
ramdisk:
aliases: []
default: null
description:
- ramdisk I(eri) to use for the instance
required: false
tenancy:
aliases: []
choices:
- default
- dedicated
default: default
description:
- An instance with a tenancy of "dedicated" runs on single-tenant hardware and can
only be launched into a VPC. Note that to use dedicated tenancy you MUST specify
a vpc_subnet_id as well. Dedicated tenancy is not available for EC2 "micro" instances.
required: false
version_added: '1.9'
version_added_collection: ansible.builtin
volumes:
aliases: []
default: null
description:
- a list of hash/dictionaries of volumes to add to the new instance; '[{"key":"value",
"key":"value"}]'; keys allowed are - device_name (str; required), delete_on_termination
(bool; False), device_type (deprecated), ephemeral (str), encrypted (bool; False),
snapshot (str), volume_type (str), iops (int) - device_type is deprecated use volume_type,
iops must be set when volume_type='io1', ephemeral and snapshot are mutually exclusive.
required: false
version_added: '1.5'
version_added_collection: ansible.builtin
group_id:
aliases: []
default: null
description:
- security group id (or list of ids) to use with the instance
required: false
version_added: '1.1'
version_added_collection: ansible.builtin
key_name:
aliases:
- keypair
default: null
description:
- key pair to use on the instance
required: false
count_tag:
aliases: []
default: null
description:
- 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 "class=webserver".
The specified tag must already exist or be passed in as the 'instance_tags' option.
required: false
version_added: '1.5'
version_added_collection: ansible.builtin
spot_type:
aliases: []
choices:
- one-time
- persistent
default: one-time
description:
- Type of spot request; one of "one-time" or "persistent". Defaults to "one-time"
if not supplied.
required: false
version_added: '2.0'
version_added_collection: ansible.builtin
user_data:
aliases: []
default: null
description:
- opaque blob of data which is made available to the ec2 instance
required: false
version_added: '0.9'
version_added_collection: ansible.builtin
access_key:
aliases:
- aws_access_key_id
- aws_access_key
- ec2_access_key
description:
- AWS access key ID.
- See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
- The C(AWS_ACCESS_KEY_ID), C(AWS_ACCESS_KEY) or C(EC2_ACCESS_KEY) environment variables
may also be used in decreasing order of preference.
- The I(aws_access_key) and I(profile) options are mutually exclusive.
- The I(aws_access_key_id) alias was added in release 5.1.0 for consistency with the
AWS botocore SDK.
- The I(ec2_access_key) alias has been deprecated and will be removed in a release
after 2024-12-01.
- Support for the C(EC2_ACCESS_KEY) environment variable has been deprecated and will
be removed in a release after 2024-12-01.
type: str
aws_config:
description:
- A dictionary to modify the botocore configuration.
- Parameters can be found in the AWS documentation U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config).
type: dict
monitoring:
aliases: []
choices:
- 'yes'
- 'no'
default: false
description:
- enable detailed monitoring (CloudWatch) for instance
required: false
version_added: '1.1'
version_added_collection: ansible.builtin
private_ip:
aliases: []
default: null
description:
- the private ip address to assign the instance (from the vpc subnet)
required: false
version_added: '1.2'
version_added_collection: ansible.builtin
secret_key:
aliases:
- aws_secret_access_key
- aws_secret_key
- ec2_secret_key
description:
- AWS secret access key.
- See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
- The C(AWS_SECRET_ACCESS_KEY), C(AWS_SECRET_KEY), or C(EC2_SECRET_KEY) environment
variables may also be used in decreasing order of preference.
- The I(secret_key) and I(profile) options are mutually exclusive.
- The I(aws_secret_access_key) alias was added in release 5.1.0 for consistency with
the AWS botocore SDK.
- The I(ec2_secret_key) alias has been deprecated and will be removed in a release
after 2024-12-01.
- Support for the C(EC2_SECRET_KEY) environment variable has been deprecated and will
be removed in a release after 2024-12-01.
type: str
spot_price:
aliases: []
default: null
description:
- 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.
required: false
version_added: '1.5'
version_added_collection: ansible.builtin
exact_count:
aliases: []
default: null
description:
- 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.
required: false
version_added: '1.5'
version_added_collection: ansible.builtin
endpoint_url:
aliases:
- ec2_url
- aws_endpoint_url
- s3_url
description:
- URL to connect to instead of the default AWS endpoints. While this can be used
to connection to other AWS-compatible services the amazon.aws and community.aws
collections are only tested against AWS.
- The C(AWS_URL) or C(EC2_URL) environment variables may also be used, in decreasing
order of preference.
- The I(ec2_url) and I(s3_url) aliases have been deprecated and will be removed in
a release after 2024-12-01.
- Support for the C(EC2_URL) environment variable has been deprecated and will be
removed in a release after 2024-12-01.
type: str
instance_ids:
aliases:
- instance_id
default: null
description:
- 'list of instance ids, currently used for states: absent, running, stopped'
required: false
version_added: '1.3'
version_added_collection: ansible.builtin
wait_timeout:
aliases: []
default: 300
description:
- how long before wait gives up, in seconds
aws_ca_bundle:
description:
- The location of a CA Bundle to use when validating SSL certificates.
- The C(AWS_CA_BUNDLE) environment variable may also be used.
type: path
ebs_optimized:
default: 'false'
description:
- whether instance is using optimized EBS volumes, see U(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html)
required: false
version_added: '1.6'
version_added_collection: ansible.builtin
instance_tags:
aliases: []
default: null
description:
- a hash/dictionary of tags to add to the new instance or for starting/stopping instance
by tag; '{"key":"value"}' and '{"key":"value","key":"value"}'
required: false
version_added: '1.0'
version_added_collection: ansible.builtin
instance_type:
aliases: []
default: null
description:
- instance type to use for the instance, see U(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html)
required: true
session_token:
aliases:
- aws_session_token
- security_token
- aws_security_token
- access_token
description:
- AWS STS session token for use with temporary credentials.
- See the AWS documentation for more information about access tokens U(https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
- The C(AWS_SESSION_TOKEN), C(AWS_SECURITY_TOKEN) or C(EC2_SECURITY_TOKEN) environment
variables may also be used in decreasing order of preference.
- The I(security_token) and I(profile) options are mutually exclusive.
- Aliases I(aws_session_token) and I(session_token) were added in release 3.2.0, with
the parameter being renamed from I(security_token) to I(session_token) in release
6.0.0.
- The I(security_token), I(aws_security_token), and I(access_token) aliases have been
deprecated and will be removed in a release after 2024-12-01.
- Support for the C(EC2_SECRET_KEY) and C(AWS_SECURITY_TOKEN) environment variables
has been deprecated and will be removed in a release after 2024-12-01.
type: str
vpc_subnet_id:
aliases: []
default: null
description:
- the subnet ID in which to launch the instance (VPC)
required: false
version_added: '1.1'
version_added_collection: ansible.builtin
validate_certs:
default: true
description:
- When set to C(false), SSL certificates will not be validated for communication with
the AWS APIs.
- Setting I(validate_certs=false) is strongly discouraged, as an alternative, consider
setting I(aws_ca_bundle) instead.
type: bool
placement_group:
aliases: []
default: null
description:
- placement group for the instance when using EC2 Clustered Compute
required: false
version_added: '1.3'
version_added_collection: ansible.builtin
assign_public_ip:
aliases: []
choices:
- 'yes'
- 'no'
default: false
description:
- when provisioning within vpc, assign a public IP address. Boto library must be 2.13.0+
required: false
version_added: '1.5'
version_added_collection: ansible.builtin
source_dest_check:
choices:
- 'yes'
- 'no'
default: true
description:
- Enable or Disable the Source/Destination checks (for NAT instances and Virtual Routers)
required: false
version_added: '1.6'
version_added_collection: ansible.builtin
spot_launch_group:
default: null
description:
- Launch group for spot request, see U(http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/how-spot-instances-work.html#spot-launch-group)
required: false
version_added: '2.1'
version_added_collection: ansible.builtin
spot_wait_timeout:
aliases: []
default: 600
description:
- how long to wait for the spot instance request to be fulfilled
version_added: '1.5'
version_added_collection: ansible.builtin
network_interfaces:
aliases:
- network_interface
default: null
description:
- 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.)
required: false
version_added: '2.0'
version_added_collection: ansible.builtin
instance_profile_name:
aliases: []
default: null
description:
- Name of the IAM instance profile to use. Boto library must be 2.5.0+
required: false
version_added: '1.3'
version_added_collection: ansible.builtin
termination_protection:
choices:
- 'yes'
- 'no'
default: false
description:
- Enable or Disable the Termination Protection
required: false
version_added: '2.0'
version_added_collection: ansible.builtin
debug_botocore_endpoint_logs:
default: false
description:
- Use a C(botocore.endpoint) logger to parse the unique (rather than total) C("resource:action")
API calls made during a task, outputing the set to the resource_actions key in the
task results. Use the C(aws_resource_action) callback to output to total list made
during a playbook.
- The C(ANSIBLE_DEBUG_BOTOCORE_LOGS) environment variable may also be used.
type: bool
instance_initiated_shutdown_behavior:
choices:
- stop
- terminate
default: stop
description:
- 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).
required: false
version_added: '2.2'
version_added_collection: ansible.builtin