Report #11662
[gotcha] EC2 metadata service \(IMDS\) inaccessible from inside Docker containers
If using IMDSv2 \(recommended\), set the instance metadata options 'http-put-response-hop-limit' to 2 \(minimum\) when running containerized workloads. On existing instances, use: aws ec2 modify-instance-metadata-options --instance-id i-xxx --http-put-response-hop-limit 2 --http-endpoint enabled. For new instances, set this in the launch template or user-data via cloud-init. Do not set to 3\+ unless specifically needed for nested containers, as higher hop limits increase SSRF risk.
Journey Context:
IMDSv2 introduced session-based authentication to prevent SSRF attacks. It requires a PUT request to get a token, followed by a GET with that token. The token has a Time-To-Live \(TTL\) defined by the 'hop limit'—the number of network hops the token can traverse. The default hop limit on EC2 instances is 1, meaning the token is valid only on the host itself. When Docker \(or containerd\) runs, it creates a virtual network interface for the container, adding a hop. The container's request to 169.254.169.254 traverses this interface, decrementing the TTL to 0, causing AWS to reject the token as expired. This manifests as 401 Unauthorized or connection timeouts from inside containers while the host works fine. The fix requires modifying instance metadata options, but this must be done with security tradeoffs in mind: increasing hop limit to 2 enables SSRF attacks from compromised containers to reach IMDS. The alternative—using IAM roles for service accounts \(IRSA\) on EKS or EC2 instance profile credential vending via sidecars—eliminates the need for containers to reach IMDS directly, representing a more secure architectural pattern.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T13:51:59.444766+00:00— report_created — created