On an EC2 instance, how does IMDSv2 differ from IMDSv1 at the request level, and what does setting the instance's metadata option HttpTokens to `required` actually enforce?

## What the metadata service is Every EC2 instance can query a link-local HTTP endpoint at `169.254.169.254` (and `fd00:ec2::254` over IPv6) for facts about itself: instance ID, instance type, Availability Zone, network configuration, the user data it was launched with, and — the part that matters — the temporary credentials of the IAM role attached through its instance profile, under `/latest/meta-data/iam/security-credentials/<role-name>`. The AWS SDKs read that path automatically, which is why code on an instance "just has" credentials without any file on disk. That convenience is also the exposure: those credentials are readable by anything that can cause the instance to make an HTTP request to a chosen URL. ## The v1 request ```bash curl http://169.254.169.254/latest/meta-data/instance-id ``` One unauthenticated GET, no headers, no state. Simple, and impossible to distinguish from any other GET the instance might be tricked into making. ## The v2 handshake IMDSv2 introduces a session token: ```bash TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \ -H "X-aws-ec2-metadata-token-ttl-seconds: 21600") curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \ http://169.254.169.254/latest/meta-data/instance-id ``` The TTL header is mandatory on the PUT and sets how long the token stays valid, up to a maximum of six hours (21600 seconds). The token is opaque, bound to that instance, and carries no privileges of its own — it is not a credential you can carry elsewhere; presenting it merely proves the requester was able to complete a local round trip. ## Why those specific choices Each element of the design closes off a way that a request could be issued by something other than software running on the instance: - **It is a PUT, not a GET.** A great many request-forging primitives can only cause a GET with no custom headers, so they cannot obtain a token at all. - **The token must be echoed in a custom request header.** Anything that can control only a URL cannot add headers. - **A token request carrying `X-Forwarded-For` is refused.** That header is what a proxy adds when it forwards someone else's request, so its presence is proof the request is not the instance's own. - **The token response is emitted with a small IP hop limit** (`HttpPutResponseHopLimit`, default 1). Even if a token were somehow requested through the instance, the response packet's TTL expires before it can be routed out to a remote caller. ## Turning it on The metadata behaviour is an instance property, in `MetadataOptions`: - `HttpTokens` — `optional` (both v1 and v2 answered) or `required` (v2 only) - `HttpEndpoint` — `enabled` or `disabled`; disabling it turns the metadata service off entirely, which is the right answer for an instance that needs no instance role - `HttpPutResponseHopLimit` — 1 to 64 - `InstanceMetadataTags` — whether instance tags are readable through IMDS ```bash aws ec2 modify-instance-metadata-options --instance-id i-0123456789abcdef0 \ --http-tokens required --http-endpoint enabled --http-put-response-hop-limit 1 ``` For new instances, set `MetadataOptions` in the launch template so every replacement inherits it, and enforce it at the policy layer with the IAM condition key `ec2:MetadataHttpTokens` on `RunInstances` so nobody can launch an instance in `optional` mode. There is also an account-and-Region-level default (`modify-instance-metadata-defaults`) so newly launched instances start hardened. ## Migrating without breaking things Flipping `HttpTokens` to `required` breaks any client still speaking v1 — an old SDK, a vendored tool, a hand-rolled `curl` in a bootstrap script. The safe order is: update SDKs and agents (all current AWS SDKs and the CLI speak v2 and fall back only when allowed), watch the per-instance CloudWatch metric `MetadataNoToken`, which counts token-less calls, wait for it to sit at zero, then set `required`. AWS has itself been progressively making IMDSv2 the default for newer instance types and launch paths, so a fleet audit is worth doing rather than assuming a uniform starting point. ## The limits of the control IMDSv2 raises the bar for reaching the metadata service from outside the instance. It does nothing about code that is genuinely running on the instance — a compromised process reads credentials either way. The complementary controls are a narrow instance role, disabling the endpoint entirely where no role is needed, and giving individual workloads their own credentials rather than sharing the host's.