Access instance metadata for an EC2 instance - Amazon Elastic Compute Cloud
Instance metadata access considerationsAccess instance metadata from within an EC2 instanceQuery instance metadata optionsResponses and error messagesQuery throttling

Access instance metadata for an EC2 instance

You can access EC2 instance metadata from inside of the instance itself or from the EC2 console, API, SDKs, or the AWS CLI. To get the current instance metadata settings for an instance from the console or command line, see Query instance metadata options for existing instances.

You can also modify user data for instances with an EBS root volume. The instance must be in the stopped state. For console directions, see Update the instance user data. For a Linux example that uses the AWS CLI, see modify-instance-attribute. For a Windows example that uses the Tools for Windows PowerShell, see User data and the Tools for Windows PowerShell.

Note

You are not billed for HTTP requests used to retrieve instance metadata and user data.

Instance metadata access considerations

To avoid problems with instance metadata retrieval, consider the following.

Command format

The command format is different, depending on whether you use Instance Metadata Service Version 1 (IMDSv1) or Instance Metadata Service Version 2 IMDSv2. By default, you can use both versions of the Instance Metadata Service. To require the use of IMDSv2, see Use the Instance Metadata Service to access instance metadata.

(IMDSv2) If IMDSv2 is required, IMDSv1 does not work

To check whether IMDSv2 is required, select the instance to view its details. The value for IMDSv2 is either Required (you must use IMDSv2) or Optional (you can use either IMDSv2 or IMDSv1).

(IMDSv2) Use /latest/api/token to retrieve the token

Issuing PUT requests to any version-specific path, for example /2021-03-23/api/token, results in the metadata service returning 403 Forbidden errors. This behavior is intended.

IPv6 support

To retrieve instance metadata using IPv6 address, ensure that you enable and use [fd00:ec2::254] instead of the IPv4 address. The instance must be a Nitro-based instance launched in a subnet that supports IPv6.

(Windows) Create custom AMIs using Windows Sysprep

To ensure that IMDS works when you launch an instance from a custom Windows AMI, the AMI must be a standardized image created with Windows Sysprep. Otherwise, the IMDS won't work. Form more information, see Create an Amazon EC2 AMI using Windows Sysprep.

In a container environment, set the hop limit to 2

The AWS SDKs use IMDSv2 calls by default. If the IMDSv2 call receives no response, the SDK retries the call and, if still unsuccessful, uses IMDSv1. This can result in a delay, especially in a container environment. In a container environment, if the hop limit is 1, the IMDSv2 response does not return because going to the container is considered an additional network hop. To avoid the process of falling back to IMDSv1 and the resultant delay, in a container environment we recommend that you set the hop limit to 2. For more information, see Configure the Instance Metadata Service options.

Metadata version

To avoid having to update your code every time Amazon EC2 releases a new instance metadata build, we recommend that you use latest in the path, and not the version number.

Packets per second (PPS) limit

There is a 1024 packet per second (PPS) limit to services that use link-local addresses. This limit includes the aggregate of Route 53 Resolver DNS Queries, Instance Metadata Service (IMDS) requests, Amazon Time Service Network Time Protocol (NTP) requests, and Windows Licensing Service (for Microsoft Windows based instances) requests.

Additional considerations for user data access

  • User data is treated as opaque data: what you specify is what you get back upon retrieval. It is up to the instance to interpret and act on user data.

  • User data must be base64-encoded. Depending on the tool or SDK that you're using, the base64-encoding might be performed for you. For example:

    • The Amazon EC2 console can perform the base64-encoding for you or accept base64-encoded input.

    • AWS CLI version 2 performs base64-encoding of binary parameters for you by default. AWS CLI version 1 performs the base64-encoding of the --user-data parameter for you.

    • The AWS SDK for Python (Boto3) performs base64-encoding of the UserData parameter for you.

  • User data is limited to 16 KB, in raw form, before it is base64-encoded. The size of a string of length n after base64-encoding is ceil(n/3)*4.

  • User data must be base64-decoded when you retrieve it. If you retrieve the data using instance metadata or the console, it's decoded for you automatically.

  • If you stop an instance, modify its user data, and start the instance, the updated user data is not run automatically when you start the instance. With Windows instances, you can configure settings so that updated user data scripts are run one time when you start the instance or every time you reboot or start the instance.

  • User data is an instance attribute. If you create an AMI from an instance, the instance user data is not included in the AMI.

Access instance metadata from within an EC2 instance

Because your instance metadata is available from your running instance, you do not need to use the Amazon EC2 console or the AWS CLI. This can be helpful when you're writing scripts to run from your instance. For example, you can access the local IP address of your instance from instance metadata to manage a connection to an external application.

All of the following are considered instance metadata, but they are accessed in different ways. Select the tab that represents the type of instance metadata you want to access to see more information.

Metadata

