Introduction

Containers running on EC2 sometimes need access to instance metadata for region discovery, instance identity, or temporary IAM role credentials. The main challenges are IMDSv2 token requirements, network reachability to the link-local metadata address, and limiting which containers are allowed to access that endpoint.

Understand the IMDSv2 Request Flow

On modern EC2 setups, the metadata service is often configured to require IMDSv2. That means you cannot make a plain GET request and expect it to work. You must fetch a session token first and send that token with later metadata calls.

1TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
2  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
3
4curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
5  http://169.254.169.254/latest/meta-data/instance-id

If the container can reach the metadata endpoint but you skip the token step, the request still fails. That is why reachability and authorization need to be checked separately.

Verify That the Container Can Reach 169.254.169.254

The metadata service lives at the link-local address 169.254.169.254. Some container network modes, host firewall rules, or security controls can block access to that address.

docker run --rm amazonlinux:2023 \
  curl -s -m 1 http://169.254.169.254/latest/meta-data/

If that fails, compare it with a host-network test:

docker run --rm --network host amazonlinux:2023 \
  curl -s -m 1 http://169.254.169.254/latest/meta-data/

If the host-network version works but the default network mode does not, the problem is not IMDS itself. It is your container networking path to the metadata address.

Fetch Role Credentials Carefully

One common use case is retrieving temporary IAM role credentials instead of injecting long-lived access keys into the container. The metadata path exposes the attached role name first, then the credential document.

1ROLE_NAME=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
2  http://169.254.169.254/latest/meta-data/iam/security-credentials/)
3
4curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
5  "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE_NAME"

This is safer than static credentials, but it also means any compromised container with metadata access may be able to assume the instance role. That is why metadata access should be treated as a privilege, not a default.

Use Short Timeouts in Application Code

Metadata lookups should fail quickly when the service is unavailable. Long hangs during startup can make a small network problem look like a larger outage.

1import requests
2
3def get_instance_id():
4    session = requests.Session()
5    token = session.put(
6        "http://169.254.169.254/latest/api/token",
7        headers={"X-aws-ec2-metadata-token-ttl-seconds": "21600"},
8        timeout=1,
9    ).text
10
11    response = session.get(
12        "http://169.254.169.254/latest/meta-data/instance-id",
13        headers={"X-aws-ec2-metadata-token": token},
14        timeout=1,
15    )
16    response.raise_for_status()
17    return response.text
18
19
20print(get_instance_id())

Short timeouts and bounded retries keep the application responsive and make failures easier to diagnose.

Consider the Platform-Specific Alternative

Not every AWS container runtime should use EC2 instance metadata directly. ECS has a task metadata endpoint and task roles. EKS typically uses IAM roles for service accounts. If you copy an EC2-only metadata script into those environments, you may get the wrong behavior or an unnecessary security risk.

That means the right question is often not “how do I reach instance metadata from Docker,” but “what identity source is correct for this platform.”

Restrict Metadata Access to Trusted Workloads

If every container on a host can read instance metadata, every container can potentially fetch the instance role credentials. That increases blast radius significantly.

Practical hardening options include:

1. restricting access with host firewall rules
2. isolating untrusted workloads from the metadata route
3. preferring workload-specific identity solutions where available

Containers that do not need instance identity should not be able to read it by accident.

Common Pitfalls

The most common mistake is using IMDSv1-style GET requests in an environment that requires IMDSv2. Another is assuming Docker networking always exposes the link-local address. Teams also overuse instance metadata in environments where ECS or EKS identity mechanisms are the better fit, and they often forget that broad metadata access effectively broadens access to the instance role.

Summary

• Accessing EC2 metadata from Docker usually requires IMDSv2 token flow.
• Verify network reachability to 169.254.169.254 from the container, not just from the host.
• Prefer temporary role credentials over static keys, but treat metadata access as privileged.
• Use short timeouts and explicit error handling in application code.
• Choose the identity mechanism that matches the AWS runtime instead of assuming EC2 metadata is always the right source.