ec2_metadata_facts - Gathers facts (instance metadata) about remote hosts within ec2

Synopsis

Aliases: ec2_facts

Parameters

Parameter Choices/Defaults Comments
client_cert
PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, client_key is not required.
client_key
PEM formatted file that contains your private key to be used for SSL client authentication. If client_cert contains both the certificate and key, this option is not required.
force
    Choices:
  • no ←
  • yes
If yes do not get a cached copy.

aliases: thirsty
force_basic_auth
    Choices:
  • no ←
  • yes
Credentials specified with url_username and url_password should be passed in HTTP Header.
http_agent Default:
ansible-httpget
Header to identify as, generally appears in web server logs.
url
HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
url_password
The password for use in HTTP basic authentication.
If the url_username parameter is not specified, the url_password parameter will not be used.
url_username
The username for use in HTTP basic authentication.
This parameter can be used without url_password for sites that allow empty passwords
use_proxy
    Choices:
  • no
  • yes ←
If no, it will not use a proxy, even if one is defined in an environment variable on the target hosts.
validate_certs
    Choices:
  • no
  • yes ←
If no, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

Notes

Note

  • Parameters to filter on ec2_metadata_facts may be added later.

Examples

# Gather EC2 metadata facts
- ec2_metadata_facts:

- debug:
    msg: "This instance is a t1.micro"
  when: ansible_ec2_instance_type == "t1.micro"

Returned Facts

Facts returned by this module are added/updated in the hostvars host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.

Fact Returned Description
ansible_ec2_ami_id
string
The AMI ID used to launch the instance.

Sample:
ami-XXXXXXXX
ansible_ec2_ami_launch_index
string
If you started more than one instance at the same time, this value indicates the order in which the instance was launched. The value of the first instance launched is 0.

Sample:
0
ansible_ec2_ami_manifest_path
string
The path to the AMI manifest file in Amazon S3. If you used an Amazon EBS-backed AMI to launch the instance, the returned result is unknown.

Sample:
(unknown)
ansible_ec2_ancestor_ami_ids
string
The AMI IDs of any instances that were rebundled to create this AMI. This value will only exist if the AMI manifest file contained an ancestor-amis key.

Sample:
(unknown)
ansible_ec2_block_device_mapping_ami
string
The virtual device that contains the root/boot file system.

Sample:
/dev/sda1
ansible_ec2_block_device_mapping_ebsN
string
The virtual devices associated with Amazon EBS volumes, if any are present. Amazon EBS volumes are only available in metadata if they were present at launch time or when the instance was last started. The N indicates the index of the Amazon EBS volume (such as ebs1 or ebs2).

Sample:
/dev/xvdb
ansible_ec2_block_device_mapping_ephemeralN
string
The virtual devices associated with ephemeral devices, if any are present. The N indicates the index of the ephemeral volume.

Sample:
/dev/xvdc
ansible_ec2_block_device_mapping_root
string
The virtual devices or partitions associated with the root devices, or partitions on the virtual device, where the root (/ or C) file system is associated with the given instance.

Sample:
/dev/sda1
ansible_ec2_block_device_mapping_swap
string
The virtual devices associated with swap. Not always present.

Sample:
/dev/sda2
ansible_ec2_fws_instance_monitoring
string
Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch.

Sample:
enabled
ansible_ec2_hostname
string
The private IPv4 DNS hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).

Sample:
ip-10-0-0-1.ec2.internal
ansible_ec2_iam_info
complex
If there is an IAM role associated with the instance, contains information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId. Otherwise, not present.

ansible_ec2_iam_info_instanceprofilearn
string
The IAM instance profile ARN.

Sample:
arn:aws:iam::<account id>:instance-profile/<role name>
ansible_ec2_iam_info_instanceprofileid
string
IAM instance profile ID.

ansible_ec2_iam_info_lastupdated
string
IAM info last updated time.

Sample:
2017-05-12T02:42:27Z
ansible_ec2_iam_instance_profile_role
string
IAM instance role.

Sample:
role_name
ansible_ec2_iam_security_credentials_
string
If there is an IAM role associated with the instance, role-name is the name of the role, and role-name contains the temporary security credentials associated with the role. Otherwise, not present.

ansible_ec2_iam_security_credentials__accesskeyid
string
IAM role access key ID.

ansible_ec2_iam_security_credentials__code
string
IAM code.

