US Edition Austin, TX UTC 00:00:00

IMDSv2 on AWS: how to enforce it and set the hop limit for containers

How to require IMDSv2 on EC2, enforce it per Region, and choose hop limit 1 or 2 for containers and EKS, with CLI commands and the audit steps first.

IMDSv2 is the session-based version of the EC2 Instance Metadata Service. To enforce it, set HttpTokens to required on each instance, then lock the setting in with account defaults, an AMI flag and policy. For containers, AWS recommends a hop limit of 2 when IMDSv2 is required, because a container adds one network hop. The sections below cover how the two versions differ, how to find IMDSv1 users before you switch, and where the hop limit trade-off sits. Settings are as documented by AWS in late October 2026.

IMDSv1 vs IMDSv2: what actually differs

Both versions serve the same data at 169.254.169.254 (and [fd00:ec2::254] over IPv6 on Nitro instances where enabled). The difference is how a request is authorised.

  • IMDSv1 is plain request/response. Any process that can send a GET to the address gets the answer, including the temporary credentials of the instance role.
  • IMDSv2 is session-oriented. The caller first sends a PUT to /latest/api/token with a TTL header (1 second to 6 hours), then sends the returned token in an X-aws-ec2-metadata-token header on every GET.

The token is tied to the instance that issued it. AWS also rejects PUT requests that carry an X-Forwarded-For header, which stops many reverse-proxy setups from relaying a token request. The practical effect is that a simple server-side request forgery (SSRF) bug that can only make GET requests no longer reaches the credentials. AWS describes the design in its security blog post on IMDS defence in depth. For the vulnerability class itself, see our Security coverage.

A minimal IMDSv2 call looks like this:

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/meta-data/instance-id

"Optional" vs "required": the HttpTokens setting

Each instance has an HttpTokens value. With optional, IMDSv1 and IMDSv2 both work. With required, IMDSv1 requests fail and a GET without a valid token gets a 401. The console labels this "IMDSv2: Optional" or "Required". By default an instance accepts both unless something else changes it; Amazon Linux 2023 disables IMDSv1 by default, according to the AWS transition guide.

The change on a running instance takes effect immediately and needs no restart:

  1. Run aws ec2 modify-instance-metadata-options --instance-id i-1234567890abcdef0 --http-tokens required --http-endpoint enabled.
  2. Watch for software that breaks (see the next section).
  3. Roll back with --http-tokens optional if needed, unless account-level enforcement is on.

Find IMDSv1 users before you switch

Switching blindly breaks old agents and scripts. AWS suggests this order:

  1. List instances that still allow IMDSv1. Use aws ec2 describe-instances --filters "Name=metadata-options.http-tokens,Values=optional", or the ImdsV1Enabled CloudWatch metric, which reports configuration even when nothing is calling.
  2. Measure real IMDSv1 calls. The MetadataNoToken CloudWatch metric counts IMDSv1 requests per instance. When it stays at zero, the instance is a candidate for required.
  3. Identify the caller. The open-source IMDS Packet Analyzer logs IMDSv1 calls at boot and at runtime.
  4. Update SDKs and CLIs. AWS lists minimum versions that support IMDSv2, including AWS CLI 1.16.289, Boto3 1.12.6, Java SDK v2 2.10.21, Go SDK v1 1.25.38 and Node.js SDK v2 2.722.0 (see the metadata service page for the full list).
  5. Switch and monitor. After you require IMDSv2, MetadataNoTokenRejected counts IMDSv1 attempts that were refused, which points at software still needing an update.

Make IMDSv2 the default for new instances

Fixing existing instances does nothing for the next launch. AWS provides four layers for new ones.

Account defaults per Region

The defaults are set per account and per Region with modify-instance-metadata-defaults. They apply to new instances only; existing ones are untouched.

aws ec2 modify-instance-metadata-defaults --region us-east-1 --http-tokens required --http-put-response-hop-limit 2

Check the result with aws ec2 get-instance-metadata-defaults --region us-east-1. Repeat for every Region you use, or set it centrally with an AWS Organizations declarative policy.

Account-level enforcement

