amazon.aws.ec2 – create, terminate, start or stop an instance in ec2

Note

This plugin is part of the amazon.aws collection (version 1.5.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 amazon.aws.

To use it in a playbook, specify: amazon.aws.ec2.

New in version 1.0.0: of amazon.aws

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.

  • python >= 2.6

  • boto

Parameters

Parameter

Comments

assign_public_ip

boolean

When provisioning within vpc, assign a public IP address. Boto library must be 2.13.0+.

Choices:

  • no

  • yes

aws_access_key

aliases: ec2_access_key, access_key

string

AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variable is used.

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.

aws_ca_bundle

path

The location of a CA Bundle to use when validating SSL certificates.

Only used for boto3 based modules.

Note: The CA Bundle is read ‘module’ side and may need to be explicitly copied from the controller if not run locally.

aws_config

dictionary

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.

aws_secret_key

aliases: ec2_secret_key, secret_key

string

AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variable is used.

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.

count

integer

Number of instances to launch.

Default: 1

count_tag

raw

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.

debug_botocore_endpoint_logs

boolean

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:

  • no ← (default)

  • yes

ebs_optimized

boolean

Whether instance is using optimized EBS volumes, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html.

Choices:

  • no ← (default)

  • yes

ec2_url

aliases: aws_endpoint_url, endpoint_url

string

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.

exact_count

integer

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.

group

aliases: groups

list / elements=string

Security group (or list of groups) to use with the instance.

group_id

list / elements=string

Security group id (or list of ids) to use with the instance.

id

string

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.

image

string

ami ID to use for the instance.

Required when state=present.

instance_ids

aliases: instance_id

list / elements=string

list of instance ids, currently used for states: absent, running, stopped

instance_initiated_shutdown_behavior

string

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:

  • stop ← (default)

  • terminate

instance_profile_name

string

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+.

instance_tags

dictionary

A hash/dictionary of tags to add to the new instance or for instances to start/stop by tag. For example {"key":"value"} or {"key":"value","key2":"value2"}.

instance_type

aliases: type

string

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

string

Kernel eki to use for the instance.

key_name

aliases: keypair

string

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.

monitoring

boolean

Enable detailed monitoring (CloudWatch) for the instance.

Choices:

  • no ← (default)

  • yes

network_interfaces

aliases: network_interface

list / elements=string

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

string

Placement group for the instance when using EC2 Clustered Compute.

private_ip

string

The private ip address to assign the instance (from the vpc subnet).

profile

aliases: aws_profile

string

Uses a boto profile. Only works with boto >= 2.24.0.

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

string

Ramdisk eri to use for the instance.

region

aliases: aws_region, ec2_region

string

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

security_token

aliases: aws_security_token, access_token

string

AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variable is used.

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.

source_dest_check

boolean

Enable or Disable the Source/Destination checks (for NAT instances and Virtual Routers). When initially creating an instance the EC2 API defaults this to True.

Choices:

  • no

  • yes

spot_launch_group

string

spot_price

string

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.

spot_type

string

The type of spot request.

After being interrupted a persistent spot instance will be started once there is capacity to fill the request again.

Choices:

  • one-time ← (default)

  • persistent

spot_wait_timeout

integer

How long to wait for the spot instance request to be fulfilled. Affects ‘Request valid until’ for setting spot request lifespan.

Default: 600

state

string

Create, terminate, start, stop or restart instances. The state ‘restarted’ was added in Ansible 2.2.

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:

  • absent

  • present ← (default)

  • restarted

  • running

  • stopped

tenancy

string

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.

Choices:

  • default ← (default)

  • dedicated

termination_protection

boolean

Enable or Disable the Termination Protection.

Defaults to false.

Choices:

  • no

  • yes

user_data

string

Opaque blob of data which is made available to the EC2 instance.

validate_certs

boolean

When set to “no”, SSL certificates will not be validated for boto versions >= 2.6.0.

Choices:

  • no

  • yes ← (default)

volumes

list / elements=dictionary

A list of hash/dictionaries of volumes to add to the new instance.

delete_on_termination

boolean

Whether the volume should be automatically deleted when the instance is terminated.

Choices:

  • no ← (default)

  • yes

device_name

string / required

A name for the device (For example /dev/sda).

encrypted

boolean

Whether the volume should be encrypted using the ‘aws/ebs’ KMS CMK.

Choices:

  • no ← (default)

  • yes

ephemeral

string

Whether the volume should be ephemeral.

Data on ephemeral volumes is lost when the instance is stopped.

Mutually exclusive with the snapshot parameter.

iops

integer

The number of IOPS per second to provision for the volume.

Required when volume_type=io1.

snapshot

string

The ID of an EBS snapshot to copy when creating the volume.

Mutually exclusive with the ephemeral parameter.

volume_size

integer

The size of the volume (in GiB).

volume_type

string

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.

vpc_subnet_id

string

The subnet ID in which to launch the instance (VPC).

wait

boolean

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:

  • no ← (default)

  • yes

wait_timeout

integer

How long before wait gives up, in seconds.

Default: 300

zone

aliases: aws_zone, ec2_zone

string

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_URL or EC2_URL, AWS_PROFILE or AWS_DEFAULT_PROFILE, AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY or EC2_ACCESS_KEY, AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY or EC2_SECRET_KEY, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN, AWS_REGION or EC2_REGION, AWS_CA_BUNDLE

  • Ansible uses the boto configuration file (typically ~/.boto) if no credentials are provided. See https://boto.readthedocs.io/en/latest/boto_config_tut.html

  • AWS_REGION or EC2_REGION can be typically be used to specify the AWS region, when required, but this can also be configured in the boto config file

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

Authors

  • Tim Gerla (@tgerla)

  • Lester Wade (@lwade)

  • Seth Vidal (@skvidal)