Sample:
Success
ansible_ec2_iam_security_credentials__expiration
string
IAM role credentials expiration time.

Sample:
2017-05-12T09:11:41Z
ansible_ec2_iam_security_credentials__lastupdated
string
IAM role last updated time.

Sample:
2017-05-12T02:40:44Z
ansible_ec2_iam_security_credentials__secretaccesskey
string
IAM role secret access key.

ansible_ec2_iam_security_credentials__token
string
IAM role token.

ansible_ec2_iam_security_credentials__type
string
IAM role type.

Sample:
AWS-HMAC
ansible_ec2_instance_action
string
Notifies the instance that it should reboot in preparation for bundling.

Sample:
none
ansible_ec2_instance_id
string
The ID of this instance.

Sample:
i-XXXXXXXXXXXXXXXXX
ansible_ec2_instance_identity_document
string
JSON containing instance attributes, such as instance-id, private IP address, etc.

ansible_ec2_instance_identity_document_accountid
string
Sample:
012345678901
ansible_ec2_instance_identity_document_architecture
string
Instance system architecture.

Sample:
x86_64
ansible_ec2_instance_identity_document_availabilityzone
string
The Availability Zone in which the instance launched.

Sample:
us-east-1a
ansible_ec2_instance_identity_document_billingproducts
string
Billing products for this instance.

ansible_ec2_instance_identity_document_devpayproductcodes
string
Product codes for the launched AMI.

ansible_ec2_instance_identity_document_imageid
string
The AMI ID used to launch the instance.

Sample:
ami-01234567
ansible_ec2_instance_identity_document_instanceid
string
The ID of this instance.

Sample:
i-0123456789abcdef0
ansible_ec2_instance_identity_document_instancetype
string
The type of instance.

Sample:
m4.large
ansible_ec2_instance_identity_document_kernelid
string
The ID of the kernel launched with this instance, if applicable.

ansible_ec2_instance_identity_document_pendingtime
string
The instance pending time.

Sample:
2017-05-11T20:51:20Z
ansible_ec2_instance_identity_document_privateip
string
The private IPv4 address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).

Sample:
10.0.0.1
ansible_ec2_instance_identity_document_ramdiskid
string
The ID of the RAM disk specified at launch time, if applicable.

ansible_ec2_instance_identity_document_region
string
The Region in which the instance launched.

Sample:
us-east-1
ansible_ec2_instance_identity_document_version
string
Identity document version.

Sample:
2010-08-31
ansible_ec2_instance_identity_pkcs7
string
Used to verify the document's authenticity and content against the signature.

ansible_ec2_instance_identity_rsa2048
string
Used to verify the document's authenticity and content against the signature.

ansible_ec2_instance_identity_signature
string
Data that can be used by other parties to verify its origin and authenticity.

ansible_ec2_instance_type
string
The type of instance.

Sample:
m4.large
ansible_ec2_local_hostname
string
The private IPv4 DNS hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).

Sample:
ip-10-0-0-1.ec2.internal
ansible_ec2_local_ipv4
string
The private IPv4 address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).

Sample:
10.0.0.1
ansible_ec2_mac
string
The instance's media access control (MAC) address. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).

Sample:
00:11:22:33:44:55
ansible_ec2_metrics_vhostmd
string
Metrics.

ansible_ec2_network_interfaces_macs__device_number
string
The unique device number associated with that interface. The device number corresponds to the device name; for example, a device-number of 2 is for the eth2 device. This category corresponds to the DeviceIndex and device-index fields that are used by the Amazon EC2 API and the EC2 commands for the AWS CLI.

Sample:
0
ansible_ec2_network_interfaces_macs__interface_id
string
The elastic network interface ID.

Sample:
eni-12345678
ansible_ec2_network_interfaces_macs__ipv4_associations_
string
The private IPv4 addresses that are associated with each public-ip address and assigned to that interface.

ansible_ec2_network_interfaces_macs__ipv6s
string
The IPv6 addresses associated with the interface. Returned only for instances launched into a VPC.

ansible_ec2_network_interfaces_macs__local_hostname
string
The interface's local hostname.

ansible_ec2_network_interfaces_macs__local_ipv4s
string
The private IPv4 addresses associated with the interface.

ansible_ec2_network_interfaces_macs__mac
string
The instance's MAC address.