Defaults can still be overridden at launch. Enforcement cannot. With --http-tokens-enforced enabled, an instance that would launch with IMDSv1 enabled fails to launch, and IMDSv1 cannot be switched back on for an instance that has it disabled (until enforcement itself is turned off). Instances already running with IMDSv1 are not changed. Turn it on only after the audit above, because a launch that relies on IMDSv1 will fail.

AMI flag

An AMI registered or modified with --imds-support v2.0 launches instances that require IMDSv2, with a hop limit of 2. AWS warns that this cannot be undone on that AMI; the only reset is a new AMI from the snapshot. Amazon Linux 2023 ships with it set.

Launch templates and policy

Put MetadataOptions with HttpTokens=required in launch templates so Auto Scaling groups start compliant. To stop people from undoing it, use an IAM policy or a service control policy with the condition keys ec2:MetadataHttpTokens, ec2:MetadataHttpPutResponseHopLimit and ec2:MetadataHttpEndpoint. A call that does not match fails with UnauthorizedOperation. A further key, ec2:RoleDelivery set to 2.0, makes API calls fail when they use role credentials that were fetched through IMDSv1.

For auditing, the AWS Config managed rule EC2_IMDSV2_CHECK marks an instance non-compliant when HttpTokens is optional. Related cloud topics are in our Cloud section.

The hop limit and containers

The hop limit is the IP time-to-live on the response to the token PUT. The AWS default is 1, which keeps the token from being forwarded beyond the instance. A container on a bridged or overlay network sits one hop behind the host, so the response to its token request is dropped. With a hop limit of 1 and IMDSv2 required, such a container gets no answer at all.

AWS documents the symptoms. SDKs that fall back to IMDSv1 after a failed token request will slow down, and SDKs that insist on IMDSv2 can fail outright. AWS recommends one of two fixes in its metadata access considerations: pass what the container needs (such as the Region) as configuration, or raise the hop limit to 2.

To change it on an existing instance:

aws ec2 modify-instance-metadata-options --instance-id i-1234567890abcdef0 --http-put-response-hop-limit 2 --http-endpoint enabled

When hop limit 1 is the better choice

A hop limit of 2 lets every container on the node reach the node's role credentials. On Kubernetes that means any pod, including a compromised one. The Amazon EKS best practices guide recommends giving pods their own identity with IAM roles for service accounts or EKS Pod Identity, then blocking pod access to instance metadata by requiring IMDSv2 and setting the hop count to 1. It adds that you should not disable the metadata endpoint, because node components depend on it.

The same guide notes that nodes provisioned by eksctl or the official CloudFormation templates get a hop limit of 2. Check what your node group launch template actually sets rather than assuming. Pods that run in the host network namespace are a separate case, since they share the node's network path, so test them before relying on hop limit 1 alone. Cluster-level cautions like this are also in our Platforms coverage.

A quick decision rule

  • No containers on the instance: required tokens, hop limit 1.
  • Containers that legitimately need instance credentials: required tokens, hop limit 2, accepting that all containers share the role.
  • Kubernetes nodes: pod-level identity, required tokens, hop limit 1, then test every workload.

Frequently asked questions

What is the difference between IMDSv1 and IMDSv2?

IMDSv1 answers any plain GET request. IMDSv2 first requires a PUT to get a short-lived token and then requires that token on every GET, which blocks many SSRF and proxy-based credential thefts.

Does requiring IMDSv2 need a restart?

No. AWS states that you can change this setting on a running instance and it takes effect immediately.

What hop limit should I use for Docker or Kubernetes on EC2?

AWS recommends 2 when IMDSv2 is required and containers must reach the metadata service. If pods should not reach it, use pod-level IAM roles and keep the hop limit at 1.

How do I know if anything still uses IMDSv1?

Watch the MetadataNoToken CloudWatch metric per instance. When it is zero over a representative period, the instance is ready to require IMDSv2.

Can I stop people from turning IMDSv1 back on?

Yes. Enable account-level enforcement with --http-tokens-enforced enabled, or use an IAM policy or SCP on ec2:MetadataHttpTokens.