Configure the instance metadata options
Instance metadata options allow you to configure new or existing instances to do the following:
-
Require the use of IMDSv2 when requesting instance metadata
-
Specify the
PUT
response hop limit -
Turn off access to instance metadata
You can also use IAM condition keys in an IAM policy or SCP to do the following:
-
Allow an instance to launch only if it's configured to require the use of IMDSv2
-
Restrict the number of allowed hops
-
Turn off access to instance metadata
You should proceed cautiously and conduct careful testing before making any changes. Take note of the following:
-
If you enforce the use of IMDSv2, applications or agents that use IMDSv1 for instance metadata access will break.
-
If you turn off all access to instance metadata, applications or agents that rely on instance metadata access to function will break.
-
For IMDSv2, you must use
/latest/api/token
when retrieving the token.
Topics
Configure instance metadata options for new instances
You can require the use of IMDSv2 on an instance when you launch it. You can also create an IAM policy that prevents users from launching new instances unless they require IMDSv2 on the new instance.
To enforce the use of IMDSv2 on all new instances
To ensure that IAM users can only launch instances that require the use of IMDSv2 when requesting instance metadata, you can specify that the condition to require IMDSv2 must be met before an instance can be launched. For the example IAM policy, see Work with instance metadata.
Configure IPv4 and IPv6 endpoints
By default, the IPv6 endpoint is disabled. This is true even if you are launching an instance into an IPv6-only subnet. You can choose to enable this endpoint at instance launch. The IPv6 endpoint for IMDS is only accessible on Instances built on the Nitro System. For more information about the metadata options, see run-instances in the AWS CLI command reference. The following example shows you how to enable the IPv6 endpoint for IMDS:
aws ec2 run-instances --image-id
ami-0abcdef1234567890
--instance-typet3.large
... --metadata-options "HttpEndpoint=enabled,HttpProtocolIpv6=enabled"
Modify instance metadata options for existing instances
You can require the use IMDSv2 on an existing instance. You can also change the PUT response hop limit and turn off access to instance metadata on an existing instance. You can also create an IAM policy that prevents users from modifying the instance metadata options on an existing instance.
Currently only the AWS SDK or AWS CLI support modifying the instance metadata options on existing instances. You can't use the Amazon EC2 console for modifying instance metadata options.
To require the use of IMDSv2
You can opt in to require that IMDSv2 is used when requesting instance
metadata. Use the modify-instance-metadata-options CLI command
and set the http-tokens
parameter to required
. When
you specify a value for http-tokens
, you must also set
http-endpoint
to enabled
.
aws ec2 modify-instance-metadata-options \ --instance-id
i-1234567898abcdef0
\ --http-tokens required \ --http-endpoint enabled
To change the PUT response hop limit
For existing instances, you can change the settings of the PUT
response hop limit. Use the modify-instance-metadata-options CLI command
and set the http-put-response-hop-limit
parameter to the required
number of hops. In the following example, the hop limit is set to
3
. Note that when specifying a value for
http-put-response-hop-limit
, you must also set
http-endpoint
to enabled
.
aws ec2 modify-instance-metadata-options \ --instance-id
i-1234567898abcdef0
\ --http-put-response-hop-limit3
\ --http-endpoint enabled
To restore the use of IMDSv1 on an instance using IMDSv2
You can use the modify-instance-metadata-options CLI command
with http-tokens
set to optional
to restore the use of
IMDSv1 when requesting instance metadata.
aws ec2 modify-instance-metadata-options \ --instance-id
i-1234567898abcdef0
\ --http-tokens optional \ --http-endpoint enabled
To turn on the IPv6 endpoint for your instance
By default, the IPv6 endpoint is disabled. This is true even if you have launched an instance into an IPv6-only subnet. The IPv6 endpoint for IMDS is only accessible on Instances built on the Nitro System. For more information about the metadata options, see modify-instance-metadata-options in the AWS CLI command reference. The following example shows you how to turn on the IPv6 endpoint for the instance metadata service.
aws ec2 modify-instance-metadata-options \ --instance-id
i-1234567898abcdef0
\ --http-protocol-ipv6 enabled \ --http-endpoint enabled
To turn off access to instance metadata
You can turn off access to your instance metadata by disabling the HTTP
endpoint of the instance metadata service, regardless of which version of the
instance metadata service you are using. You can reverse this change at any time
by enabling the HTTP endpoint. Use the modify-instance-metadata-options CLI command
and set the http-endpoint
parameter to
disabled
.
aws ec2 modify-instance-metadata-options \ --instance-id
i-1234567898abcdef0
\ --http-endpoint disabled
To control the use of modify-instance-metadata-options
To control which IAM users can modify the instance metadata options, specify a policy that prevents all users other than users with a specified role to use the ModifyInstanceMetadataOptions API. For the example IAM policy, see Work with instance metadata.