ec2_instance – Manage EC2 instances

Create, update or delete an AWS EC2 instance.

Examples

- name: Launch an EC2 instance in a specific subnet
  ec2_instance:
    name: first-instance
    type: a1.medium
    ami: ami-0343ab73df9eb1496
    key_pair: my-keypair
    subnet: subnet-870717cd
  register: my_instance

- name: Update EC2 instance configuration
  ec2_instance:
    id: "{{ my_instance.object.id }}"
    on_instance_initiated_shutdown: terminate
    monitoring: detailed

- name: Launch another EC2 instance
  ec2_instance:
    name: second-instance
    type: t2.micro
    ami: ami-0343ab73df9eb1496
    key_pair: my-keypair
    network_interface: eni-2j66sa32jfs2f2d
    tags:
      env: staging

- name: Terminate an EC2 instance
  ec2_instance:
    id: "{{ my_instance.object.id }}"
    state: absent

See Also

See also

• ec2_instance_info – List EC2 instances

• ec2_network_interface – Manage EC2 Elastic Network Interfaces

Parameters

ami (optional)

ID of the Amazon Machine Image used to launch the instance.

This parameter is required when creating a new instance.

In the absence of id and network_interface, the value of this parameter will be used in conjunction with name and subnet to identify the instance.

type: str

auth (optional)

Parameters for authenticating with the AWS service. Each of them may be defined via environment variables.

type: dict

access_key (optional)

The AWS access key ID. If not set, the value of the AWS_ACCESS_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str

profile (optional)

The name of the AWS profile configured with aws configure.

Can be used instead of explicitly specifying your access credentials and region.

Use default to use the default profile.

Mutually exclusive with access_key and secret_key.

type: str

region (optional)

The name of the AWS region.

If not set, the value of the AWS_REGION environment variable will be checked.

If you set a profile that specifies a default region, that region is used and you can omit this parameter. Use this parameter to override the profile’s default region.

type: str

secret_key (optional)

The AWS secret access key. If not set, the value of the AWS_SECRET_KEY environment variable will be checked.

Mutually exclusive with profile.

type: str

url (optional)

The URL to the AWS service related to the resource. By default, this is automatically determined through the region parameter.

If not set explicitly, the value of the AWS_<SERVICE>_URL environment variable will be used.

The services currently supported are EC2 and S3.

type: str

availability_zone (optional)

ID of the availability zone in which to create the instance.

This parameter is required when creating an instance if neither subnet nor network_interface are specified.

If subnet is provided, this parameter is ignored.

If id is not provided, at least one of subnet, availability_zone is required.

type: str

clear_tags (optional)

Whether to clear any existing tags on the resource that are not explicitly stated in tags.

By default, existing tags are kept on the resource.

When this parameter is set to true, any pre-existing tags on the resource (including the name tag) are removed. To clear all tags except the name tag, make sure to provide the name parameter.

type: bool

id (optional)

ID of the resource to perform the task on.

If specified, this parameter is used to identify the resource.

Omit this parameter when you are first creating the resource.

type: str

key_pair (optional)

Name of the key pair to be used when connecting to the instance.

This parameter is required when creating an instance.

type: str

monitoring (optional)

CloudWatch monitoring mode for the instance.

If you omit this parameter when creating a new instance, the default value basic will be used.

type: str

choices: basic, detailed

name (optional)

Name tag for the EC2 instance.

This parameter is required when creating a new instance.

In the absence of id and network_interface, the value of this parameter will be used in conjunction with ami and subnet to identify the instance.

type: str

network_interface (optional)

ID of an existing ENI to attach to the instance as the primary network interface (at device index 0).

This parameter is required when creating an instance if you don’t provide subnet or availability_zone. If network_interface points to an ENI that is already attached as a primary network interface for an instance, the module uses it to uniquely identify the instance.

If this parameter is provided, the instance will be created in the subnet of the network interface.

If this parameter is omitted when creating an instance, a default primary network interface will be automatically created and attached, and you can optionally set security_groups to configure it.

Note that the network_interface cannot be modified after instance is launched. Use steampunk.aws.ec2_network_interface to attach any additional ENIs to the instance.

This parameter is mutually exclusive with security_groups, subnet and availability_zone.

type: str

on_instance_initiated_shutdown (optional)

Default behavior for instance-initiated shutdown.

If you omit this parameter when creating a new instance, the default value stop will be used.

type: str

choices: stop, terminate

security_groups (optional)

IDs of security groups that will be associated with the default primary network interface.

If omitted, the VPC’s default security group will be used.

Use this parameter if you wish to configure the default primary network interface that will be created automatically when a new instance is launched.

To modify security groups of the default network interface created for you on instance launch, use steampunk.aws.ec2_network_interface.

This parameter is mutually exclusive with network_interface.

type: list

state (optional)

The desired state of the EC2 instance.

When creating a new instance, the default behavior of the module is to wait until the instance is in running state on AWS. Set wait_state to false to modify this behavior.

Note that terminated instances are treated as absent.

type: str

default: present

choices: present, absent

subnet (optional)

ID of the subnet where the instance will be launched from.

This parameter is required when creating an instance if neither availability_zone nor network_interface are specified.

If omitted, the instance will be created in the default subnet for the availability zone specified in availability_zone of the default VPC for auth.region.

type: str

tags (optional)

Metadata for the AWS resource as key/value pairs.

Keys and values are case-sensitive.

type: dict

tenancy (optional)

The instance tenancy setting.

If omitted, the VPC’s default instance tenancy setting will be used.

You cannot modify this setting after an instance is launched.

type: str

choices: default, dedicated

type (optional)

Type of the EC2 instance.

This parameter is required when creating a new instance.

Currently it is not possible to modify the instance type after an instance is launched.

type: str

wait_state (optional)

Whether the module should wait (block) until state is reached.

For newly created instances - if state is present and this parameter is set, the module ensures a running instance. Otherwise it ensures an instance that exists on AWS, but is not necessarily in running state.

Note that this parameter has no effect when you’re updating an existing instance.

If state is absent and this parameter is set, the module initiates instance termination and continues. Otherwise it waits until the instance is terminated.

type: bool

default: True

Return Values

object (success and I(state)=C(present)), complex,

An object representing the EC2 Instance.

id (always), str, i-841b9271gd

ID of the EC2 instance.

launched_at (always), str, 2020-04-15T08:08:40+00:00

The time when instance was launched.

type (always), str, a1.xsmall

EC2 instance type.

ami (always), str, ami-0343ab73df9eb1496

ID of the AMI used to launched the instance.

vpc (always), str, vpc-129385ns2s2

ID of the VPC containing the instance.

subnet (always), str, subnet-14hs85ns83hg

ID of the subnet containing the instance.

availability_zone (always), str, az-use-1

ID of the availability zone for the instance.

security_groups (always), list, [‘sg-27fhs72gs922f’]

IDs of security groups associated with the instance.

network_interface (always), str, eni-2dfr38df335

ID of the instance’s primary network interface.

secondary_network_interfaces (always), list, []

IDs of the secondary network interfaces attached to the instance.

key_pair (always), str, my-key-pair

Name of the key pair to be used when connecting to the instance.

tenancy (always), str, default

The instance tenancy setting.

monitoring (always), str, detailed

CloudWatch monitoring mode for the instance.

on_instance_initiated_shutdown (always), str, terminate

The behavior when shut down is initiated from the instance.

state (always), str, running

State of the EC2 instance as reported by AWS.