Instance Metadata Service (IMDSv2) for EC2 Credentials

Every EC2 instance can ask a special local endpoint, "who am I and what may I do?"

That endpoint is the Instance Metadata Service (IMDS), reachable at the link-local address 169.254.169.254. When an instance has an attached instance profile, IMDS serves the role's temporary credentials, and the SDK reads them as the last link in the credential chain.

IMDSv2 is the hardened, session-oriented version you should require everywhere.

Recipe

On an EC2 instance with an instance profile, the default client resolves IMDS credentials with no configuration. This is the entire "recipe."

# --- Python (boto3) ---
import boto3
 
# On EC2 with an instance profile, the chain reads IMDSv2 automatically.
s3 = boto3.client("s3", region_name="us-east-1")
print([b["Name"] for b in s3.list_buckets()["Buckets"]])

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
// The default chain reads IMDSv2 automatically as its last link.
const s3 = new S3Client({ region: "us-east-1" });
const out = await s3.send(new ListBucketsCommand({}));
console.log(out.Buckets?.map((b) => b.Name));

When to reach for this:

• Your code runs directly on EC2 (not a container orchestrator with its own role source).
• You want zero credential management - the instance profile supplies everything.
• You need auto-rotating temporary credentials with no secrets on disk.
• You are debugging why an instance is or is not resolving its role.

Working Example

You rarely call IMDS by hand, but seeing the raw IMDSv2 flow explains what the SDK does and why v2 is safer.

IMDSv2 is a two-step handshake: PUT to get a session token, then GET the metadata with that token in a header.

# 1. Get a session token (valid up to 6 hours). The PUT is what v1 lacked.
TOKEN=$(curl -sX PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
 
# 2. Use the token to read the instance-profile credentials.
ROLE=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/iam/security-credentials/)
 
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE"
# -> JSON: AccessKeyId, SecretAccessKey, Token, Expiration

The SDK does exactly this internally, then refreshes before Expiration. You can force the SDK to require v2 and set retry behavior:

# --- Python (boto3) ---
import os
import boto3
from botocore.config import Config
 
# Refuse the insecure v1 fallback at the SDK level.
os.environ["AWS_EC2_METADATA_V1_DISABLED"] = "true"
 
cfg = Config(retries={"max_attempts": 2, "mode": "standard"})
s3 = boto3.client("s3", region_name="us-east-1", config=cfg)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { fromInstanceMetadata } from "@aws-sdk/credential-providers";
 
// Explicit IMDS provider with bounded timeout/retries.
const s3 = new S3Client({
  region: "us-east-1",
  credentials: fromInstanceMetadata({ timeout: 1000, maxRetries: 2 }),
});

What this demonstrates:

• IMDSv2 requires a PUT-issued session token before any metadata read.
• AWS_EC2_METADATA_V1_DISABLED=true makes boto3 refuse the legacy v1 flow.
• SDK v3 exposes the provider directly as fromInstanceMetadata when you want explicit control.
• The credentials are temporary and the SDK refreshes them automatically.

Deep Dive

Why IMDSv2 Exists

IMDSv1 answered a plain GET with credentials.

That made it a target for server-side request forgery (SSRF): if an app could be tricked into fetching an attacker-controlled URL, the attacker could aim it at 169.254.169.254 and exfiltrate the role's credentials.

IMDSv2 closes this by requiring a PUT to mint a session token first, and the token request carries headers (like a low TTL and a hop limit) that a naive proxied GET cannot forge. It defeats the common SSRF and open-proxy shapes that leaked v1 credentials.

The Hop Limit

IMDS responses have a PUT response hop limit - a TTL on the IP packet.

The default of 1 means only the instance itself can reach IMDS. Containers running on the instance add a network hop, so a limit of 1 blocks them.

Set the hop limit to at least 2 when containers on the instance need IMDS credentials:

aws ec2 modify-instance-metadata-options \
  --instance-id i-0123456789abcdef0 \
  --http-tokens required \
  --http-put-response-hop-limit 2

--http-tokens required enforces IMDSv2 at the instance level, rejecting v1 entirely - the strongest posture.

How the SDK Consumes It

The instance-metadata provider is the last link in the credential chain.

It only runs if nothing earlier - env vars, shared files, container credentials - answered. On startup the SDK fetches a token, reads the role name, then reads the credentials, caching them until near expiry. A slow or blocked IMDS endpoint therefore shows up as a startup delay, which is why bounding the timeout matters.

Gotchas

• Hop limit of 1 blocks containers - a containerized app on EC2 cannot reach IMDS. Fix: set --http-put-response-hop-limit 2.
• v1 still allowed - leaving http-tokens optional keeps the SSRF-vulnerable path open. Fix: set --http-tokens required and AWS_EC2_METADATA_V1_DISABLED=true.
• IMDS disabled entirely - http-endpoint disabled means no instance credentials at all. Fix: enable the endpoint, or supply credentials another way.
• Long startup hang - a blocked 169.254.169.254 stalls resolution. Fix: bound the IMDS timeout and retries so failure is fast.
• Assuming IMDS on non-EC2 - containers with their own role source (ECS/EKS) use different providers. Fix: rely on the chain rather than hardcoding IMDS.
• Instance profile missing - no attached profile means IMDS serves no credentials. Fix: attach an instance profile with the needed role.

Alternatives

FAQs

Related

• The Credential Provider Chain, End to End - where IMDS sits as the final link.
• Web Identity Federation & IRSA (EKS) - the container-native alternative to node roles.
• SDK Config Precedence: Env, Profile, Code & Defaults - how a stray env var can shadow IMDS.
• Production Configuration Best Practices - enforcing IMDSv2 across a fleet.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).