Modify instance metadata options for existing instances
You can modify the instance metadata options for existing instances.
You can also create an IAM policy that prevents users from modifying the instance metadata options on existing instances. To control which 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.
Note
If a declarative policy was used to configure the instance metadata options, you can't modify them directly within the account. For more information, see Declarative policies in the AWS Organizations User Guide.
Require the use of IMDSv2
Use one of the following methods to modify the instance metadata options on an existing instance to require that IMDSv2 is used when requesting instance metadata. When IMDSv2 is required, IMDSv1 cannot be used.
Note
Before requiring that IMDSv2 is used, ensure that the instance
isn't making IMDSv1 calls. The MetadataNoToken
CloudWatch metric tracks IMDSv1 calls. When
MetadataNoToken records zero IMDSv1 usage for an
instance, the instance is then ready to require IMDSv2.
Restore the use of IMDSv1
When IMDSv2 is required on an instance, using an IMDSv1 request will fail.
When IMDSv2 is optional, then both IMDSv2 and IMDSv1
will work. Therefore, to restore IMDSv1, set IMDSv2 to optional
(httpTokens = optional) using one of the following
methods.
The httpTokensEnforced IMDS property also prevents attempts to enable
IMDSv1 on an existing instance. When enabled for an account in a Region,
an attempt to set httpTokens to optional will result
in an UnsupportedOperation exception. Fore more information, see
Troubleshooting.
Important
If your instance launches are failing due to IMDSv2 enforcement, you have two options to enable launches to succeed:
-
Launch instances as IMDSv2-only – If the software running on the instances uses IMDSv2 only (no dependency on IMDSv1), then you can launch the instances as IMDSv2 only. To do this, configure IMDSv2 only by setting
httpTokens = requiredeither in the launch parameters or in the metadata defaults for the account in the Region. -
Disable enforcement – If your software still depends on IMDSv1, set
httpTokensEnforcedtodisabledfor the account in the Region. For more information, see Enforce IMDSv2 at the account level.
Change the PUT response hop limit
For existing instances, you can change the settings of the PUT
response hop limit.
Currently only the AWS CLI and AWS SDKs support changing the PUT response hop limit.
Enable the IMDS IPv4 and IPv6 endpoints
The IMDS has two endpoints on an instance: IPv4 (169.254.169.254)
and IPv6 ([fd00:ec2::254]). When you enable the IMDS, the IPv4
endpoint is automatically enabled. The IPv6 endpoint remains disabled even if
you launch an instance into an IPv6-only subnet. To enable the IPv6 endpoint,
you need to do so explicitly. When you enable the IPv6 endpoint, the IPv4
endpoint remains enabled.
You can enable the IPv6 endpoint at instance launch or after.
Requirements for enabling the IPv6 endpoint
-
The selected instance type is a Nitro-based instance.
-
The selected subnet supports IPv6, where the subnet is either dual stack or IPv6 only.
Currently only the AWS CLI and AWS SDKs support enabling the IMDS IPv6 endpoint after instance launch.
Turn on access to instance metadata
You can turn on access to instance metadata by enabling the HTTP endpoint of the IMDS on your instance, regardless of which version of the IMDS you are using. You can reverse this change at any time by disabling the HTTP endpoint.
Use one of the following methods to turn on access to instance metadata on an instance.
Turn off access to instance metadata
You can turn off access to instance metadata by disabling the HTTP endpoint of the IMDS on your instance, regardless of which version of the IMDS you are using. You can reverse this change at any time by enabling the HTTP endpoint.
Use one of the following methods to turn off access to instance metadata on an instance.
Allow access to tags in instance metadata
You can allow access to tags in the instance metadata on a running or stopped instance. For each instance, you must explicitly allow access. If access is allowed, instance tag keys must comply with specific character restrictions, otherwise you get an error. For more information, see Enable access to tags in instance metadata.
Troubleshooting
Modifying an IMDSv1-enabled instance fails
Description
You get the following error message:
You can't launch instances with IMDSv1 because httpTokensEnforced is
enabled for this account. Either launch the instance with httpTokens=required or
contact your account owner to disable httpTokensEnforced using the
ModifyInstanceMetadataDefaults API or the account settings in the EC2
console.
Cause
This error is thrown when you attempt to modify an existing instance to be
IMDSv1 enabled (httpTokens = optional) in an
account where the EC2 account settings or an AWS Organization
declarative policy enforces the use of IMDSv2
(httpTokensEnforced = enabled).
Solution
If you require IMDSv1 support on existing instances, you'll need to disable
IMDSv2 enforcement for the account in the Region. To disable
IMDSv2 enforcement, set HttpTokensEnforced to
disabled. For more information, see ModifyInstanceMetadataDefaults in the Amazon EC2 API Reference. If
you prefer to configure this setting using the console, see Enforce IMDSv2 at the account level.
We recommend that you use IMDSv2 only (httpTokens=required). For
more information, see Transition to using Instance Metadata Service Version 2.
