| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Instance Metadata
Amazon EC2 instances can access instance-specific metadata, as well as data supplied when launching the instances, using a specific URI.
You can use this data to build more generic AMIs that can be modified by configuration files supplied at launch time. For example, if you run web servers for various small businesses, they can all use the same AMI and retrieve their content from the Amazon S3 bucket you specify at launch. To add a new customer at any time, simply create a bucket for the customer, add their content, and launch your AMI.
Metadata is divided into categories. For more information about the categories, see Metadata Categories.
Data Retrieval
Retrieve instance metadata from within a running instance using the following: GET
http://169.254.169.254/latest/meta-data/
Security of Launch Data
Although you can only access instance metadata for an instance from the instance itself, the data is not protected by cryptographic methods. Therefore, you should take suitable precautions to protect sensitive data (such as long lived encryption keys).
Note
You are not billed for HTTP requests used to retrieve metadata and user-supplied data.
Metadata Retrieval
Requests for a specific metadata resource returns the appropriate value, or a
404 HTTP error code if the resource is not available. All
metadata is returned as text (content type text/plain).
Requests for a general metadata resource (the URI ends with a
/) return a list of available resources, or a
404 HTTP error code if there is no such resource. The
list items are on separate lines terminated by line feeds (ASCII 10).
Examples
The following examples list HTTP GET requests and responses on Linux instances.
Note
On Windows instances, you can install a tool such as cURL or GNU Wget to request instance metadata.
This example gets the available versions of the instance metadata. These versions do not necessarily correlate with an Amazon EC2 API version.
GET http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
2011-01-01
...
latestThis example gets the top-level metadata items. Some of these items are available only for instances in a VPC. For more information about each of these items, see Metadata Categories.
GET http://169.254.169.254/latest/meta-data/
amiid
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-action
instance-id
instance-type
kernel-id
local-hostname
local-ipv4
ipv4-associations
mac
network/
placement/
public-hostname
public-ipv4
public-keys/
reservation-id
security-groupsThis example gets the value of some of the metadata items from the preceding example.
GET http://169.254.169.254/latest/meta-data/ami-manifest-pathmy-amis/spamd-image.manifest.xmlGET http://169.254.169.254/latest/meta-data/ami-idami-2bb65342GET http://169.254.169.254/latest/meta-data/reservation-idr-fea54097GET http://169.254.169.254/latest/meta-data/hostnameec2-67-202-51-223.compute-1.amazonaws.com
This example gets the list of available public keys.
GET http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-keyThis example shows the formats in which public key 0 is available.
GET http://169.254.169.254/latest/meta-data/public-keys/0/
openssh-keyThis example gets public key 0 (in the OpenSSH key format).
GET http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa AAAA.....wZEf my-public-keyThis example gets the product code (s) associated with the AMI. Product codes are returned one per line.
GET http://169.254.169.254/latest/meta-data/product-codes
774F4FF8
...This example gets an instance's Media Access Control (MAC) address.
GET http://169.254.169.254/latest/meta-data/mac
02:29:96:8f:6a:2dThis example shows the network information available for an Amazon EC2-Classic/NAT instance.
GET http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/
local-hostname
local-ipv4s
mac
public-ipv4s
security-group-ids
subnet-id
subnet-ipv4-cidr-block
vpc-id
vpc-ipv4-cidr-blockThis example gets the subnet ID for an Amazon EC2 instance launched into a VPC.
GET http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7This example shows the network information available for an Amazon EC2-Classic instance (one not running in an Amazon EC2-VPC).
GET http://169.254.169.254/latest/meta-data/network/interfaces/macs/03:15:28:7g:5b:8a/
local-hostname
local-ipv4s
mac
public-ipv4s
public-hostnameUser Data Retrieval
When you launch an instance, you can specify user data,
which is available for all instances in the reservation to retrieve. You can
also add (or modify) user data to Amazon EBS-backed instances when they're
stopped. Requests for the user data returns the data as-is (content type
application/x-octetstream). Many people use user data to configure an instance during launch or even run a configuration script.
Note
All user-supplied data is treated as opaque data; what you give us is what you get back. It is the responsibility of the instance to interpret this data appropriately.
Example
This shows an example of returning comma-separated, user-supplied data.
GET http://169.254.169.254/latest/user-data
1234,fred,reboot,true | 4512,jimbo, | 173,,,
This shows an example of returning line-separated, user-supplied data.
GET http://169.254.169.254/latest/user-data
[general]
instances: 4
[instance-0]
s3-bucket: <user_name>
[instance-1]
reboot-on-error: yesYou can modify the user data for an Amazon EBS-backed instance while the instance is stopped. For more information, see Modifying Attributes of a Stopped Instance.
Use Case: AMI Launch Index Value
In this example, Alice wants to launch four instances of her favorite database AMI with the first acting as master and the remainder acting as replicas.
The master database configuration specifies various database parameters (e.g.,
the size of store) while the replicas' configuration specifies different parameters,
such as the replication strategy. Alice decides to provide this data as an ASCII
string with a pipe symbol (|) delimiting the data for the various
instances:
store-size=123PB backup-every=5min | replicate-every=1min | replicate-every=2min | replicate-every=10min | replicate-every=20min
The store-size=123PB backup-every=5min defines the master
database configuration, replicate-every=1min defines the first
replicant's configuration, replicate-every=2min defines the
second replicant's configuration, and so on.
Alice launches four instances.
PROMPT>ec2-run-instances ami-2bb65342 -n 4 -d "store-size=123PB backup-every=5min | replicate-every=1min | replicate-every=2min | replicate-every=10min | replicate-every=20min"RESERVATION r-fea54097 598916040194 default INSTANCE i-3ea74257 ami-2bb65342 pending 0 m1.small 2010-03-19T13:59:03+0000 us-east-1a aki-94c527fd ari-96c527ff monitoring-disabled ebs INSTANCE i-31a74258 ami-2bb65342 pending 0 m1.small 2010-03-19T13:59:03+0000 us-east-1a aki-94c527fd ari-96c527ff monitoring-disabled ebs INSTANCE i-31a74259 ami-2bb65342 pending 0 m1.small 2010-03-19T13:59:03+0000 us-east-1a aki-94c527fd ari-96c527ff monitoring-disabled ebs INSTANCE i-31a7425a ami-2bb65342 pending 0 m1.small 2010-03-19T13:59:03+0000 us-east-1a aki-94c527fd ari-96c527ff monitoring-disabled ebs
After they're launched, all instances have a copy of the user data and the common metadata shown here (where ami_id represents the latest version of an AMI):
AMI id: ami-id
Reservation ID: r-fea54097
Public keys: none
Security group names: default
Instance type: m1.small
However, each instance has certain unique metadata.
Instance 1
| Metadata | Value |
|---|---|
| instance-id | i-3ea74257 |
| ami-launch-index | 0 |
| public-hostname | ec2-67-202-51-223.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.223 |
| local-hostname | ip-10-251-50-35.ec2.internal |
| local-ipv4 | 10.251.50.35 |
Instance 2
| Metadata | Value |
|---|---|
| instance-id | i-31a74258 |
| ami-launch-index | 1 |
| public-hostname | ec2-67-202-51-224.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.224 |
| local-hostname | ip-10-251-50-36.ec2.internal |
| local-ipv4 | 10.251.50.36 |
Instance 3
| Metadata | Value |
|---|---|
| instance-id | i-31a74259 |
| ami-launch-index | 2 |
| public-hostname | ec2-67-202-51-225.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.225 |
| local-hostname | ip-10-251-50-37.ec2.internal |
| local-ipv4 | 10.251.50.37 |
Instance 4
| Metadata | Value |
|---|---|
| instance-id | i-31a7425a |
| ami-launch-index | 3 |
| public-hostname | ec2-67-202-51-226.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.226 |
| local-hostname | ip-10-251-50-38.ec2.internal |
| local-ipv4 | 10.251.50.38 |
Therefore, an instance can determine its portion of the user-supplied data through the following process.
Metadata Discovery Process
| 1 |
Determine the index in the launch group. GET http://169.254.169.254/latest/meta-data/ami-launch-index 1 |
|
2 |
Retrieve the user data. GET http://169.254.169.254/latest/user-data/ store-size=123PB backup-every=5min | replicate-every=1min | replicate-every=2min | replicate-every=10min | replicate-every=20min |
|
3 |
Extract the appropriate part of the user data. user_data.split('|')[ami_launch_index]
|
Metadata Categories
The data available to instances is categorized into metadata and user-supplied data. The following table lists the categories of metadata.
| Data | Description | Version Introduced |
|---|---|---|
ami-id
| The AMI ID used to launch the instance. | 1.0 |
ami-launch-index
| The index of this instance in the reservation. | 1.0 |
ami-manifest-path
| The manifest path of the AMI with which the instance was launched. | 1.0 |
ancestor-ami-ids
| The AMI IDs of any instances that were rebundled to create this AMI. Will only
exist if the AMI manifest file contained an ancestor-amis
key. | 2007-10-10 |
block-device-mapping/
| Returns the ami, root,
ebs, ephemeral, and
swap files (associated virtual devices) as
described below. | 2007-12-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 Amazon EBS volumes, if any are
present. Only available in metadata if it is present at launch time.
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 associated with ephemeral devices, if any are present. The N indicates the index of the ephemeral volume. | 2007-12-15 |
block-device-mapping/root
| The virtual devices or partitions associated with the root devices or
partitions on the ami 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 |
iam/info
| Returns information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId. | 2012-06-01 |
iam/security-credentials/
| Where role-name is
the name of the IAM role associated with the instance. Returns the
temporary security credentials (AccessKeyId, SecretAccessKey,
SessionToken, and Expiration) associated with the IAM role. | 2012-06-01 |
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-type
| The type of instance. For more information, see Instance Families and Types. | 2007-08-29 |
kernel-id
| The ID of the kernel launched with this instance, if applicable. | 2008-02-01 |
local-hostname
| The local hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which device-number is 0). | 2007-01-19 |
local-ipv4
| The private IP address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which device-number is 0). | 1.0 |
mac
| The instance's MAC address. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which device-number is 0). | 2011-01-01 |
network/interfaces/macs/
| The device-number associated with that interface. Each interface must have a unique device number. The device-number serves as a hint to device naming in the instance; for example, device-number is 2 for the eth2 device. | 2011-01-01 |
network/interfaces/macs/
| The private IPv4 address(es) that are associated with each
public-ip address and assigned to that
interface. | 2011-01-01 |
network/interfaces/macs/
| The interface's local hostname. | 2011-01-01 |
network/interfaces/macs/
| The private IP addresses associated with the interface. | 2011-01-01 |
network/interfaces/macs/
| The instance's Media Access Control
( | 2011-01-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 profile. | 2007-12-15 |
network/interfaces/macs/
| The interface's public hostname. | 2011-01-01 |
network/interfaces/macs/
| The elastic IP addresses associated with the interface. There may be multiple IP addresses on an instance. | 2011-01-01 |
network/interfaces/macs/
| Security groups to which the network interface belongs. | 2011-01-01 |
network/interfaces/macs/
| IDs of the security groups to which the network interface belongs. Returned only for Amazon EC2 instances launched into a VPC. For more information on security groups in EC2-VPC, see Security Groups for Your VPC. | 2011-01-01 |
network/interfaces/macs/
| The ID of the Amazon EC2-VPC subnet in which the interface resides. Returned only for Amazon EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| The CIDR block of the Amazon EC2-VPC subnet in which the interface resides. Returned only for Amazon EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| The ID of the Amazon EC2-VPC in which the interface resides. Returned only for Amazon EC2 instances launched into a VPC. | 2011-01-01 |
placement/availability-zone
| The Availability Zone in which the instance launched. | 2008-02-01 |
product-codes
| Product codes associated with the instance, if any. | 2007-03-01 |
public-hostname
| The public hostname of the instance. Not returned for Amazon EC2 instances launched into a VPC. See Elastic IP Addresses (EIP) for more information. | 2007-01-19 |
public-ipv4
| The public IP 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
| ID of the reservation. | 1.0 |
security-groups
|
The names of the security groups applied to the instance. Note Only Amazon EC2 instances launched into a VPC can have their security groups changed after launch. These changes
will be reflected here and in network/interfaces/macs/
| 1.0 |
You can provide user data when you launch an instance, or when the instance is in a stopped state (for EBS-backed instances). User-supplied data is treated as opaque data: what you give us is what you get back.
Note
All instances launched together get the same user-supplied data. You can use the AMI launch index as an index into the data.
User data is limited to 16 KB. This limit applies to the data in raw form, not base64-encoded form.
The user data must be base64-encoded before being submitted to the API. The API command line tools perform the base64 encoding for you. The data is in base64 and is decoded before being presented to the instance.
For more information about base64 encodings, see
http://tools.ietf.org/html/rfc4648.
Dynamic Data
Amazon EC2 instances can also include dynamic data. Dynamic data is retrieved from
http://169.254.169.254/latest/dynamic/
| Data | Description | Version introduced |
|---|---|---|
fws/instance-monitoring
| Value showing whether the customer has enabled detailed 1-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.. | 2009-04-04 |
instance-identity/pkcs7
| Used to verify the document's authenticity and content against the signature. | 2009-04-04 |
instance-identity/signature
| Data that can be used by other parties to verify its origin and authenticity. | 2009-04-04 |
