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
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.
- If IMDSv2 is required, IMDSv1 does not work
-
If you use IMDSv1 and receive no response, it's likely that IMDSv2 is required. To check whether IMDSv2 is required, select the instance to view its details. The IMDSv2 value indicates 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
PUTrequests 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. - Metadata version
-
To avoid having to update your code every time Amazon EC2 releases a new instance metadata build, we recommend that you use
latestin the path, and not the version number. - IPv6 support
-
To retrieve instance metadata using an IPv6 address, ensure that you enable and use the IPv6 address of the IMDS
[fd00:ec2::254]instead of the IPv4 address169.254.169.254. 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. For more information, see Create an Amazon EC2 AMI using Windows Sysprep.
- In a container environment, consider reconfiguration or increasing the hop limit to 2
-
The AWS SDKs use IMDSv2 calls by default. If the IMDSv2 call receives no response, some AWS SDKs retry the call and, if still unsuccessful, use IMDSv1. This can result in a delay, especially in a container environment. For those AWS SDKs that require IMDSv2, if the hop limit is 1 in a container environment, the call might not receive a response at all because going to the container is considered an additional network hop.
To mitigate these issues in a container environment, consider changing the configuration to pass settings (such as the AWS Region) directly to the container, or consider increasing the hop limit to 2. For information about the hop limit impact, see Add defense in depth against open firewalls, reverse proxies, and SSRF vulnerabilities with enhancements to the EC2 Instance Metadata Service
. For information about changing the hop limit, see Change the PUT response hop limit. - 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-dataparameter for you.The AWS SDK for Python (Boto3) performs base64-encoding of the
UserDataparameter 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.
Query instance metadata options for existing instances
You can query the instance metadata options for your existing instances.
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).
If an IMDSv1 request receives no response, it's likely that IMDSv2 is required.
For requests made using IMDSv2, the following HTTP error codes can be returned:
-
400 - Missing or Invalid Parameters– ThePUTrequest is not valid. -
401 - Unauthorized– TheGETrequest 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. -
404 - Not Found– The resource is not available or there is no such resource. -
503– The request could not be completed. Retry the request.
If the IMDS returns an error, curl prints the error message
in the output and returns a success status code. The error message is stored in the
TOKEN variable, which causes curl commands that use
the token to fail. If you call curl with the -f
option, it returns an error status code in the event of an HTTP server error. If you
enable error handling, the shell can catch the error and stop the script.
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.
