Skip to main content

Read instance metadata from inside an instance

This guide reads metadata about an instance from a shell inside it, through the instance metadata service at 169.254.169.254. Every read needs a session token, so step 1 gets one.

Before you start, you need a shell on the instance (for example through tritonctl ssh) and curl in the guest. The curl commands run inside the instance, as any user. The tritonctl commands in steps 5 and 6 run on your workstation.

Step 1: Get a session token​

Request a token that lives for six hours (21600 seconds, the maximum):

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

The response body is the token. Values below 1 are raised to 1, and values above 21600 are lowered to 21600. Request a new token when it expires.

If the request fails:

ResultCause
400, missing X-aws-ec2-metadata-token-ttl-seconds headerThe TTL header was not sent.
400, X-aws-ec2-metadata-token-ttl-seconds must be an integerThe TTL is not a whole number.
404, imds disabledMetadata is turned off for this instance.
curl times outMetadata is turned off for this instance, or the request did not go to TCP port 80.

Step 2: List what is available​

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

The response lists one name per line. A name ending in / has children.

ami-id
hostname
instance-id
instance-type
local-hostname
local-ipv4
mac
public-keys/

The exact list depends on the instance. local-ipv6 appears only when the primary NIC has an IPv6 address, and public-keys/ only when the instance has SSH keys.

Step 3: Read one value​

Read the instance's UUID:

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

Text values come back as the bare text, with no quotes and no trailing newline. Numbers and structured values come back as JSON with Content-Type: application/json.

Read the first SSH public key attached to the instance:

curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key

Triton-specific facts, such as the VPC, subnet, and image, are under /triton/system:

curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/triton/system/vpc-id

Step 4: Read the user-data​

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

The response is the user-data passed at create time. An instance created without user-data answers 404, not found. To set it, see Pass user-data when you create an instance.

Step 5: Read a key you set yourself​

Keys you set with tritonctl meta set are under /triton/, by namespace. From your workstation, set a project-wide key:

tritonctl meta set --scope project --key config/app/mode --value production

Inside any instance in that project:

curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/triton/config/app/mode

The new value reaches the guest within 30 seconds, the agent's cache lifetime.

To see every key the guest can read, with the scope each value came from:

curl -sS -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/triton/dynamic/realized

A key you set but cannot read from the guest has guest_visible turned off. Keys outside config/ and state/ set at tenant scope are hidden by default. Pass --guest-visible true to tritonctl meta set to show one.

Step 6: Write a value back from the guest​

A guest can update an existing guest/ key that was set with --guest-writable. From your workstation, create the key for one instance:

tritonctl meta set --scope instance --id <INSTANCE> \
  --key guest/status --value starting --guest-writable

<INSTANCE> is the instance name, UUID, or UUID prefix.

Inside the instance:

curl -sS -X PUT -H "X-aws-ec2-metadata-token: $TOKEN" \
  --data ready \
  http://169.254.169.254/triton/guest/status

A body that is valid JSON is stored as that JSON value. Any other body is stored as a string. A write to a key that does not exist answers 404, and a write to a key without --guest-writable answers 403.

If a read fails​

ResultCause
401, missing IMDS tokenThe X-aws-ec2-metadata-token header was not sent.
401, invalid IMDS tokenThe token expired, is malformed, or was issued to another instance or on another compute node. Get a new one.
404, not foundNo visible key at that path, and no visible keys below it.
429, rate limit exceededMore than 100 requests per second sustained, after a burst of 200. Slow down and retry.
503, realized view unavailableThe agent could not reach the control plane to build the view. Retry.

See also​