Use instance metadata to manage your EC2 instance
Instance metadata is data about your instance that you can use to configure or manage the running instance. Instance metadata includes the following:
- Instance metadata properties
-
Instance metadata properties are divided into categories, for example, host name, events, and security groups.
- Dynamic data
-
Dynamic data is metadata that's generated when the instance is launched, such as an instance identity document. For more information, see Dynamic data categories.
- User data
-
You can also use instance metadata to access user data that you specified when you launched your instance. For example, you can specify parameters for configuring your instance, or include a simple script. You can also build generic AMIs and use user data to modify the configuration files supplied at launch time. For example, if you run web servers for various small businesses, they can all use the same generic AMI and retrieve their content from an Amazon S3 bucket that you specify in the user data at launch. To add a new customer at any time, create a bucket for the customer, add their content, and launch your AMI with the unique bucket name provided to your code in the user data. If you launch multiple instances using the same
RunInstancescall, the user data is available to all instances in that reservation. Each instance that is part of the same reservation has a uniqueami-launch-indexnumber, so that you can write code that controls what the instances do. For example, the first host might elect itself as the original node in a cluster. For a detailed AMI launch example, see Identify each instance launched in a single request.
Important
Although you can only access instance metadata and user data from within the instance itself, the data is not protected by authentication or cryptographic methods. Anyone who has 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 passwords or long-lived encryption keys, as user data.
Contents
Instance metadata categories
Instance metadata properties are divided into categories. To retrieve instance metadata properties, you specify the category in the request, and the metadata is returned in the response.
When new categories are released, a new instance metadata build is created with a new
version number. In the following table, the Version when category was
released column specifies the build version when an instance metadata
category was released. To avoid having to update your code every time Amazon EC2 releases a
new instance metadata build, use latest instead of the version number in
your metadata requests. For more information, see Get the available versions of the instance metadata.
When Amazon EC2 releases a new instance metadata category, the instance metadata for the new category might not be available for existing instances. With Nitro-based instances, you can retrieve instance metadata only for the categories that were available at launch. For instances with the Xen hypervisor, you can stop and then start the instance to update the categories that are available for the instance.
The following table lists the categories of instance metadata. Some of the category
names 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 instance
metadata.
| 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 same
RunInstances call, this value indicates the launch
order for each instance. The value of the first instance launched is 0.
If you launch instances using Auto Scaling or EC2 fleet, this value is
always 0. |
1.0 |
ami-manifest-path
|
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. |
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 an
ancestor-amis key. |
2007年10月10日 |
autoscaling/target-lifecycle-state |
Value showing the target Auto Scaling lifecycle state that an Auto Scaling
instance is transitioning to. Present when the instance transitions
to one of the target lifecycle states after March 10, 2022. Possible
values: |
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 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). |
2007年12月15日 |
block-device-mapping/ephemeralN
|
The virtual devices for any non-NVMe instance store volumes. The N indicates the index of each volume. The number of instance store volumes in the block device mapping might not match the actual number of instance store volumes for the instance. The instance type determines the number of instance store volumes that are available to an instance. If the number of instance store volumes in a block device mapping exceeds the number available to an instance, the additional instance store volumes are ignored. | 2007年12月15日 |
block-device-mapping/root
|
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. | 2007年12月15日 |
block-device-mapping/swap
|
The virtual devices associated with swap. Not always
present. |
2007年12月15日 |
events/maintenance/history |
If there are completed or canceled maintenance events for the instance, contains a JSON string with information about the events. | 2018年08月17日 |
events/maintenance/scheduled |
If there are active maintenance events for the instance, contains a JSON string with information about the events. For more information, see View scheduled events that affect your Amazon EC2 instances. | 2018年08月17日 |
events/recommendations/rebalance |
The approximate time, in UTC, when the EC2 instance rebalance
recommendation notification is emitted for the instance. The following
is an example of the metadata for this category: {"noticeTime":
"2020-11-05T08:22:00Z"}. This category is available only
after the notification is emitted. For more information, see EC2 instance rebalance recommendations. |
2020年10月27日 |
hostname |
If the EC2 instance is using IP-based naming (IPBN), this is the private IPv4 DNS hostname of the instance. If the EC2 instance is using Resource-based naming (RBN), this is the RBN. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). For more information about IPBN and RBN, see EC2 instance hostnames and domains. | 1.0 |
iam/info
|
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. | 2012年01月12日 |
iam/security-credentials/
|
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 (for more information, see Retrieve security credentials from instance metadata).
Otherwise, not present. |
2012年01月12日 |
identity-credentials/ec2/info |
Information about the credentials in
identity-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-instance software to identify itself to AWS to support features such as EC2 Instance Connect and AWS Systems Manager Default Host Management Configuration. These credentials have no policies attached, so they have no additional AWS API permissions beyond identifying the instance to the AWS feature. For more information, see Instance identity roles for Amazon EC2 instances. | 2018年05月23日 |
instance-action |
Notifies the instance that it should reboot in preparation for
bundling. 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, see Amazon EC2 billing and purchasing options. | 2019年10月01日 |
instance-type
|
The type of instance. For more information, see Amazon EC2 instance types. | 2007年08月29日 |
ipv6
|
The IPv6 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) network interface and the first IPv6 address 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, if applicable. | 2008年02月01日 |
local-hostname
|
In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If the EC2 instance is using IP-based naming (IPBN), this is the private IPv4 DNS hostname of the instance. If the EC2 instance is using Resource-based naming (RBN), this is the RBN. For more information about IPBN, RBN, and EC2 instance naming, see EC2 instance hostnames and domains. | 2007年01月19日 |
local-ipv4
|
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). If this is an IPv6-only instance, this item is not set and results in an HTTP 404 response. | 1.0 |
mac
|
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). | 2011年01月01日 |
metrics/vhostmd |
No longer available. | 2011年05月01日 |
network/interfaces/macs/
|
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. |
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 IP address 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 where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0). If this is a IPv6-only instance, this is the resource-based name. For more information about IPBN and RBN, see EC2 instance hostnames and domains. |
2007年01月19日 |
network/interfaces/macs/
|
The private IPv4 addresses associated with the interface. If this is an IPv6-only network interface, this item is not set and results in an HTTP 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 multiple network cards. | 2020年11月01日 |
network/interfaces/macs/
|
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. | 2011年01月01日 |
network/interfaces/macs/
|
The interface's public DNS (IPv4). This category is only returned if
the enableDnsHostnames attribute is set to
true. For more information, see DNS attributes for your VPC
in the Amazon VPC User Guide. If the instance only has a
public-IPv6 address and no public-IPv4 address, this item is not set and
results in an HTTP 404 response. |
2011年01月01日 |
network/interfaces/macs/
|
The public IP address or Elastic IP addresses associated with the interface. 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 interface belongs. | 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 interface resides. | 2011年01月01日 |
network/interfaces/macs/
|
The IPv6 CIDR block of the subnet in which the interface resides. | 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 interface resides. | 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, it might be different from the Availability Zone, which can vary by account. | 2019年10月01日 |
placement/group-name
|
The name of the placement group in which the instance is launched. | 2020年08月24日 |
placement/host-id
|
The ID of the host on which the instance is launched. Applicable only to Dedicated Hosts. | 2020年08月24日 |
placement/partition-number
|
The number of the partition in which the instance is launched. | 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 if
the enableDnsHostnames attribute is set to
true. For more information, see DNS attributes for your VPC
in the Amazon VPC User Guide. If the instance only has a
public-IPv6 address and no public-IPv4 address, this item is not set and
results in an HTTP 404 response. |
2007年01月19日 |
public-ipv4
|
The public IPv4 address. If an Elastic IP address is associated with the 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 launch time. | 1.0 |
ramdisk-id
|
The ID of the RAM disk specified at launch time, if applicable. | 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 in
network/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 approximate time, in UTC, when the action will occur. This item is present only if the Spot Instance has been marked for hibernate, stop, or terminate. For more information, see instance-action. |
2016年11月15日 |
spot/termination-time
|
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 (for example, 2015年01月05日T18:02:00Z) 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. For more information, see termination-time. |
2014年11月05日 |
tags/instance |
The instance tags associated with the instance. Only available if you explicitly allow access to tags in instance metadata. For more information, see Enable 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-minute
monitoring in CloudWatch. Valid values: enabled |
disabled |
2009年04月04日 |
instance-identity/document
|
JSON containing instance attributes, such as instance-id, private IP address, etc. See Instance identity documents for Amazon EC2 instances. | 2009年04月04日 |
instance-identity/pkcs7
|
Used to verify the document's authenticity and content against the signature. See Instance identity documents for Amazon EC2 instances. | 2009年04月04日 |
instance-identity/signature
|
Data that can be used by other parties to verify its origin and authenticity. See Instance identity documents for Amazon EC2 instances. | 2009年04月04日 |
Warning Javascript is disabled or is unavailable in your browser.
To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.