Use instance metadata to manage your EC2instance
Instance metadata is data about your instance that you can use toconfigure or manage the running instance. Instance metadata includes the following:
- Instance metadata properties
Instance metadata properties are divided intocategories, for example, hostname, events, and security groups.
- Dynamic data
Dynamic data is metadata that's generated when the instance is launched, suchas an instance identity document. For more information, seeDynamic data categories.
- User data
You can also use instance metadata to accessuser datathat you specified when you launched your instance. For example, you can specifyparameters for configuring your instance, or include a simple script. You canalso build generic AMIs and use user data to modify the configuration filessupplied at launch time. For example, if you run web servers for various smallbusinesses, they can all use the same generic AMI and retrieve their contentfrom an Amazon S3 bucket that you specify in the user data at launch. To add a newcustomer at any time, create a bucket for the customer, add their content, andlaunch your AMI with the unique bucket name provided to your code in the userdata. If you launch multiple instances using the same
RunInstancescall, the user data is available to all instances in that reservation. Eachinstance that is part of the same reservation has a uniqueami-launch-indexnumber, so that you can write code thatcontrols what the instances do. For example, the first host might elect itselfas the original node in a cluster. For a detailed AMI launch example, seeIdentify each instance launched in a singlerequest.
Although you can only access instance metadata and user data from within the instanceitself, the data is not protected by authentication or cryptographic methods. Anyone whohas direct access to the instance, and potentially any software running on the instance,can view its metadata. Therefore, you should not store sensitive data, such as passwordsor long-lived encryption keys, as user data.
Contents
Instance metadata categories
Instance metadata properties are divided into categories. To retrieve instancemetadata properties, you specify the category in the request, and the metadata isreturned in the response.
When new categories are released, a new instance metadata build is created with a newversion number. In the following table, theVersion when category wasreleased column specifies the build version when an instance metadatacategory was released. To avoid having to update your code every time Amazon EC2 releases anew instance metadata build, uselatest instead of the version number inyour metadata requests. For more information, seeGet the available versions of the instance metadata.
When Amazon EC2 releases a new instance metadata category, the instance metadata for thenew category might not be available for existing instances. WithNitro-based instances,you can retrieve instance metadata only for the categories that were available atlaunch. For instances with the Xen hypervisor, you canstopand then start the instance to update the categories that are available forthe instance.
The following table lists the categories of instance metadata. Some of the categorynames include placeholders for data that is unique to your instance. For example,mac represents the MAC address for the network interface.You must replace the placeholders with actual values when you retrieve the instancemetadata.
| Category | Description | Version when category was released |
|---|---|---|
ami-id | The AMI ID used to launch the instance. | 1.0 |
ami-launch-index | If you launch multiple instances using the sameRunInstances call, this value indicates the launchorder for each instance. The value of the first instance launched is 0.If you launch instances using Auto Scaling or EC2 fleet, this value isalways 0. | 1.0 |
ami-manifest-path | The path to the AMI manifest file in Amazon S3. If you used anAmazon EBS-backed AMI to launch the instance, the returned result isunknown. | 1.0 |
ancestor-ami-ids | The AMI IDs of any instances that were rebundled to create this AMI.This value will only exist if the AMI manifest file contained anancestor-amis key. | 2007-10-10 |
autoscaling/target-lifecycle-state | Value showing the target Auto Scaling lifecycle state that an Auto Scalinginstance is transitioning to. Present when the instance transitionsto one of the target lifecycle states after March 10, 2022. Possiblevalues: | 2021-07-15 |
block-device-mapping/ami | The virtual device that contains the root/boot file system. | 2007-12-15 |
block-device-mapping/ebsN | The virtual devices associated with any Amazon EBS volumes. Amazon EBS volumesare only available in metadata if they were present at launch time orwhen the instance was last started. TheN indicatesthe index of the Amazon EBS volume (such asebs1 orebs2). | 2007-12-15 |
block-device-mapping/ephemeralN | The virtual devices for any non-NVMe instance store volumes. TheN indicates the index of each volume. Thenumber of instance store volumes in the block device mapping might notmatch the actual number of instance store volumes for the instance. Theinstance type determines the number of instance store volumes that areavailable to an instance. If the number of instance store volumes in ablock device mapping exceeds the number available to an instance, theadditional instance store volumes are ignored. | 2007-12-15 |
block-device-mapping/root | The virtual devices or partitions associated with the root devices orpartitions on the virtual device, where the root (/ or C:) file systemis associated with the given instance. | 2007-12-15 |
block-device-mapping/swap | The virtual devices associated withswap. Not alwayspresent. | 2007-12-15 |
events/maintenance/history | If there are completed or canceled maintenance events for theinstance, contains a JSON string with information about theevents. | 2018-08-17 |
events/maintenance/scheduled | If there are active maintenance events for the instance, contains aJSON string with information about the events. For more information, seeView scheduled events that affect your Amazon EC2 instances. | 2018-08-17 |
events/recommendations/rebalance | The approximate time, in UTC, when the EC2 instance rebalancerecommendation notification is emitted for the instance. The followingis an example of the metadata for this category:{"noticeTime":"2020-11-05T08:22:00Z"}. This category is available onlyafter the notification is emitted. For more information, seeEC2 instance rebalance recommendations. | 2020-10-27 |
hostname | If the EC2 instance is using IP-based naming (IPBN), this is theprivate IPv4 DNS hostname of the instance. If the EC2 instance is usingResource-based naming (RBN), this is the RBN. In cases where multiplenetwork interfaces are present, this refers to the eth0 device (thedevice for which the device number is 0). For more information aboutIPBN and RBN, seeEC2 instance hostnames and domains. | 1.0 |
iam/info | If there is an IAM role associated with the instance, containsinformation about the last time the instance profile was updated,including the instance's LastUpdated date, InstanceProfileArn, andInstanceProfileId. Otherwise, not present. | 2012-01-12 |
iam/security-credentials/ | If there is an IAM role associated with the instance,role-name is the name of the role, androle-name contains the temporary securitycredentials associated with the role (for more information, seeRetrieve security credentials from instance metadata).Otherwise, not present. | 2012-01-12 |
identity-credentials/ec2/info | Information about the credentials inidentity-credentials/ec2/security-credentials/ec2-instance. | 2018-05-23 |
identity-credentials/ec2/security-credentials/ec2-instance | Credentials for the instance identity role that allow on-instancesoftware to identify itself to AWS to support features such asEC2 Instance Connect and AWS Systems Manager Default Host Management Configuration. Thesecredentials have no policies attached, so they have no additional AWSAPI permissions beyond identifying the instance to the AWS feature.For more information, seeInstance identity roles for Amazon EC2 instances. | 2018-05-23 |
instance-action | Notifies the instance that it should reboot in preparation forbundling. Valid values:none |shutdown |bundle-pending. | 2008-09-01 |
instance-id | The ID of this instance. | 1.0 |
instance-life-cycle | The purchasing option of this instance. For more information, seeAmazon EC2 billing and purchasing options. | 2019-10-01 |
instance-type | The type of instance. For more information, seeAmazon EC2 instance types. | 2007-08-29 |
ipv6 | The IPv6 address of the instance. In cases where multiple networkinterfaces are present, this refers to the eth0 device (the device forwhich the device number is 0) network interface and the first IPv6address assigned. If no IPv6 address exists on network interface[0],this item is not set and results in an HTTP 404 response. | 2021-01-03 |
kernel-id | The ID of the kernel launched with this instance, ifapplicable. | 2008-02-01 |
local-hostname | In cases where multiple network interfaces are present, this refersto the eth0 device (the device for which the device number is 0). If theEC2 instance is using IP-based naming (IPBN), this is the private IPv4DNS hostname of the instance. If the EC2 instance is usingResource-based naming (RBN), this is the RBN. For more information aboutIPBN, RBN, and EC2 instance naming, seeEC2 instance hostnames and domains. | 2007-01-19 |
local-ipv4 | The private IPv4 address of the instance. In cases where multiplenetwork interfaces are present, this refers to the eth0 device (thedevice for which the device number is 0). If this is an IPv6-onlyinstance, this item is not set and results in an HTTP 404response. | 1.0 |
mac | The instance's media access control (MAC) address. In cases wheremultiple network interfaces are present, this refers to the eth0 device(the device for which the device number is 0). | 2011-01-01 |
metrics/vhostmd | No longer available. | 2011-05-01 |
network/interfaces/macs/ | The unique device number associated with that interface. The devicenumber corresponds to the device name; for example, adevice-number of 2 is for the eth2 device. Thiscategory corresponds to theDeviceIndex anddevice-index fields that are used by the Amazon EC2 API andthe EC2 commands for the AWS CLI. | 2011-01-01 |
network/interfaces/macs/ | The ID of the network interface. | 2011-01-01 |
network/interfaces/macs/ | The private IPv4 addresses that are associated with each public IPaddress and assigned to that interface. | 2011-01-01 |
network/interfaces/macs/ | The IPv6 addresses assigned to the interface. | 2016-06-30 |
network/interfaces/macs/ | The IPv6 prefix assigned to the network interface. | |
network/interfaces/macs/ | The private IPv4 DNS hostname of the instance. In cases wheremultiple network interfaces are present, this refers to the eth0device (the device for which the device number is 0). If this is aIPv6-only instance, this is the resource-based name. For moreinformation about IPBN and RBN, seeEC2 instance hostnames and domains. | 2007-01-19 |
network/interfaces/macs/ | The private IPv4 addresses associated with the interface. If this isan IPv6-only network interface, this item is not set and results in anHTTP 404 response. | 2011-01-01 |
network/interfaces/macs/ | The instance's MAC address. | 2011-01-01 |
network/interfaces/macs/ | The index of the network card. Some instance types support multiplenetwork cards. | 2020-11-01 |
network/interfaces/macs/ | The ID of the owner of the network interface. In multiple-interfaceenvironments, an interface can be attached by a third party, such asElastic Load Balancing. Traffic on an interface is always billed to the interfaceowner. | 2011-01-01 |
network/interfaces/macs/ | The interface's public DNS (IPv4). This category is only returned iftheenableDnsHostnames attribute is set totrue. For more information, seeDNS attributes for your VPCin theAmazon VPC User Guide. If the instance only has apublic-IPv6 address and no public-IPv4 address, this item is not set andresults in an HTTP 404 response. | 2011-01-01 |
network/interfaces/macs/ | The public IP address or Elastic IP addresses associated with theinterface. There may be multiple IPv4 addresses on an instance. | 2011-01-01 |
network/interfaces/macs/ | Security groups to which the network interface belongs. | 2011-01-01 |
network/interfaces/macs/ | The IDs of the security groups to which the network interfacebelongs. | 2011-01-01 |
network/interfaces/macs/ | The ID of the subnet in which the interface resides. | 2011-01-01 |
network/interfaces/macs/ | The IPv4 CIDR block of the subnet in which the interfaceresides. | 2011-01-01 |
network/interfaces/macs/ | The IPv6 CIDR block of the subnet in which the interfaceresides. | 2016-06-30 |
network/interfaces/macs/ | The ID of the VPC in which the interface resides. | 2011-01-01 |
network/interfaces/macs/ | The primary IPv4 CIDR block of the VPC. | 2011-01-01 |
network/interfaces/macs/ | The IPv4 CIDR blocks for the VPC. | 2016-06-30 |
network/interfaces/macs/ | The IPv6 CIDR block of the VPC in which the interfaceresides. | 2016-06-30 |
placement/availability-zone | The Availability Zone in which the instance launched. | 2008-02-01 |
placement/availability-zone-id | The static Availability Zone ID in which the instance is launched.The Availability Zone ID is consistent across accounts. However, itmight be different from the Availability Zone, which can vary byaccount. | 2019-10-01 |
placement/group-name | The name of the placement group in which the instance islaunched. | 2020-08-24 |
placement/host-id | The ID of the host on which the instance is launched. Applicable onlyto Dedicated Hosts. | 2020-08-24 |
placement/partition-number | The number of the partition in which the instance islaunched. | 2020-08-24 |
placement/region | The AWS Region in which the instance is launched. | 2020-08-24 |
product-codes | AWS Marketplace product codes associated with the instance, if any. | 2007-03-01 |
public-hostname | The instance's public DNS (IPv4). This category is only returned iftheenableDnsHostnames attribute is set totrue. For more information, seeDNS attributes for your VPCin theAmazon VPC User Guide. If the instance only has apublic-IPv6 address and no public-IPv4 address, this item is not set andresults in an HTTP 404 response. | 2007-01-19 |
public-ipv4 | The public IPv4 address. If an Elastic IP address is associated withthe instance, the value returned is the Elastic IP address. | 2007-01-19 |
public-keys/0/openssh-key | Public key. Only available if supplied at instance launchtime. | 1.0 |
ramdisk-id | The ID of the RAM disk specified at launch time, ifapplicable. | 2007-10-10 |
reservation-id | The ID of the reservation. | 1.0 |
security-groups | The names of the security groups applied to the instance. After launch, you can change the security groups of the instances.Such changes are reflected here and innetwork/interfaces/macs/ | 1.0 |
services/domain | The domain for AWS resources for the Region. | 2014-02-25 |
services/partition | The partition that the resource is in. For standard AWS Regions,the partition is | 2015-10-20 |
spot/instance-action | The action (hibernate, stop, or terminate) and the approximatetime, in UTC, when the action will occur. This item is present onlyif the Spot Instance has been marked for hibernate, stop, or terminate. Formore information, seeinstance-action. | 2016-11-15 |
spot/termination-time | The approximate time, in UTC, that the operating system for yourSpot Instance will receive the shutdown signal. This item is present andcontains a time value (for example, 2015-01-05T18:02:00Z) only ifthe Spot Instance has been marked for termination by Amazon EC2. Thetermination-time item is not set to a time if you terminated theSpot Instance yourself. For more information, seetermination-time. | 2014-11-05 |
tags/instance | The instance tags associated with the instance. Only available if youexplicitly allow access to tags in instance metadata. For moreinformation, seeEnable access to tags in instance metadata. | 2021-03-23 |
Dynamic data categories
The following table lists the categories of dynamic data.
| Category | Description | Version when category was released |
|---|---|---|
fws/instance-monitoring | Value showing whether the customer has enabled detailed one-minutemonitoring in CloudWatch. Valid values:enabled |disabled | 2009-04-04 |
instance-identity/document | JSON containing instance attributes, such as instance-id, private IPaddress, etc. SeeInstance identity documents for Amazon EC2 instances. | 2009-04-04 |
instance-identity/pkcs7 | Used to verify the document's authenticity and content against thesignature. SeeInstance identity documents for Amazon EC2 instances. | 2009-04-04 |
instance-identity/signature | Data that can be used by other parties to verify its origin andauthenticity. SeeInstance identity documents for Amazon EC2 instances. | 2009-04-04 |
