amazon.aws.ec2_metadata_facts module – Gathers facts (instance metadata) about remote hosts within EC2

Note

This module is part of the amazon.aws collection (version 10.0.0-dev0).

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

New in amazon.aws 1.0.0

Synopsis

• This module fetches data from the instance metadata endpoint in EC2 as per https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html.

• The module must be called from within the EC2 instance itself.

• The module is configured to utilize the session oriented Instance Metadata Service v2 (IMDSv2) https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html.

• If the HttpEndpoint parameter https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html#API_ModifyInstanceMetadataOptions_RequestParameters is set to disabled for the EC2 instance, the module will return an error while retrieving a session token.

Parameters

Parameter	Comments
metadata_token_ttl_seconds integer added in amazon.aws 8.2.0	Specify a value for the X-aws-ec2-metadata-token-ttl-seconds header. Value must be between 1 and 21600. Default: 60

Notes

Note

• Parameters to filter on ec2_metadata_facts may be added later.

Examples

# Gather EC2 metadata facts
- amazon.aws.ec2_metadata_facts:

# Set a bigger value for X-aws-ec2-metadata-token-ttl-seconds header
- amazon.aws.ec2_metadata_facts:
    metadata_token_ttl_seconds: 240

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

Key	Description
ansible_ec2_ami_id string	The AMI ID used to launch the instance. Returned: success 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. Returned: success 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. Returned: success 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. Returned: success Sample: "(unknown)"
ansible_ec2_block_device_mapping_ami string	The virtual device that contains the root/boot file system. Returned: success 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). Returned: success 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. Returned: success 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. Returned: success Sample: "/dev/sda1"
ansible_ec2_block_device_mapping_swap string	The virtual devices associated with swap. Not always present. Returned: success Sample: "/dev/sda2"
ansible_ec2_fws_instance_monitoring string	Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch. Returned: success 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). Returned: success 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. Returned: success Sample: ""
InstanceProfileArn string	The ARN of the InstanceProfile associated with the Instance. Returned: success
InstanceProfileId string	The Id of the InstanceProfile associated with the Instance. Returned: success
LastUpdated string	The last time which InstanceProfile is associated with the Instance changed. Returned: success
ansible_ec2_iam_info_instanceprofilearn string	The IAM instance profile ARN. Returned: success Sample: "arn:aws:iam::123456789012:instance-profile/role_name"
ansible_ec2_iam_info_instanceprofileid string	IAM instance profile ID. Returned: success Sample: ""
ansible_ec2_iam_info_lastupdated string	IAM info last updated time. Returned: success Sample: "2017-05-12T02:42:27Z"
ansible_ec2_iam_instance_profile_role string	IAM instance role. Returned: success Sample: "role_name"
ansible_ec2_iam_security_credentials_role_name 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. Returned: success Sample: ""
ansible_ec2_iam_security_credentials_role_name_accesskeyid string	IAM role access key ID. Returned: success Sample: ""
ansible_ec2_iam_security_credentials_role_name_code string	IAM code. Returned: success Sample: "Success"
ansible_ec2_iam_security_credentials_role_name_expiration string	IAM role credentials expiration time. Returned: success Sample: "2017-05-12T09:11:41Z"
ansible_ec2_iam_security_credentials_role_name_lastupdated string	IAM role last updated time. Returned: success Sample: "2017-05-12T02:40:44Z"
ansible_ec2_iam_security_credentials_role_name_secretaccesskey string	IAM role secret access key. Returned: success Sample: ""
ansible_ec2_iam_security_credentials_role_name_token string	IAM role token. Returned: success Sample: ""
ansible_ec2_iam_security_credentials_role_name_type string	IAM role type. Returned: success Sample: "AWS-HMAC"
ansible_ec2_instance_action string	Notifies the instance that it should reboot in preparation for bundling. Returned: success Sample: "none"
ansible_ec2_instance_id string	The ID of this instance. Returned: success Sample: "i-XXXXXXXXXXXXXXXXX"
ansible_ec2_instance_identity_document string	JSON containing instance attributes, such as instance-id, private IP address, etc. Returned: success Sample: ""
ansible_ec2_instance_identity_document_accountid string	Returned: success Sample: "123456789012"
ansible_ec2_instance_identity_document_architecture string	Instance system architecture. Returned: success Sample: "x86_64"
ansible_ec2_instance_identity_document_availabilityzone string	The Availability Zone in which the instance launched. Returned: success Sample: "us-east-1a"
ansible_ec2_instance_identity_document_billingproducts string	Billing products for this instance. Returned: success Sample: ""
ansible_ec2_instance_identity_document_devpayproductcodes string	Product codes for the launched AMI. Returned: success Sample: ""
ansible_ec2_instance_identity_document_imageid string	The AMI ID used to launch the instance. Returned: success Sample: "ami-01234567"
ansible_ec2_instance_identity_document_instanceid string	The ID of this instance. Returned: success Sample: "i-0123456789abcdef0"
ansible_ec2_instance_identity_document_instancetype string	The type of instance. Returned: success Sample: "m4.large"
ansible_ec2_instance_identity_document_kernelid string	The ID of the kernel launched with this instance, if applicable. Returned: success Sample: ""
ansible_ec2_instance_identity_document_pendingtime string	The instance pending time. Returned: success 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). Returned: success Sample: "10.0.0.1"
ansible_ec2_instance_identity_document_ramdiskid string	The ID of the RAM disk specified at launch time, if applicable. Returned: success Sample: ""
ansible_ec2_instance_identity_document_region string	The Region in which the instance launched. Returned: success Sample: "us-east-1"
ansible_ec2_instance_identity_document_version string	Identity document version. Returned: success Sample: "2010-08-31"
ansible_ec2_instance_identity_pkcs7 string	Used to verify the document’s authenticity and content against the signature. Returned: success Sample: ""
ansible_ec2_instance_identity_rsa2048 string	Used to verify the document’s authenticity and content against the signature. Returned: success Sample: ""
ansible_ec2_instance_identity_signature string	Data that can be used by other parties to verify its origin and authenticity. Returned: success Sample: ""
ansible_ec2_instance_life_cycle string	The purchasing option of the instance. Returned: success Sample: "on-demand"
ansible_ec2_instance_tags dictionary added in amazon.aws 9.1.0	The dict of tags for the instance. Returns empty dict if access to tags (InstanceMetadataTags) in instance metadata is not enabled. Returned: success Sample: {"tagKey1": "tag value 1", "tag_key2": "tag value 2"}
ansible_ec2_instance_tags_keys list / elements=string added in amazon.aws 5.5.0	The list of tags keys of the instance. Returns empty list if access to tags (InstanceMetadataTags) in instance metadata is not enabled. Returned: success Sample: ["tagKey1", "tag_key2"]
ansible_ec2_instance_type string	The type of the instance. Returned: success 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). Returned: success 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). Returned: success 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). Returned: success Sample: "00:11:22:33:44:55"
ansible_ec2_metrics_vhostmd string	Metrics; no longer available. Returned: success Sample: ""
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: "0"
ansible_ec2_network_interfaces_macs_mac_address_interface_id string	The elastic network interface ID. Returned: success Sample: "eni-12345678"
ansible_ec2_network_interfaces_macs_mac_address_ipv4_associations_ip_address string	The private IPv4 addresses that are associated with each public-ip address and assigned to that interface. Returned: success Sample: ""
ansible_ec2_network_interfaces_macs_mac_address_ipv6s string	The IPv6 addresses associated with the interface. Returned only for instances launched into a VPC. Returned: success Sample: ""
ansible_ec2_network_interfaces_macs_mac_address_local_hostname string	The interface’s local hostname. Returned: success Sample: ""
ansible_ec2_network_interfaces_macs_mac_address_local_ipv4s string	The private IPv4 addresses associated with the interface. Returned: success Sample: ""
ansible_ec2_network_interfaces_macs_mac_address_mac string	The instance’s MAC address. Returned: success Sample: "00:11:22:33:44:55"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: "123456789012"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: "ec2-1-2-3-4.compute-1.amazonaws.com"
ansible_ec2_network_interfaces_macs_mac_address_public_ipv4s string	The Elastic IP addresses associated with the interface. There may be multiple IPv4 addresses on an instance. Returned: success Sample: "1.2.3.4"
ansible_ec2_network_interfaces_macs_mac_address_security_group_ids string	The IDs of the security groups to which the network interface belongs. Returned only for instances launched into a VPC. Returned: success Sample: "sg-01234567,sg-01234568"
ansible_ec2_network_interfaces_macs_mac_address_security_groups string	Security groups to which the network interface belongs. Returned only for instances launched into a VPC. Returned: success Sample: "secgroup1,secgroup2"
ansible_ec2_network_interfaces_macs_mac_address_subnet_id string	The ID of the subnet in which the interface resides. Returned only for instances launched into a VPC. Returned: success Sample: "subnet-01234567"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: "10.0.1.0/24"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: ""
ansible_ec2_network_interfaces_macs_mac_address_vpc_id string	The ID of the VPC in which the interface resides. Returned only for instances launched into a VPC. Returned: success Sample: "vpc-0123456"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: "10.0.0.0/16"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: "10.0.0.0/16"
ansible_ec2_network_interfaces_macs_mac_address_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. Returned: success Sample: ""
ansible_ec2_placement_availability_zone string	The Availability Zone in which the instance launched. Returned: success Sample: "us-east-1a"
ansible_ec2_placement_region string	The Region in which the instance launched. Returned: success Sample: "us-east-1"
ansible_ec2_product_codes string	Product codes associated with the instance, if any. Returned: success Sample: "aw0evgkw8e5c1q413zgy5pjce"
ansible_ec2_profile string	EC2 instance hardware profile. Returned: success 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. Returned: success 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. Returned: success Sample: "1.2.3.4"
ansible_ec2_public_key string	Public key. Only available if supplied at instance launch time. Returned: success Sample: ""
ansible_ec2_ramdisk_id string	The ID of the RAM disk specified at launch time, if applicable. Returned: success Sample: ""
ansible_ec2_reservation_id string	The ID of the reservation. Returned: success 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. Returned: success Sample: "securitygroup1,securitygroup2"
ansible_ec2_services_domain string	The domain for AWS resources for the region; for example, amazonaws.com for us-east-1. Returned: success 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. Returned: success 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. Returned: success Sample: "2015-01-05T18:02:00Z"
ansible_ec2_user_data string	The instance user data. Returned: success Sample: "#!/bin/bash"

Authors

• Silviu Dicu (@silviud)

• Vinay Dandekar (@roadmapper)

Collection links

• Issue Tracker
• Repository (Sources)
• Communication