Use IMDSv2
You can access instance metadata from a running instance using one of the following methods:
-
Instance Metadata Service Version 1 (IMDSv1) – a request/response method
-
Instance Metadata Service Version 2 (IMDSv2) – a session-oriented method
-
In order to use EC2Launch with IMDSv2, the version must be 1.3.2002730 or later.
By default, you can use either IMDSv1 or IMDSv2, or both. The instance
metadata service distinguishes between IMDSv1 and IMDSv2 requests based
on whether, for any given request, either the PUT
or GET
headers, which are unique to IMDSv2, are present in that request. For more
information, see Add defense in depth against open firewalls, reverse proxies, and SSRF
vulnerabilities with enhancements to the EC2 Instance Metadata
Service
You can configure the instance metadata service on each instance such that local code or users must use IMDSv2. When you specify that IMDSv2 must be used, IMDSv1 no longer works. For more information, see Configure the instance metadata options.
To retrieve instance metadata, see Retrieve instance metadata.
The examples in this section use the IPv4 address of the instance metadata
service: 169.254.169.254
. If you are retrieving instance metadata for
EC2 instances over the IPv6 address, ensure that you enable and use the IPv6 address
instead: fd00:ec2::254
. The IPv6 address of the instance metadata
service is compatible with IMDSv2 commands. The IPv6 address is only accessible on
Instances built on the Nitro System.
How Instance Metadata Service Version 2 works
IMDSv2 uses session-oriented requests. With session-oriented requests, you create a session token that defines the session duration, which can be a minimum of one second and a maximum of six hours. During the specified duration, you can use the same session token for subsequent requests. After the specified duration expires, you must create a new session token to use for future requests.
The following example uses a Linux shell script and IMDSv2 to retrieve the top-level instance metadata items. The example:
-
Creates a session token lasting six hours (21,600 seconds) using the
PUT
request -
Stores the session token header in a variable named
TOKEN
-
Requests the top-level metadata items using the token
You can run two separate commands, or combine them.
Separate commands
First, generate a token using the following command.
[ec2-user ~]$
TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`
Then, use the token to generate top-level metadata items using the following command.
[ec2-user ~]$
curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/
Combined commands
You can store the token and combine the commands. The following example combines the above two commands and stores the session token header in a variable named TOKEN.
If there is an error in creating the token, instead of a valid token, an error message is stored in the variable, and the command will not work.
[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" -v http://169.254.169.254/latest/meta-data/
After you've created a token, you can reuse it until it expires. In the following
example command, which gets the ID of the AMI used to launch the instance, the token
that is stored in $TOKEN
in the previous example is
reused.
[ec2-user ~]$
curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/ami-id
When you use IMDSv2 to request instance metadata, the request must include the following:
-
Use a
PUT
request to initiate a session to the instance metadata service. ThePUT
request returns a token that must be included in subsequentGET
requests to the instance metadata service. The token is required to access metadata using IMDSv2. -
Include the token in all
GET
requests to the instance metadata service. When token usage is set torequired
, requests without a valid token or with an expired token receive a401 - Unauthorized
HTTP error code. For information about changing the token usage requirement, see modify-instance-metadata-options in the Amazon CLI Command Reference.-
The token is an instance-specific key. The token is not valid on other EC2 instances and will be rejected if you attempt to use it outside of the instance on which it was generated.
-
The
PUT
request must include a header that specifies the time to live (TTL) for the token, in seconds, up to a maximum of six hours (21,600 seconds). The token represents a logical session. The TTL specifies the length of time that the token is valid and, therefore, the duration of the session. -
After a token expires, to continue accessing instance metadata, you must create a new session using another
PUT
. -
You can choose to reuse a token or create a new token with every request. For a small number of requests, it might be easier to generate and immediately use a token each time you need to access the instance metadata service. But for efficiency, you can specify a longer duration for the token and reuse it rather than having to write a
PUT
request every time you need to request instance metadata. There is no practical limit on the number of concurrent tokens, each representing its own session. IMDSv2 is, however, still constrained by normal instance metadata service connection and throttling limits. For more information, see Query throttling.
-
HTTP GET
and HEAD
methods are allowed in IMDSv2
instance metadata requests. PUT
requests are rejected if they contain
an X-Forwarded-For header.
By default, the response to PUT
requests has a response hop limit
(time to live) of 1
at the IP protocol level. You can adjust the hop
limit using the modify-instance-metadata-options
command if you need to
make it larger. For example, you might need a larger hop limit for backward
compatibility with container services running on the instance. For more information,
see modify-instance-metadata-options in the Amazon CLI Command Reference.
Transition to using Instance Metadata Service Version 2
Use of Instance Metadata Service Version 2 (IMDSv2) is optional. Instance Metadata Service Version 1 (IMDSv1) will continue to be supported indefinitely. If you choose to migrate to using IMDSv2, we recommend that you use the following tools and transition path.
Tools for helping with the transition to IMDSv2
If your software uses IMDSv1, use the following tools to help reconfigure your software to use IMDSv2.
-
Amazon software: The latest versions of the Amazon SDKs and CLIs support IMDSv2. To use IMDSv2, make sure that your EC2 instances have the latest versions of the Amazon SDKs and CLIs. For information about updating the CLI, see Installing, updating, and uninstalling the Amazon CLI in the Amazon Command Line Interface User Guide.
All Amazon Linux 2 software packages support IMDSv2.
-
CloudWatch: IMDSv2 uses token-backed sessions, while IMDSv1 does not. The
MetadataNoToken
CloudWatch metric tracks the number of calls to the instance metadata service that are using IMDSv1. By tracking this metric to zero, you can determine if and when all of your software has been upgraded to use IMDSv2. For more information, see Instance metrics. -
Updates to EC2 APIs and CLIs: For existing instances, you can use the modify-instance-metadata-options CLI command (or the ModifyInstanceMetadataOptions API) to require the use of IMDSv2. For new instances, you can use the run-instances CLI command (or the RunInstances API) and the
metadata-options
parameter to launch new instances that require the use of IMDSv2.To require the use of IMDSv2 on all new instances launched by Auto Scaling groups, your Auto Scaling groups can use either a launch template or a launch configuration. When you create a launch template or create a launch configuration, you must configure the
MetadataOptions
parameters to require the use of IMDSv2. After you configure the launch template or launch configuration, the Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected.Use the modify-instance-metadata-options CLI command (or the ModifyInstanceMetadataOptions API) to require the use of IMDSv2 on the existing instances, or terminate the instances and the Auto Scaling group will launch new replacement instances with the instance metadata options settings that are defined in the launch template or launch configuration.
-
IAM policies and SCPs: You can use an IAM condition to enforce that IAM users can't launch an instance unless it uses IMDSv2. You can also use IAM conditions to enforce that IAM users can't modify running instances to re-enable IMDSv1, and to enforce that the instance metadata service is available on the instance.
The
ec2:MetadataHttpTokens
,ec2:MetadataHttpPutResponseHopLimit
, andec2:MetadataHttpEndpoint
IAM condition keys can be used to control the use of the RunInstances and the ModifyInstanceMetadataOptions API and corresponding CLI. If a policy is created, and a parameter in the API call does not match the state specified in the policy using the condition key, the API or CLI call fails with anUnauthorizedOperation
response. These condition keys can be used either in IAM policies or Amazon Organizations service control policies (SCPs).Furthermore, you can choose an additional layer of protection to enforce the change from IMDSv1 to IMDSv2. At the access management layer with respect to the APIs called via EC2 Role credentials, you can use a new condition key in either IAM policies or Amazon Organizations service control policies (SCPs). Specifically, by using the policy condition key
ec2:RoleDelivery
with a value of2.0
in your IAM policies, API calls made with EC2 Role credentials obtained from IMDSv1 will receive anUnauthorizedOperation
response. The same thing can be achieved more broadly with that condition required by an SCP. This ensures that credentials delivered via IMDSv1 cannot actually be used to call APIs because any API calls not matching the specified condition will receive anUnauthorizedOperation
error. For example IAM policies, see Work with instance metadata. For more information, see Service Control Policies in the Amazon Organizations User Guide.
Recommended path to requiring IMDSv2 access
Using the above tools, we recommend that you follow this path for transitioning to IMDSv2:
Step 1: At the start
Update the SDKs, CLIs, and your software that use Role credentials on their EC2 instances to IMDSv2-compatible versions. For information about updating the CLI, see Upgrading to the latest version of the Amazon CLI in the Amazon Command Line Interface User Guide.
Then, change your software that directly accesses instance metadata (in other words, that does not use an SDK) using the IMDSv2 requests.
Step 2: During the transition
Track your transition progress by using the CloudWatch metric
MetadataNoToken
. This metric shows the number of calls to the
instance metadata service that are using IMDSv1 on your instances.
For
more information, see Instance metrics.
Step 3: When everything is ready on all instances
Everything is ready on all instances when the CloudWatch metric
MetadataNoToken
records zero IMDSv1
usage.
At this stage, you can do the following:
-
For existing instances: You can require IMDSv2 use through the modify-instance-metadata-options command. You can make these changes on running instances; you do not need to restart your instances.
-
For new instances: When launching a new instance, you can do one of the following:
-
In the Amazon EC2 console launch instance wizard, set Metadata accessible to Enabled and Metadata version to V2. For more information, see Step 3: Configure Instance Details.
-
Use the run-instances command to specify that only IMDSv2 is to be used.
-
Updating instance metadata options for existing instances is available only through the API or Amazon CLI. It is currently not available in the Amazon EC2 console. For more information, see Configure the instance metadata options.
Step 4: When all of your instances are transitioned to IMDSv2
The ec2:MetadataHttpTokens
,
ec2:MetadataHttpPutResponseHopLimit
, and
ec2:MetadataHttpEndpoint
IAM condition keys can be used to
control the use of the RunInstances and the ModifyInstanceMetadataOptions API and corresponding CLI. If a
policy is created, and a parameter in the API call does not match the state
specified in the policy using the condition key, the API or CLI call fails with
an UnauthorizedOperation
response. For example IAM policies, see
Work with instance metadata.