Instance Metadata

Amazon EC2 instances can access instance-specific metadata as well as data supplied when launching the instances. This data can be used to build more generic AMIs that can be modified by configuration files supplied at launch time.

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.

Categories of Available Data

The data available to instances is categorized into metadata and user-supplied data.

Metadata is specific to an instance and is described in the following table.

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 (per AMI).	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.	2007-10-10
block-device-mapping	Defines native device names to use when exposing virtual devices.	2007-10-10
instance-id	The ID of this instance.	1.0
instance-type	The type of instance to launch. For more information, see Instance Types.	2007-08-29
local-hostname	The local hostname of the instance.	2007-01-19
local-ipv4	Public IP address if launched with direct addressing; private IP address if launched with public addressing.	1.0
kernel-id	The ID of the kernel launched with this instance, if applicable.	2008-02-01
placement	The availability zone in which the instance launched.	2008-02-01
product-codes	Product codes associated with this instance.	2007-03-01
public-hostname	The public hostname of the instance.	2007-01-19
public-ipv4	NATted public IP Address	2007-01-19
public-keys/	Public keys. Only available if supplied at instance launch time	1.0
ramdisk-id	The ID of the RAM disk launched with this instance, if applicable.	2008-02-01
reservation-id	ID of the reservation.	1.0
security-groups	Names of the security groups the instance is launched in. Only available if supplied at instance launch time	1.0

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 16K. 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 presented to the instance.

Data Retrieval

An instance retrieves the data by querying a web server using a Query API. The base URI of all requests is http://169.254.169.254/2008-02-01/ where 2008-02-01 indicates the API version.

	Note
	Amazon EC2 Version 1.0 is part of a legacy versioning scheme. Newer versions follow a date based versioning scheme. For more information on the versioning scheme used by Amazon EC2, see API Versioning.

The latest version of the API is always available using the URI http://169.254.169.254/latest.

Security of Launch Data

Although only your specific instance can access launch data, the data is not protected by cryptographic methods. 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.

Retrieving Metadata

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 (i.e. an URI ending 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).

Example

The following examples list HTTP GET requests and responses. You can use a tool such as curl or wget to make these types of requests.

This example gets the available API versions.

GET http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2008-02-01

This example gets the top-level metadata items.

GET http://169.254.169.254/2008-02-01/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-id
instance-type
local-hostname
local-ipv4
placement/
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups

This example gets the value of each metadata item from the preceding example.

GET http://169.254.169.254/2008-02-01/meta-data/ami-manifest-path
my-amis/spamd-image.manifest.xml
GET http://169.254.169.254/2008-02-01/meta-data/ami-manifest-path
my-amis/spamd-image.manifest.xml
GET http://169.254.169.254/2008-02-01/meta-data/ami-id
ami-2bb65342
GET http://169.254.169.254/2008-02-01/meta-data/reservation-id
r-fea54097
GET http://169.254.169.254/2008-02-01/meta-data/hostname
ec2-67-202-51-223.compute-1.amazonaws.com

This example gets the list of available public keys.

GET http://169.254.169.254/2008-02-01/meta-data/public-keys/
0=my-public-key

This example shows the formats in which public key 0 is available.

GET http://169.254.169.254/2008-02-01/meta-data/public-keys/0/
openssh-key

This example gets public key 0 (in openssh-key format).

GET http://169.254.169.254/2008-02-01/meta-data/public-keys/0/openssh-key
ssh-rsa AAAA.....wZEf my-public-key

This example gets the product code.

GET http://169.254.169.254/2008-02-01/meta-data/product-codes
774F4FF8

Retrieving User Data

Requests for the user data returns the data as-is (content type application/x-octetstream).

	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/2008-02-01/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/2008-02-01/user-data
[general]
instances: 4

[instance-0]
s3-bucket: fred

[instance-1]
reboot-on-error: yes

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.

$ 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 2007-08-07T11:29:58+0000 us-east-1c
INSTANCE i-31a74258 ami-2bb65342 pending 1 m1.small 2007-08-07T11:29:58+0000 us-east-1c
INSTANCE i-31a74259 ami-2bb65342 pending 2 m1.small 2007-08-07T11:29:58+0000 us-east-1c
INSTANCE i-31a7425a ami-2bb65342 pending 3 m1.small 2007-08-07T11:29:58+0000 us-east-1c

Once launched, all instances have a copy of the user data and the common metadata shown here:

AMI id: ami-2bb65342
AMI manifest path: ec2-public-images/getting-started.manifest.xml
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

Determine the instance in the launch group.

GET http://169.254.169.254/2008-02-01/meta-data/ami-launch-index
1

Retrieve the user data.

GET http://169.254.169.254/2008-02-01/user-data
          store-size=123PB backup-every=5min | replicate-every=1min | replicate-every=2min | replicate-every=10min | replicate-every=20min

Extract the appropriate part of the user data.

user_data.split('|')[ami_launch_index]