AWS IMDS: Instance Metadata Service (IMDSv2)

Prerequisites

• A running Spinifex cluster (see Setting Up Your Cluster)
• A running instance to query from
• For IAM role credentials: an instance launched with --iam-instance-profile

Instructions

Using IMDS from a Guest

All commands in this section run inside the guest VM.

Get a Session Token

Request a token with a TTL between 1 and 21600 seconds (6 hours):

TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

The token endpoint only accepts PUT — a GET returns 405 Method Not Allowed. A missing or out-of-range TTL header returns 400 Bad Request.

Read Metadata

Send the token back in the X-aws-ec2-metadata-token header on every read:

curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/instance-id

i-0a1b2c3d4e5f67890

Directory paths (ending in /) return a newline-separated listing of children:

curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/

One-Liner Pattern

For scripts, mint a short-lived token inline:

imds() {
  local token=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
    -H "X-aws-ec2-metadata-token-ttl-seconds: 60")
  curl -s -H "X-aws-ec2-metadata-token: $token" "http://169.254.169.254/latest/$1"
}

imds meta-data/instance-id
imds meta-data/local-ipv4
imds meta-data/placement/availability-zone

Metadata Paths

GET / lists supported API versions (2021-07-15, latest). Any dated version segment (e.g. /2016-09-02/..., as probed by cloud-init) aliases to /latest.

Commonly used paths under /latest/meta-data/:

The network/interfaces/macs/ subtree covers the primary interface only; querying another MAC returns 404 (multi-ENI metadata is deferred).

Paths that intentionally return 404: tags/instance/*, block-device-mapping/*, placement/{group-name,partition-number,availability-zone-id,host-id}, instance-action, and spot/{instance-action,termination-time} (404 is the correct "no interruption scheduled" answer for spot pollers).

User Data

User data supplied at launch (run-instances --user-data) is served at:

curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/user-data

Returns the decoded user data, or 404 if the instance was launched without any. cloud-init consumes this automatically at first boot.

IAM Role Credentials

Instances launched with an IAM instance profile get short-lived, auto-rotating credentials through IMDS — no static keys baked into the image. Creating roles and instance profiles is covered in IAM Roles and Instance Profiles. These are the same temporary credentials STS issues, delivered to the guest automatically instead of through an explicit assume-role call.

# Discover the role name
ROLE=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/iam/security-credentials/)

# Fetch credentials
curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  "http://169.254.169.254/latest/meta-data/iam/security-credentials/$ROLE"

{
  "Code": "Success",
  "LastUpdated": "2026-07-03T10:00:00Z",
  "Type": "AWS-HMAC",
  "AccessKeyId": "ASIA1A2B3C4D5E6F7890",
  "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "Token": "IQoJb3JpZ2luX2VjE...",
  "Expiration": "2026-07-03T11:00:00Z",
  "AccountId": "000000000001"
}

Credentials are ASIA-prefixed temporary STS credentials valid for 1 hour, re-minted automatically 5 minutes before expiry. The AWS SDKs and CLI pick them up with no configuration:

# Inside the guest, with no ~/.aws/credentials:
aws sts get-caller-identity

If the instance has no profile, the whole iam/ subtree returns 404 (and is omitted from the meta-data/ listing).

Instance Identity Document

An unsigned identity document (schema 2017-09-30) is available at:

curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/dynamic/instance-identity/document

{
  "accountId": "000000000001",
  "architecture": "x86_64",
  "availabilityZone": "ap-southeast-2a",
  "imageId": "ami-0123456789abcdef0",
  "instanceId": "i-0a1b2c3d4e5f67890",
  "instanceType": "t3.micro",
  "pendingTime": "2026-07-03T09:58:12Z",
  "privateIp": "10.0.1.15",
  "region": "ap-southeast-2",
  "version": "2017-09-30"
}

The signed forms (signature, pkcs7, rsa2048) currently return 404 — they require a per-cluster signing key and land with EKS IRSA support.

Metadata Options

Metadata options are managed from the control plane with the standard EC2 commands. The mutable knobs are the PUT response hop limit and HttpTokens; the remaining fields are fixed.

Inspect

aws ec2 describe-instances --instance-ids i-0a1b2c3d4e5f67890 \
  --query 'Reservations[0].Instances[0].MetadataOptions'

{
  "State": "applied",
  "HttpTokens": "required",
  "HttpPutResponseHopLimit": 1,
  "HttpEndpoint": "enabled",
  "HttpProtocolIpv6": "disabled",
  "InstanceMetadataTags": "disabled"
}

Set at Launch

aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type t3.micro \
  --metadata-options "HttpPutResponseHopLimit=2"

Modify a Running or Stopped Instance

aws ec2 modify-instance-metadata-options \
  --instance-id i-0a1b2c3d4e5f67890 \
  --http-put-response-hop-limit 2

Raise the hop limit above the default of 1 when containers on the instance need IMDS access through an extra routing hop (e.g. containers on a bridge network fetching role credentials). Valid range is 1–64.

Enabling IMDSv1

Instances default to HttpTokens=required, so every read needs a token. Set optional to also serve untokened reads:

aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type t3.micro \
  --metadata-options "HttpTokens=optional"

This exists for guest agents that cannot perform the IMDSv2 handshake. The main one is cloudbase-init, the standard Windows bootstrap agent, whose EC2Service has no token support in any released version — a Windows instance left at required gets 401 on every read and so never receives its hostname, injected administrator password or user-data.

Prefer required everywhere else. IMDSv1 has no defence against a confused-deputy SSRF in a guest workload reaching the metadata endpoint on an attacker's behalf, which is the whole reason IMDSv2 binds tokens to the requesting interface.

Rejected settings:

• --http-endpoint disabled → UnsupportedOperation (the endpoint cannot be turned off)
• --http-protocol-ipv6 enabled → UnsupportedOperation
• --instance-metadata-tags enabled → UnsupportedOperation
• Hop limit outside 1–64 → InvalidParameterValue

How It Works

Useful background for host-side troubleshooting:

• The IMDS HTTP server runs inside the spinifex-vpcd service on each host, listening on 169.254.169.254:80 with one listener per instance's primary interface — attribution is structural, with no source-IP trust.
• A freshly launched guest's metadata service comes up within a few seconds of launch; cloud-init's built-in retries absorb this window.
• Session tokens and cached role credentials are not persisted. A vpcd restart drops them; SDKs and cloud-init transparently reissue. Datapath state on the host survives service restarts.

Limits and Defaults