amazon.aws.ec2_instance module – Create & manage EC2 instances

Note

This module is part of the amazon.aws collection (version 9.1.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_instance.

New in amazon.aws 1.0.0

Synopsis

• Create and manage AWS EC2 instances.

• This module does not support creating EC2 Spot instances.

• The amazon.aws.ec2_spot_instance module can create and manage spot instances.

Requirements

The below requirements are needed on the host that executes this module.

• python >= 3.6

• boto3 >= 1.28.0

• botocore >= 1.31.0

Parameters

Parameter	Comments
aap_callback aliases: tower_callback dictionary	Preconfigured user-data to enable an instance to perform an Ansible Automation Platform callback (Linux only). For Windows instances, to enable remote access via Ansible set aap_callback.windows to true, and optionally set an admin password. If using aap_callback.windows and aap_callback.set_password, callback to Ansible Automation Platform will not be performed but the instance will be ready to receive winrm connections from Ansible. Mutually exclusive with user_data.
host_config_key string	Host configuration secret key generated by the Tower job template. Required if aap_callback.windows=False.
job_template_id string	Either the integer ID of the Tower Job Template, or the name. Using a name for the job template is not supported by Ansible Tower prior to version 3.2. Required if aap_callback.windows=False.
set_password string	Optional admin password to use if aap_callback.windows=True.
tower_address string	IP address or DNS name of Tower server. Must be accessible via this address from the VPC that this instance will be launched in. Required if aap_callback.windows=False.
windows boolean	Set aap_callback.windows=True to use powershell instead of bash for the callback script. Choices: false ← (default) true
access_key aliases: aws_access_key_id, aws_access_key, ec2_access_key string	AWS access key ID. See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. The AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or EC2_ACCESS_KEY environment variables may also be used in decreasing order of preference. The aws_access_key and profile options are mutually exclusive. The aws_access_key_id alias was added in release 5.1.0 for consistency with the AWS botocore SDK. The ec2_access_key alias has been deprecated and will be removed in a release after 2024-12-01. Support for the EC2_ACCESS_KEY environment variable has been deprecated and will be removed in a release after 2024-12-01.
additional_info string added in amazon.aws 7.1.0	Reserved for Amazon’s internal use.
availability_zone string	Specify an availability zone to use the default subnet it. Useful if not specifying the vpc_subnet_id parameter. If no subnet, ENI, or availability zone is provided, the default subnet in the default VPC will be used in the first AZ (alphabetically sorted).
aws_ca_bundle path	The location of a CA Bundle to use when validating SSL certificates. The AWS_CA_BUNDLE environment variable may also be used.
aws_config dictionary	A dictionary to modify the botocore configuration. Parameters can be found in the AWS documentation https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config.
count integer added in amazon.aws 2.2.0	Number of instances to launch. Setting this value will result in always launching new instances. Mutually exclusive with exact_count.
cpu_credit_specification string	For T series instances, choose whether to allow increased charges to buy CPU credits if the default pool is depleted. Choose unlimited to enable buying additional CPU credits. Choices: "unlimited" "standard"
cpu_options dictionary	Reduce the number of vCPU exposed to the instance. Those parameters can only be set at instance launch. The two suboptions cpu_options.threads_per_core and cpu_options.core_count are mandatory. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html for combinations available.
core_count integer / required	Set the number of core to enable.
threads_per_core integer / required	Select the number of threads per core to enable. Disable or Enable Intel HT. Choices: 1 2
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: false ← (default) true
detailed_monitoring boolean	Whether to allow detailed CloudWatch metrics to be collected, enabling more detailed alerting. Choices: false true
ebs_optimized boolean	Whether instance is should use optimized EBS volumes, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html. Choices: false true
endpoint_url aliases: ec2_url, aws_endpoint_url, s3_url string	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 AWS_URL or EC2_URL environment variables may also be used, in decreasing order of preference. The ec2_url and s3_url aliases have been deprecated and will be removed in a release after 2024-12-01. Support for the EC2_URL environment variable has been deprecated and will be removed in a release after 2024-12-01.
exact_count integer added in amazon.aws 2.2.0	An integer value which indicates how many instances that match the filters parameter should be running. Instances are either created or terminated based on this value. If termination takes place, least recently created instances will be terminated based on Launch Time. Mutually exclusive with count, instance_ids.
filters dictionary	A dict of filters to apply when deciding whether existing instances match and should be altered. Each dict item consists of a filter key and a filter value. See https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html. for possible filters. Filter names and values are case sensitive. By default, instances are filtered for counting by their “Name” tag, base AMI, state (running, by default), and subnet ID. Any queryable filter can be used. Good candidates are specific tags, SSH keys, or security groups.
hibernation_options boolean added in amazon.aws 5.0.0	Indicates whether an instance is enabled for hibernation. Refer https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/hibernating-prerequisites.html for Hibernation prerequisits. Choices: false ← (default) true
iam_instance_profile aliases: instance_role string	The ARN or name of an EC2-enabled IAM instance profile to be used. If a name is not provided in ARN format then the ListInstanceProfiles permission must also be granted. https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListInstanceProfiles.html If no full ARN is provided, the role with a matching name will be used from the active AWS account.
image dictionary	An image to use for the instance. The amazon.aws.ec2_ami_info module may be used to retrieve images. One of image or image_id are required when instance is not already present.
id string	The AMI ID.
kernel string	a string AKI to override the AMI kernel.
ramdisk string	Overrides the AMI’s default ramdisk ID.
image_id string	ami ID to use for the instance. One of image or image_id are required when instance is not already present. This is an alias for image.id.
instance_ids list / elements=string	If you specify one or more instance IDs, only instances that have the specified IDs are returned. Mutually exclusive with exact_count. Default: []
instance_initiated_shutdown_behavior string	Whether to stop or terminate an instance upon shutdown. Choices: "stop" "terminate"
instance_type string	Instance type to use for the instance, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html. At least one of instance_type or launch_template must be specificed when launching an instance. When the instance is present and the instance_type specified value is different from the current value, the instance will be stopped and the instance type will be updated.
key_name string	Name of the SSH access key to assign to the instance - must exist in the region the instance is created. Use amazon.aws.ec2_key to manage SSH keys.
launch_template dictionary	The EC2 launch template to base instance configuration on. At least one of instance_type or launch_template must be specificed when launching an instance.
id string	The ID of the launch template (optional if name is specified).
name string	The pretty name of the launch template (optional if id is specified).
version string	The specific version of the launch template to use. If unspecified, the template default is chosen.
license_specifications list / elements=dictionary	The license specifications to be used for the instance.
license_configuration_arn string / required	The Amazon Resource Name (ARN) of the license configuration.
metadata_options dictionary added in amazon.aws 2.0.0	Modify the metadata options for the instance. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html for more information. The two suboptions metadata_options.http_endpoint and metadata_options.http_tokens are supported.
http_endpoint string	Enables or disables the HTTP metadata endpoint on instances. If specified a value of disabled, metadata of the instance will not be accessible. Choices: "enabled" ← (default) "disabled"
http_protocol_ipv6 string added in amazon.aws 4.0.0	Whether the instance metadata endpoint is available via IPv6 (enabled) or not (disabled). Choices: "enabled" "disabled" ← (default)
http_put_response_hop_limit integer added in amazon.aws 4.0.0	The desired HTTP PUT response hop limit for instance metadata requests. The larger the number, the further instance metadata requests can travel. Default: 1
http_tokens string	Set the state of token usage for instance metadata requests. If the state is optional (v1 and v2), instance metadata can be retrieved with or without a signed token header on request. If the state is required (v2), a signed token header must be sent with any instance metadata retrieval requests. Choices: "optional" ← (default) "required"
instance_metadata_tags string added in amazon.aws 4.0.0	Whether the instance tags are availble (enabled) via metadata endpoint or not (disabled). Choices: "enabled" "disabled" ← (default)
name string	The Name tag for the instance.
network dictionary	Either a dictionary containing the key interfaces corresponding to a list of network interface IDs or containing specifications for a single network interface. Use the amazon.aws.ec2_eni module to create ENIs with special settings. This field is deprecated and will be removed in a release after 2026-12-01, use network_interfaces or network_interfaces_ids instead. Mutually exclusive with network_interfaces. Mutually exclusive with network_interfaces_ids.
assign_public_ip boolean	When true assigns a public IP address to the interface. Choices: false true
delete_on_termination boolean	Delete the interface when the instance it is attached to is terminated. Choices: false true
description string	A description for the network interface.
device_index integer	The index of the interface to modify.
groups list / elements=string	A list of security group IDs to attach to the interface.
interfaces list / elements=string	A list of ENI IDs (strings) or a list of objects containing the key id.
ipv6_addresses list / elements=string	A list of IPv6 addresses to assign to the network interface.
private_ip_address string	An IPv4 address to assign to the interface.
private_ip_addresses list / elements=string	A list of IPv4 addresses to assign to the network interface.
source_dest_check boolean	Controls whether source/destination checking is enabled on the interface. This field with be ignored when source_dest_check is provided. Choices: false true
subnet_id string	The subnet to connect the network interface to.
network_interfaces list / elements=dictionary added in amazon.aws 8.2.0	A list of dictionaries containing specifications for network interfaces. Use the amazon.aws.ec2_eni module to create ENIs with special settings. Mutually exclusive with network.
assign_public_ip boolean	When true assigns a public IP address to the interface. Choices: false true
delete_on_termination boolean	Delete the interface when the instance it is attached to is terminated. Choices: false true ← (default)
description string	A description for the network interface.
device_index integer	The position of the network interface in the attachment order. Use device index 0 for a primary network interface. Default: 0
groups list / elements=string	A list of security group IDs or names to attach to the interface.
ipv6_addresses list / elements=string	A list of IPv6 addresses to assign to the network interface.
private_ip_address string	An IPv4 address to assign to the interface.
private_ip_addresses list / elements=dictionary	A list of private IPv4 addresses to assign to the network interface. Only one private IPv4 address can be designated as primary. You cannot specify this option if you’re launching more than one instance.
primary boolean	Indicates whether the private IPv4 address is the primary private IPv4 address. Only one IPv4 address can be designated as primary. Choices: false true
private_ip_address string / required	The private IPv4 address.
subnet_id string	The subnet to connect the network interface to.
network_interfaces_ids list / elements=dictionary added in amazon.aws 8.2.0	A list of ENI ids to attach to the instance. Mutually exclusive with network. Mutually exclusive with security_group. Mutually exclusive with security_groups.
device_index integer	The position of the network interface in the attachment order. Default: 0
id string / required	The ID of the network interface.
placement dictionary added in amazon.aws 7.0.0	The location where the instance launched, if applicable.
affinity string	The affinity setting for the instance on the Dedicated Host.
availability_zone string	The Availability Zone of the instance.
group_name string	The name of the placement group the instance is in.
host_id string	The ID of the Dedicated Host on which the instance resides.
host_resource_group_arn string	The ARN of the host resource group in which to launch the instances.
partition_number integer	The number of the partition the instance is in.
tenancy string	Type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. Support for tenancy=host was added in amazon.aws 7.6.0. Choices: "dedicated" "default" "host"
placement_group string	The placement group that needs to be assigned to the instance. This field is deprecated and will be removed in a release after 2025-12-01, use placement instead.
profile aliases: aws_profile string	A named AWS profile to use for authentication. See the AWS documentation for more information about named profiles https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html. The AWS_PROFILE environment variable may also be used. The profile option is mutually exclusive with the aws_access_key, aws_secret_key and security_token options.
purge_tags boolean	If purge_tags=true and tags is set, existing tags will be purged from the resource to match exactly what is defined by tags parameter. If the tags parameter is not set then tags will not be modified, even if purge_tags=True. Tag keys beginning with aws: are reserved by Amazon and can not be modified. As such they will be ignored for the purposes of the purge_tags parameter. See the Amazon documentation for more information https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html#tag-conventions. Choices: false true ← (default)
region aliases: aws_region, ec2_region string	The AWS region to use. For global services such as IAM, Route53 and CloudFront, region is ignored. The AWS_REGION or EC2_REGION environment variables may also be used. See the Amazon AWS documentation for more information http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region. The ec2_region alias has been deprecated and will be removed in a release after 2024-12-01 Support for the EC2_REGION environment variable has been deprecated and will be removed in a release after 2024-12-01.
secret_key aliases: aws_secret_access_key, aws_secret_key, ec2_secret_key string	AWS secret access key. See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. The AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY, or EC2_SECRET_KEY environment variables may also be used in decreasing order of preference. The secret_key and profile options are mutually exclusive. The aws_secret_access_key alias was added in release 5.1.0 for consistency with the AWS botocore SDK. The ec2_secret_key alias has been deprecated and will be removed in a release after 2024-12-01. Support for the EC2_SECRET_KEY environment variable has been deprecated and will be removed in a release after 2024-12-01.
security_group string	A security group ID or name. Mutually exclusive with security_groups. Mutually exclusive with network_interfaces_ids.
security_groups list / elements=string	A list of security group IDs or names (strings). Mutually exclusive with security_group. Mutually exclusive with network_interfaces_ids. Default: []
session_token aliases: aws_session_token, security_token, aws_security_token, access_token string	AWS STS session token for use with temporary credentials. See the AWS documentation for more information about access tokens https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys. The AWS_SESSION_TOKEN, AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN environment variables may also be used in decreasing order of preference. The security_token and profile options are mutually exclusive. Aliases aws_session_token and session_token were added in release 3.2.0, with the parameter being renamed from security_token to session_token in release 6.0.0. The security_token, aws_security_token, and access_token aliases have been deprecated and will be removed in a release after 2024-12-01. Support for the EC2_SECRET_KEY and AWS_SECURITY_TOKEN environment variables has been deprecated and will be removed in a release after 2024-12-01.
source_dest_check boolean added in amazon.aws 8.2.0	Controls whether source/destination checking is enabled on the interface. Choices: false true
state string	Goal state for the instances. state=present: ensures instances exist, but does not guarantee any state (e.g. running). Newly-launched instances will be run by EC2. state=running: state=present + ensures the instances are running. state=started: state=running + waits for EC2 status checks to report OK if wait=true. state=stopped: ensures an existing instance is stopped. state=rebooted: convenience alias for state=stopped immediately followed by state=running. state=restarted: convenience alias for state=stopped immediately followed by state=started. state=terminated: ensures an existing instance is terminated. state=absent: alias for state=terminated. Choices: "present" ← (default) "terminated" "running" "started" "stopped" "restarted" "rebooted" "absent"
tags aliases: resource_tags dictionary	A dictionary representing the tags to be applied to the resource. If the tags parameter is not set then tags will not be modified.
tenancy string	What type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. This field is deprecated and will be removed in a release after 2025-12-01, use placement instead. Choices: "dedicated" "default"
termination_protection boolean	Whether to enable termination protection. This module will not terminate an instance with termination protection active, it must be turned off first. Choices: false true
user_data string	Opaque blob of data which is made available to the EC2 instance.
validate_certs boolean	When set to false, SSL certificates will not be validated for communication with the AWS APIs. Setting validate_certs=false is strongly discouraged, as an alternative, consider setting aws_ca_bundle instead. Choices: false true ← (default)
volumes list / elements=dictionary	A list of block device mappings, by default this will always use the AMI root device so the volumes option is primarily for adding more storage. A mapping contains the (optional) keys device_name, virtual_name, ebs.volume_type, ebs.volume_size, ebs.kms_key_id, ebs.snapshot_id, ebs.iops, and ebs.delete_on_termination. For more information about each parameter, see https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_BlockDeviceMapping.html.
vpc_subnet_id aliases: subnet_id string	The subnet ID in which to launch the instance (VPC). If none is provided, amazon.aws.ec2_instance will chose the default zone of the default VPC.
wait boolean	Whether or not to wait for the desired state (use wait_timeout to customize this). Choices: false true ← (default)
wait_timeout integer	How long to wait (in seconds) for the instance to finish booting/terminating. Default: 600

Notes

Note

• Caution: For modules, environment variables and configuration files are read from the Ansible ‘host’ context and not the ‘controller’ context. As such, files may need to be explicitly copied to the ‘host’. For lookup and connection plugins, environment variables and configuration files are read from the Ansible ‘controller’ context and not the ‘host’ context.

• The AWS SDK (boto3) that Ansible uses may also read defaults for credentials and other settings, such as the region, from its configuration files in the Ansible ‘host’ context (typically ~/.aws/credentials). See https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html for more information.

Examples

# Note: These examples do not set authentication details, see the AWS Guide for details.

- name: Terminate every running instance in a region. Use with EXTREME caution.
  amazon.aws.ec2_instance:
    state: absent
    filters:
      instance-state-name: running

- name: restart a particular instance by its ID
  amazon.aws.ec2_instance:
    state: restarted
    instance_ids:
      - i-12345678

- name: start an instance with a public IP address
  amazon.aws.ec2_instance:
    name: "public-compute-instance"
    key_name: "prod-ssh-key"
    vpc_subnet_id: subnet-5ca1ab1e
    instance_type: c5.large
    security_group: default
    network_interfaces:
      - assign_public_ip: true
    image_id: ami-123456
    tags:
      Environment: Testing

- name: start an instance and Add EBS
  amazon.aws.ec2_instance:
    name: "public-withebs-instance"
    vpc_subnet_id: subnet-5ca1ab1e
    instance_type: t2.micro
    key_name: "prod-ssh-key"
    security_group: default
    volumes:
      - device_name: /dev/sda1
        ebs:
          volume_size: 16
          delete_on_termination: true

- name: start an instance and Add EBS volume from a snapshot
  amazon.aws.ec2_instance:
    name: "public-withebs-instance"
    instance_type: t2.micro
    image_id: ami-1234567890
    vpc_subnet_id: subnet-5ca1ab1e
    volumes:
      - device_name: /dev/sda2
        ebs:
          snapshot_id: snap-1234567890

- name: Create EC2 instance with termination protection turned on
  amazon.aws.ec2_instance:
    name: "my-ec2-instance"
    vpc_subnet_id: subnet-5ca1ab1e
    instance_type: t3.small
    image_id: ami-123456
    termination_protection: true
    wait: true

- name: start an instance with a cpu_options
  amazon.aws.ec2_instance:
    name: "public-cpuoption-instance"
    vpc_subnet_id: subnet-5ca1ab1e
    tags:
      Environment: Testing
    instance_type: c4.large
    volumes:
      - device_name: /dev/sda1
        ebs:
          delete_on_termination: true
    cpu_options:
      core_count: 1
      threads_per_core: 1

- name: start an instance and have it begin a Tower callback on boot
  amazon.aws.ec2_instance:
    name: "tower-callback-test"
    key_name: "prod-ssh-key"
    vpc_subnet_id: subnet-5ca1ab1e
    security_group: default
    tower_callback:
      # IP or hostname of tower server
      tower_address: 1.2.3.4
      job_template_id: 876
      host_config_key: '[secret config key goes here]'
    network_interfaces:
      - assign_public_ip: true
    image_id: ami-123456
    cpu_credit_specification: unlimited
    tags:
      SomeThing: "A value"

- name: start an instance with ENI (An existing ENI ID is required)
  amazon.aws.ec2_instance:
    name: "public-eni-instance"
    key_name: "prod-ssh-key"
    vpc_subnet_id: subnet-5ca1ab1e
    network_interfaces_ids:
      - id: "eni-12345"
        device_index: 0
    tags:
      Env: "eni_on"
    volumes:
      - device_name: /dev/sda1
        ebs:
          delete_on_termination: true
    instance_type: t2.micro
    image_id: ami-123456

- name: add second ENI interface
  amazon.aws.ec2_instance:
    name: "public-eni-instance"
    network_interfaces_ids:
      - id: "eni-12345"
        device_index: 0
      - id: "eni-67890"
        device_index: 1
    image_id: ami-123456
    tags:
      Env: "eni_on"
    instance_type: t2.micro

- name: start an instance with metadata options
  amazon.aws.ec2_instance:
    name: "public-metadataoptions-instance"
    vpc_subnet_id: subnet-5calable
    instance_type: t3.small
    image_id: ami-123456
    tags:
      Environment: Testing
    metadata_options:
      http_endpoint: enabled
      http_tokens: optional

# ensure number of instances running with a tag matches exact_count
- name: start multiple instances
  amazon.aws.ec2_instance:
    instance_type: t3.small
    image_id: ami-123456
    exact_count: 5
    region: us-east-2
    vpc_subnet_id: subnet-0123456
    network_interfaces:
      - assign_public_ip: true
        groups:
          - default
    tags:
      foo: bar

# launches multiple instances - specific number of instances
- name: start specific number of multiple instances
  amazon.aws.ec2_instance:
    instance_type: t3.small
    image_id: ami-123456
    count: 3
    region: us-east-2
    network_interfaces:
      - assign_public_ip: true
        groups:
          - default
        subnet_id: subnet-0123456
    state: present
    tags:
      foo: bar

# launches an instance with a primary and a secondary network interfaces
- name: start an instance with a primary and secondary network interfaces
  amazon.aws.ec2_instance:
    instance_type: t2.large
    image_id: ami-123456
    region: us-east-2
    network_interfaces:
      - assign_public_ip: true
        groups:
          - default
        subnet_id: subnet-0123456
        private_ip_addresses:
          - primary: true
            private_ip_address: 168.50.4.239
          - primary: false
            private_ip_address: 168.50.4.237
    state: present
    tags:
      foo: bar

# launches a mac instance with HostResourceGroupArn and LicenseSpecifications
- name: start a mac instance with a host resource group and license specifications
  amazon.aws.ec2_instance:
    name: "mac-compute-instance"
    key_name: "prod-ssh-key"
    vpc_subnet_id: subnet-5ca1ab1e
    instance_type: mac1.metal
    security_group: default
    placement:
      host_resource_group_arn: arn:aws:resource-groups:us-east-1:123456789012:group/MyResourceGroup
    license_specifications:
      - license_configuration_arn: arn:aws:license-manager:us-east-1:123456789012:license-configuration:lic-0123456789
    image_id: ami-123456
    tags:
      Environment: Testing

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed_ids list / elements=string added in amazon.aws 5.3.0	A list of the set of EC2 instance IDs changed by the module action. Returned: when instances that must be present are launched Sample: ["i-0123456789abcdef0"]
instance_ids list / elements=string added in amazon.aws 5.3.0	A list of EC2 instance IDs matching the provided specification and filters. Returned: always Sample: ["i-0123456789abcdef0", "i-0123456789abcdef1"]
instances complex	A list of EC2 instances. Returned: when wait=true or when matching instances already exist
additional_info string added in amazon.aws 7.1.0	Reserved for Amazon’s internal use. Returned: always
ami_launch_index integer	The AMI launch index, which can be used to find this instance in the launch group. Returned: always Sample: 0
architecture string	The architecture of the image. Returned: always Sample: "x86_64"
block_device_mappings complex	Any block device mapping entries for the instance. Returned: always
device_name string	The device name exposed to the instance (for example, /dev/sdh or xvdh). Returned: always Sample: "/dev/sdh"
ebs complex	Parameters used to automatically set up EBS volumes when the instance is launched. Returned: always
attach_time string	The time stamp when the attachment initiated. Returned: always Sample: "2017-03-23T22:51:24+00:00"
delete_on_termination boolean	Indicates whether the volume is deleted on instance termination. Returned: always Sample: true
status string	The attachment state. Returned: always Sample: "attached"
volume_id string	The ID of the EBS volume. Returned: always Sample: "vol-12345678"
capacity_reservation_specification complex	Information about the Capacity Reservation targeting option. Returned: success
capacity_reservation_preference string	Describes the Capacity Reservation preferences. Returned: success Sample: "open"
client_token string	The idempotency token you provided when you launched the instance, if applicable. Returned: always Sample: "mytoken"
cpu_options complex	The CPU options for the instance. Returned: success
amd_sev_snp string	Indicates whether the instance is enabled for AMD SEV-SNP. Returned: success Sample: "enabled"
core_count integer	The number of CPU cores for the instance. Returned: success Sample: 1
threads_per_core integer	The number of threads per CPU core. Returned: success Sample: 2
current_instance_boot_mode string	The boot mode that is used to boot the instance at launch or start. Returned: success Sample: "legacy-bios"
ebs_optimized boolean	Indicates whether the instance is optimized for EBS I/O. Returned: always Sample: false
ena_support boolean	Specifies whether enhanced networking with ENA is enabled. Returned: always Sample: true
enclave_options dictionary	Indicates whether the instance is enabled for Amazon Web Services Nitro Enclaves. Returned: success
enabled boolean	If this parameter is set to true, the instance is enabled for Amazon Web Services Nitro Enclaves. Returned: always Sample: false
hibernation_options dictionary	Indicates whether the instance is enabled for hibernation. Returned: success
configured boolean	If true, your instance is enabled for hibernation; otherwise, it is not enabled for hibernation. Returned: always Sample: false
hypervisor string	The hypervisor type of the instance. Returned: always Sample: "xen"
iam_instance_profile complex	The IAM instance profile associated with the instance, if applicable. Returned: always
arn string	The Amazon Resource Name (ARN) of the instance profile. Returned: always Sample: "arn:aws:iam::123456789012:instance-profile/myprofile"
id string	The ID of the instance profile. Returned: always Sample: "JFJ397FDG400FG9FD1N"
image_id string	The ID of the AMI used to launch the instance. Returned: always Sample: "ami-0011223344"
instance_id string	The ID of the instance. Returned: always Sample: "i-012345678"
instance_type string	The instance type size of the running instance. Returned: always Sample: "t2.micro"
key_name string	The name of the key pair, if this instance was launched with an associated key pair. Returned: always Sample: "my-key"
launch_time string	The time the instance was launched. Returned: always Sample: "2017-03-23T22:51:24+00:00"
licenses list / elements=dictionary	The license configurations for the instance. Returned: When license specifications are provided.
license_configuration_arn string	The Amazon Resource Name (ARN) of the license configuration. Returned: always Sample: "arn:aws:license-manager:us-east-1:123456789012:license-configuration:lic-0123456789"
metadata_options complex	The metadata options for the instance. Returned: always
http_endpoint string	Indicates whether the HTTP metadata endpoint on your instances is enabled or disabled. Returned: success Sample: "enabled"
http_protocol_ipv6 string	Indicates whether the IPv6 endpoint for the instance metadata service is enabled or disabled. Returned: success Sample: "disabled"
http_put_response_hop_limit integer	The maximum number of hops that the metadata token can travel. Returned: success Sample: 1
http_tokens string	Indicates whether IMDSv2 is required. Returned: success Sample: "optional"
instance_metadata_tags string	Indicates whether access to instance tags from the instance metadata is enabled or disabled. Returned: success Sample: "disabled"
state string	The state of the metadata option changes. Returned: success Sample: "applied"
monitoring complex	The monitoring for the instance. Returned: always
state string	Indicates whether detailed monitoring is enabled. Otherwise, basic monitoring is enabled. Returned: always Sample: "disabled"
network_interfaces list / elements=dictionary	One or more network interfaces for the instance. Returned: always
association complex	The association information for an Elastic IPv4 associated with the network interface. Returned: always
ip_owner_id string	The ID of the owner of the Elastic IP address. Returned: always Sample: "amazon"
public_dns_name string	The public DNS name. Returned: always Sample: ""
public_ip string	The public IP address or Elastic IP address bound to the network interface. Returned: always Sample: "1.2.3.4"
attachment complex	The network interface attachment. Returned: always
attach_time string	The time stamp when the attachment initiated. Returned: always Sample: "2017-03-23T22:51:24+00:00"
attachment_id string	The ID of the network interface attachment. Returned: always Sample: "eni-attach-3aff3f"
delete_on_termination boolean	Indicates whether the network interface is deleted when the instance is terminated. Returned: always Sample: true
device_index integer	The index of the device on the instance for the network interface attachment. Returned: always Sample: 0
network_card_index integer	The index of the network card. Returned: always Sample: 0
status string	The attachment state. Returned: always Sample: "attached"
description string	The description. Returned: always Sample: "My interface"
groups list / elements=dictionary	One or more security groups. Returned: always
group_id string	The ID of the security group. Returned: always Sample: "sg-abcdef12"
group_name string	The name of the security group. Returned: always Sample: "mygroup"
interface_type string	The type of network interface. Returned: always Sample: "interface"
ipv6_addresses list / elements=dictionary	One or more IPv6 addresses associated with the network interface. Returned: always
ipv6_address string	The IPv6 address. Returned: always Sample: "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
mac_address string	The MAC address. Returned: always Sample: "00:11:22:33:44:55"
network_interface_id string	The ID of the network interface. Returned: always Sample: "eni-01234567"
owner_id string	The AWS account ID of the owner of the network interface. Returned: always Sample: "01234567890"
private_dns_name string	The private DNS hostname name assigned to the instance. Returned: always Sample: "ip-10-1-0-156.ec2.internal"
private_ip_address string	The IPv4 address of the network interface within the subnet. Returned: always Sample: "10.0.0.1"
private_ip_addresses list / elements=dictionary	The private IPv4 addresses associated with the network interface. Returned: always
association complex	The association information for an Elastic IP address (IPv4) associated with the network interface. Returned: success
ip_owner_id string	The ID of the owner of the Elastic IP address. Returned: always Sample: "amazon"
public_dns_name string	The public DNS name. Returned: always Sample: ""
public_ip string	The public IP address or Elastic IP address bound to the network interface. Returned: always Sample: "1.2.3.4"
primary boolean	Indicates whether this IPv4 address is the primary private IP address of the network interface. Returned: always Sample: true
private_dns_name string	The private DNS hostname name assigned to the instance. Returned: always Sample: "ip-10-1-0-156.ec2.internal"
private_ip_address string	The private IPv4 address of the network interface. Returned: always Sample: "10.0.0.1"
source_dest_check boolean	Indicates whether source/destination checking is enabled. Returned: always Sample: true
status string	The status of the network interface. Returned: always Sample: "in-use"
subnet_id string	The ID of the subnet for the network interface. Returned: always Sample: "subnet-0123456"
vpc_id string	The ID of the VPC for the network interface. Returned: always Sample: "vpc-0123456"
placement complex	The location where the instance launched, if applicable. Returned: always
affinity string	The affinity setting for the instance on the Dedicated Host. Returned: When a placement group is specified.
availability_zone string	The Availability Zone of the instance. Returned: always Sample: "ap-southeast-2a"
group_id string	The ID of the placement group the instance is in (for cluster compute instances). Returned: success Sample: "pg-01234566"
group_name string	The name of the placement group the instance is in (for cluster compute instances). Returned: always Sample: "my-placement-group"
host_id string	The ID of the Dedicated Host on which the instance resides. Returned: success
host_resource_group_arn string	The ARN of the host resource group in which the instance is in. Returned: success Sample: "arn:aws:resource-groups:us-east-1:123456789012:group/MyResourceGroup"
partition_number integer	The number of the partition the instance is in. Returned: success Sample: 1
tenancy string	Type of tenancy to allow an instance to use. Default is shared tenancy. Dedicated tenancy will incur additional charges. Returned: always Sample: "default"
platform_details string	The platform details value for the instance. Returned: always Sample: "Linux/UNIX"
private_dns_name string	The private DNS name. Returned: always Sample: "ip-10-0-0-1.ap-southeast-2.compute.internal"
private_dns_name_options dictionary	The options for the instance hostname. Returned: success
enable_resource_name_dns_a_record boolean	Indicates whether to respond to DNS queries for instance hostnames with DNS A records. Returned: success Sample: false
enable_resource_name_dns_aaaa_record boolean	Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. Returned: success Sample: false
hostname_type string	The type of hostname to assign to an instance. Returned: success Sample: "ip-name"
private_ip_address string	The IPv4 address of the network interface within the subnet. Returned: always Sample: "10.0.0.1"
product_codes list / elements=dictionary	One or more product codes. Returned: always
product_code_id string	The product code. Returned: always Sample: "aw0evgkw8ef3n2498gndfgasdfsd5cce"
product_code_type string	The type of product code. Returned: always Sample: "marketplace"
public_dns_name string	The public DNS name assigned to the instance. Returned: always
public_ip_address string	The public IPv4 address assigned to the instance Returned: always Sample: "52.0.0.1"
root_device_name string	The device name of the root device Returned: always Sample: "/dev/sda1"
root_device_type string	The type of root device used by the AMI. Returned: always Sample: "ebs"
security_groups list / elements=dictionary	One or more security groups for the instance. Returned: always
group_id string	The ID of the security group. Returned: always Sample: "sg-0123456"
group_name string	The name of the security group. Returned: always Sample: "my-security-group"
source_dest_check boolean	Indicates whether source/destination checking is enabled. Returned: always Sample: true
state complex	The current state of the instance. Returned: always
code integer	The low byte represents the state. Returned: always Sample: 16
name string	The name of the state. Returned: always Sample: "running"
state_transition_reason string	The reason for the most recent state transition. Returned: always
subnet_id string	The ID of the subnet in which the instance is running. Returned: always Sample: "subnet-00abcdef"
tags dictionary	Any tags assigned to the instance. Returned: always
virtualization_type string	The type of virtualization of the AMI. Returned: always Sample: "hvm"
vpc_id dictionary	The ID of the VPC the instance is in. Returned: always Sample: "vpc-0011223344"
terminated_ids list / elements=string added in amazon.aws 5.3.0	A list of the set of EC2 instance IDs terminated by the module action. Returned: when instances that must be absent are terminated Sample: ["i-0123456789abcdef1"]

Authors

• Ryan Scott Brown (@ryansb)

Collection links

• Issue Tracker
• Repository (Sources)
• Communication