IMDS (Instance Metadata Service)

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.

# 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. Because the platform is IMDSv2-only, the only mutable knob is the PUT response hop limit.

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.

Rejected settings:

• --http-tokens optional → UnsupportedOperation (IMDSv2 cannot be relaxed)
• --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