Sample:
00:11:22:33:44:55
ansible_ec2_network_interfaces_macs__owner_id
string
The ID of the owner of the network interface. In multiple-interface environments, an interface can be attached by a third party, such as Elastic Load Balancing. Traffic on an interface is always billed to the interface owner.

Sample:
01234567890
ansible_ec2_network_interfaces_macs__public_hostname
string
The interface's public DNS (IPv4). If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true.

Sample:
ec2-1-2-3-4.compute-1.amazonaws.com
ansible_ec2_network_interfaces_macs__public_ipv4s
string
The Elastic IP addresses associated with the interface. There may be multiple IPv4 addresses on an instance.

Sample:
1.2.3.4
ansible_ec2_network_interfaces_macs__security_group_ids
string
The IDs of the security groups to which the network interface belongs. Returned only for instances launched into a VPC.

Sample:
sg-01234567,sg-01234568
ansible_ec2_network_interfaces_macs__security_groups
string
Security groups to which the network interface belongs. Returned only for instances launched into a VPC.

Sample:
secgroup1,secgroup2
ansible_ec2_network_interfaces_macs__subnet_id
string
The ID of the subnet in which the interface resides. Returned only for instances launched into a VPC.

Sample:
subnet-01234567
ansible_ec2_network_interfaces_macs__subnet_ipv4_cidr_block
string
The IPv4 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC.

Sample:
10.0.1.0/24
ansible_ec2_network_interfaces_macs__subnet_ipv6_cidr_blocks
string
The IPv6 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC.

ansible_ec2_network_interfaces_macs__vpc_id
string
The ID of the VPC in which the interface resides. Returned only for instances launched into a VPC.

Sample:
vpc-0123456
ansible_ec2_network_interfaces_macs__vpc_ipv4_cidr_block
string
The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC.

Sample:
10.0.0.0/16
ansible_ec2_network_interfaces_macs__vpc_ipv4_cidr_blocks
string
The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC.

Sample:
10.0.0.0/16
ansible_ec2_network_interfaces_macs__vpc_ipv6_cidr_blocks
string
The IPv6 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC.

ansible_ec2_placement_availability_zone
string
The Availability Zone in which the instance launched.

Sample:
us-east-1a
ansible_ec2_placement_region
string
The Region in which the instance launched.

Sample:
us-east-1
ansible_ec2_product_codes
string
Product codes associated with the instance, if any.

Sample:
aw0evgkw8e5c1q413zgy5pjce
ansible_ec2_profile
string
EC2 instance hardware profile.

Sample:
default-hvm
ansible_ec2_public_hostname
string
The instance's public DNS. If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true.

Sample:
ec2-1-2-3-4.compute-1.amazonaws.com
ansible_ec2_public_ipv4
string
The public IPv4 address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address.

Sample:
1.2.3.4
ansible_ec2_public_key
string
Public key. Only available if supplied at instance launch time.

ansible_ec2_ramdisk_id
string
The ID of the RAM disk specified at launch time, if applicable.

ansible_ec2_reservation_id
string
The ID of the reservation.

Sample:
r-0123456789abcdef0
ansible_ec2_security_groups
string
The names of the security groups applied to the instance. After launch, you can only change the security groups of instances running in a VPC. Such changes are reflected here and in network/interfaces/macs/mac/security-groups.

Sample:
securitygroup1,securitygroup2
ansible_ec2_services_domain
string
The domain for AWS resources for the region; for example, amazonaws.com for us-east-1.

Sample:
amazonaws.com
ansible_ec2_services_partition
string
The partition that the resource is in. For standard AWS regions, the partition is aws. If you have resources in other partitions, the partition is aws-partitionname. For example, the partition for resources in the China (Beijing) region is aws-cn.

Sample:
aws
ansible_ec2_spot_termination_time
string
The approximate time, in UTC, that the operating system for your Spot instance will receive the shutdown signal. This item is present and contains a time value only if the Spot instance has been marked for termination by Amazon EC2. The termination-time item is not set to a time if you terminated the Spot instance yourself.

Sample:
2015-01-05T18:02:00Z
ansible_ec2_user_data
string
The instance user data.

Sample:
#!/bin/bash


Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Silviu Dicu (@silviud)
  • Vinay Dandekar (@roadmapper)

Hint

If you notice any issues in this documentation you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/ec2_metadata_facts_module.html