← all posts

AWS IMDSv1 To IMDSv2 Migration

August 7, 2025
AWS IMDSv1 To IMDSv2 Migration

IMDSv2 is the safer version of the EC2 Instance Metadata Service. The main change is session-oriented access: callers first request a token with PUT, then use that token when requesting metadata.

This reduces the risk of open metadata access through SSRF-style paths and makes metadata access more deliberate.

The migration sounds like a toggle, but in practice it is a compatibility rollout across launch templates, SDK versions, bootstrap scripts, and container networking.

Token Reuse

You can create a new token for every metadata request, but that is inefficient. For most workloads, request a token with a sensible TTL and reuse it during the process lifetime.

There is no practical limit on concurrent tokens, but normal IMDS throttling and connection limits still apply. Treat token creation as a local optimization problem, not as an unlimited control plane.

That detail matters because some teams misread "session token" as "scarce shared resource." It is not. The real risk is compatibility and request behavior, not token exhaustion.

Metadata Option Precedence

Metadata options are resolved at instance launch. The order matters:

  1. Instance launch configuration or launch template.
  2. Account-level regional settings.
  3. AMI configuration.

This means an account default does not always win. If a launch template explicitly allows IMDSv1, that instance-level configuration can override the account-level preference.

This is one of the reasons migrations stall. Security teams set an account preference and assume the fleet is covered. Old launch templates quietly keep the old behavior alive.

Container Hop Limit

Containerized workloads often need a higher metadata hop limit. A host process may work with hop limit 1, while a container path may require 2 because the request crosses an extra network hop.

When IMDSv2 migrations break only container workloads, check the hop limit before assuming the SDK is broken. In many cases the host path works and only the container path fails because the request crosses one extra hop.

SDK Compatibility

Older SDKs and CLI versions may not support IMDSv2 correctly. Before enforcing IMDSv2, inventory the versions used by applications, bootstrap scripts, agents, and maintenance tooling.

Examples of minimum versions include:

  1. AWS CLI 1.16.289 or later.
  2. Boto3 1.12.6 or later.
  3. Botocore 1.13.25 or later.
  4. AWS SDK for Java 1.11.678 or Java 2.x 2.10.21 or later.

The exact estate matters more than the table. Find what is actually running.

The hidden offenders are often not the main application. They are bootstrap scripts, old agents, patching tools, or legacy AMIs that never got dependency upgrades.

Migration Pattern

  1. Inventory instances and launch templates.
  2. Check application SDK versions.
  3. Test IMDSv2 required mode on non-production.
  4. Adjust hop limit for container hosts.
  5. Set account-level defaults.
  6. Update launch templates.
  7. Enforce HttpTokens=required.

If you need a practical rollout shape, make the policy and the templates converge first, then enforce. Enforcing before inventory usually turns into a noisy break/fix exercise.

Operational Note

For fleet management, encode the settings in configuration management rather than applying them manually. Ansible, Systems Manager, launch templates, AMIs, and account settings should all agree.

IMDSv2 migration is not just a security toggle. It is a compatibility rollout across applications, agents, images, templates, and runtime environments.

;