Instance metadata properties are divided into categories. For a description of each instance metadata category, see Instance metadata categories.

To access instance metadata properties from within a running instance, get the data from the following IPv4 or IPv6 URIs. These IP addresses are link-local addresses and are valid only from the instance. For more information, see Link-local addresses.

IPv4

http://169.254.169.254/latest/meta-data/

IPv6

http://[fd00:ec2::254]/latest/meta-data/
Dynamic data

To retrieve dynamic data from within a running instance, use one of the following URIs.

IPv4

http://169.254.169.254/latest/dynamic/

IPv6

http://[fd00:ec2::254]/latest/dynamic/
Examples: Access with cURL

The following examples use cURL to retrieve the high-level instance identity categories.

IMDSv2

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048

IMDSv1

[ec2-user ~]$ curl http://169.254.169.254/latest/dynamic/instance-identity/
rsa2048
pkcs7
document
signature
dsa2048
Examples: Access with PowerShell

The following examples use PowerShell to retrieve the high-level instance identity categories.

IMDSv2

PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature

IMDSv1

PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/dynamic/instance-identity/
document
rsa2048
pkcs7
signature

For more information about dynamic data and examples of how to retrieve it, see Instance identity documents for Amazon EC2 instances.

User data

To retrieve user data from an instance, use one of the following URIs. To retrieve user data using the IPv6 address, you must enable it, and the instance must be a Nitro-based instance in a subnet that supports IPv6.

IPv4

http://169.254.169.254/latest/user-data

IPv6

http://[fd00:ec2::254]/latest/user-data

A request for user data returns the data as it is (content type application/octet-stream). If the instance does not have any user data, the request returns 404 - Not Found.

Examples: Access with cURL to retrieve comma-separated text

The following examples use cURL to retrieve user data that was specified as comma-separated text.

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

curl http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
Examples: Access with PowerShell to retrieve comma-separated text

The following examples use PowerShell to retrieve user data that was specified as comma-separated text.

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} `
-Method PUT -Uri http://169.254.169.254/latest/api/token} -Method GET -uri http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,
Examples: Access with cURL to retrieve a script

The following examples use cURL to retrieve user data that was specified as a script.

IMDSv2

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

IMDSv1

curl http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on
Examples: Access with PowerShell to retrieve a script

The following examples use PowerShell to retrieve user data that was specified as a script.

IMDSv2

[string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token
Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/user-data
<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

IMDSv1

Invoke-RestMethod -uri http://169.254.169.254/latest/user-data
<powershell>
$file = $env:SystemRoot + "\Temp\" + (Get-Date).ToString("MM-dd-yy-hh-mm")
New-Item $file -ItemType file
</powershell>
<persist>true</persist>

Query instance metadata options for existing instances

You can query the instance metadata options for your existing instances by using one of the following methods.

Console
To query the instance metadata options for an existing instance using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances.

  3. Select your instance.

  4. Choose Actions, Instance settings, Modify instance metadata options.

  5. Review the current instance metadata options in the Modify instance metadata options dialog box.

AWS CLI
To query the instance metadata options for an existing instance using the AWS CLI

Use the describe-instances CLI command.

aws ec2 describe-instances \
    --instance-id i-1234567898abcdef0 \
    --query 'Reservations[].Instances[].MetadataOptions'
PowerShell
To query the instance metadata options for an existing instance using the Tools for PowerShell

Use the Get-EC2Instance Cmdlet.

(Get-EC2Instance `
    -InstanceId i-1234567898abcdef0).Instances.MetadataOptions

Responses and error messages

All instance metadata is returned as text (HTTP content type text/plain).

A request for a specific metadata resource returns the appropriate value, or a 404 - Not Found HTTP error code if the resource is not available.

A request for a general metadata resource (the URI ends with a /) returns a list of available resources, or a 404 - Not Found HTTP error code if there is no such resource. The list items are on separate lines, terminated by line feeds (ASCII 10).

For requests made using Instance Metadata Service Version 2, the following HTTP error codes can be returned:

  • 400 - Missing or Invalid Parameters – The PUT request is not valid.

  • 401 - Unauthorized – The GET request uses an invalid token. The recommended action is to generate a new token.

  • 403 - Forbidden – The request is not allowed or the IMDS is turned off.

  • 503 – The request could not be completed. Retry the request.

Query throttling

We throttle queries to the IMDS on a per-instance basis, and we place limits on the number of simultaneous connections from an instance to the IMDS.

If you're using the IMDS to retrieve AWS security credentials, avoid querying for credentials during every transaction or concurrently from a high number of threads or processes, as this might lead to throttling. Instead, we recommend that you cache the credentials until they start approaching their expiry time. For more information about IAM role and security credentials associated with the role, see Retrieve security credentials from instance metadata.

If you are throttled while accessing the IMDS, retry your query with an exponential backoff strategy.