Prev Next

Using Instance Data

Introduction

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

Example Scenario

Perhaps you run web servers for various Mom-and-Pop stores. All the instances use the same AMI. At launch time you could specify which Amazon S3 bucket the AMI should retrieve its content from. This allows you to launch multiple Mom-and-Pop sites serving different content using the same AMI by doing the following:

Categories of Available Data

The data available to instances is categorized into

metadata

This data is specific to an instance. Currently we provide:

DataDescriptionVersion Introduced
ami-idThe AMI id the instance was launched with.1.0
ami-manifest-pathThe manifest path of the AMI the instance was launched with.1.0
ami-launch-indexThe index of this instance in the reservation (per AMI).1.0
instance-idThe id of this instance.1.0
hostnameThe local hostname of this instance. Deprecated as of 2007-01-19, use local-hostname instead.1.0
local-hostnameThe local hostname of the instance.2007-01-19
public-hostnameThe public hostname of the instance.2007-01-19
local-ipv4Public IP address if launched with direct addressing, private IP address if launched with public addressing.1.0
public-ipv4NATted public IP Address2007-01-19
public-keys/Public keys. Only available if supplied at instance launch time1.0
reservation-idId of the reservation.1.0
security-groupsNames of the security groups the instance is launched in. Only available if supplied at instance launch time1.0
product-codesProduct codes associated with this instance. 2007-03-01

user-supplied data

Any user-supplied data is treated as opaque data: what you give us is what you get back.

[Note]Note

  • All instances launched together get the same user-supplied data. You may use the AMI launch index as an index into the data (example).

  • 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 will be base64 decoded before being presented to the instance.

Retrieving the Data

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

[Note]Note

Version 1.0 is part of a legacy versioning scheme. Newer versions follow a date based versioning scheme. See the section called “API Versioning” for more information on the versioning scheme used by Amazon EC2.

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

Although this data is only accessible by your specific instance, the data is not protected by cryptographic methods. You should take suitable precautions to protect sensitive data (such as long lived encryption keys).

You are not billed for these HTTP requests.

Requests for a specific metadatum 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 metadatum resource (i.e. an URI ending with a /) return a list of the resources available at that level or a 404 HTTP error code if there is no such resource. The list items are on separate lines with lines terminated by any combination of linefeed (ASCII 10) and carriage return (ASCII 13).

Resource & URIExample

Get the available API versions

GET http://169.254.169.254/

 Request 
GET http://169.254.169.254/
Response 
1.0
2007-03-01

Get the top-level metadata items

GET http://169.254.169.254/2007-03-01/meta-data/

 Request 
GET http://169.254.169.254/2007-03-01/meta-data/
Response 
ami-id
ami-launch-index
ami-manifest-path
instance-id
hostname
local-ipv4
public-keys/
reservation-id
security-groups

Get the value of metadatum X (where 'X' is from the above list)

GET http://169.254.169.254/2007-03-01/meta-data/X

 Request 
GET http://169.254.169.254/2007-03-01/meta-data/ami-manifest-path
Response 
my-amis/spamd-image.manifest.xml
Request 
GET http://169.254.169.254/2007-03-01/meta-data/ami-id
Response 
ami-5bae4b32
Request 
GET http://169.254.169.254/2007-03-01/meta-data/reservation-id
Response 
r-fea54097
Request 
GET http://169.254.169.254/2007-03-01/meta-data/hostname
Response 
domU-12-34-31-00-00-05.usma1.compute.amazonaws.com

Get the list of available public keys

GET http://169.254.169.254/2007-03-01/meta-data/public-keys/

 Request 
GET http://169.254.169.254/2007-03-01/meta-data/public-keys/
Response 
0=my-public-key

In which formats is public key 0 available?

GET http://169.254.169.254/2007-03-01/meta-data/public-keys/0/

 Request 
GET http://169.254.169.254/2007-03-01/meta-data/public-keys/0/
Response 
openssh-key

Get public key 0 (in openssh-key format)

GET http://169.254.169.254/2007-03-01/meta-data/public-keys/0/openssh-key

 Request 
GET http://169.254.169.254/2007-03-01/meta-data/public-keys/0/openssh-key
Response 
ssh-rsa AAAA.....wZEf my-public-key

Get product codes

GET http://169.254.169.254/2007-03-01/meta-data/product-codes

 Request 
GET http://169.254.169.254/2007-03-01/meta-data/product-codes
Response 
774F4FF8

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

[Note]Note

As mentioned previously, all user-supplied data is treated as opaque data: what you give us is what you get back. It is thus the responsibility of the instance to interpret this data appropriately.

Resource & URIExamples

Get the user-supplied data

GET http://169.254.169.254/2007-03-01/user-data

 Request 
GET http://169.254.169.254/2007-03-01/user-data
Response 
1234,fred,reboot,true | 4512,jimbo, | 173,,,
Request 
GET http://169.254.169.254/2007-03-01/user-data
Response 
[general]
instances: 4

[instance-0]
s3-bucket: fred

[instance-1]
reboot-on-error: yes
Request 
GET http://169.254.169.254/2007-03-01/user-data
Response 
GIF89aXfgs13qa....

Example of Using the AMI Launch Index Value

Alice wants four instances of her favorite database AMI. The first instance will be the master with the remainder acting as replicants.

The master database configuration specifies various database parameters (the size of store, say) while the replicants' configuration specifies different parameters (replication strategy say). Alice decides to provide this data as an ASCII string with | delimiting the various instances' data: 

store-size=123PB backup-every=5min | replicate-every=1min | replicate-every=2min | replicate-every=10min | replicate-every=20min

The example above breaks down as follows

Alice launches her instances: 

$ ec2-run-instances ami-5bae4b32 -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-5bae4b32 pending 0
INSTANCE i-31a74258 ami-5bae4b32 pending 1
INSTANCE i-31a74259 ami-5bae4b32 pending 2
INSTANCE i-31a7425a ami-5bae4b32 pending 3

Note that only 4 instances were launched.

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

However each instance has certain unique metadata:

Instance 1

MetadatumValue
instance-idi-3ea74257
ami-launch-index0
hostnamedomU-12-43-33-00-01-27.usma1.compute.amazonaws.com
local-ipv4216.182.228.87

Instance 2

MetadatumValue
instance-idi-31a74258
ami-launch-index1
hostnamedomU-12-31-33-00-01-72.usma1.compute.amazonaws.com
local-ipv4216.182.228.88

Instance 3

MetadatumValue
instance-idi-31a74259
ami-launch-index2
hostnamedomU-12-31-33-00-01-73.usma1.compute.amazonaws.com
local-ipv4216.182.228.89

Instance 4

MetadatumValue
instance-idi-31a7425a
ami-launch-index3
hostnamedomU-12-31-33-00-01-74.usma1.compute.amazonaws.com
local-ipv4216.182.228.90

Therefore an instance can determine its portion of the user-supplied data by the simple process of

  1. Determining which instance in the launch group it is: 

    GET http://169.254.169.254/2007-03-01/meta-data/ami-launch-index
          1

  2. Retrieving the user data: 

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

  3. Extracting the appropriate part of the user data: 

    user_data.split('|')[ami_launch_index]

Prev Copyright Information Next
 Home