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:

user-supplied data

Any 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 may use the AMI launch index metadatum as an index into the data (example).

  • User data is limited to 16K.

  • 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-01-19/ where 2007-01-19 indicates the API version.

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).

ResourceURIExample
Get the available API versions GET http://169.254.169.254/ Request 
GET http://169.254.169.254/
Response 
1.0
2.0
Get the top-level metadata items GET http://169.254.169.254/2007-01-19/meta-data/ Request 
GET http://169.254.169.254/2007-01-19/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-01-19/meta-data/X Request 
GET http://169.254.169.254/2007-01-19/meta-data/ami-manifest-path
Response 
my-amis/spamd-image.manifest.xml
Request 
GET http://169.254.169.254/2007-01-19/meta-data/ami-id
Response 
ami-5bae4b32
Request 
GET http://169.254.169.254/2007-01-19/meta-data/reservation-id
Response 
r-fea54097
Request 
GET http://169.254.169.254/2007-01-19/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-01-19/meta-data/public-keys/ Request 
GET http://169.254.169.254/2007-01-19/meta-data/public-keys/
Response 
0=my-public-key
In which formats is public key 0 available? GET http://169.254.169.254/2007-01-19/meta-data/public-keys/0/ Request 
GET http://169.254.169.254/2007-01-19/meta-data/public-keys/0/
Response 
openssh-key
Get public key 0 (in openssh-key format) GET http://169.254.169.254/2007-01-19/meta-data/public-keys/0/openssh-key Request 
GET http://169.254.169.254/2007-01-19/meta-data/public-keys/0/openssh-key
Response 
ssh-rsa AAAA.....wZEf my-public-key

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

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.
ResourceURIExamples
Get the user-supplied data GET http://169.254.169.254/2007-01-19/user-data Request 
GET http://169.254.169.254/2007-01-19/user-data
Response 
1234,fred,reboot,true | 4512,jimbo, | 173,,,
Request 
GET http://169.254.169.254/2007-01-19/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-01-19/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:

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

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

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

Instance4
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-01-19/meta-data/ami-launch-index
          1

  2. Retrieving the user data: 

    GET http://169.254.169.254/2007-01-19/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 Next