Instance metadata service

Instance metadata service

Read droplet identity and network configuration from an authorized guest.

The instance metadata service supplies a droplet's identity and bootstrap configuration to its guest. Requests are scoped to the interface and execution identity of that droplet.

Session tokens

PUT/v1/token
Auth
Guest-local metadata identity; no organization API token

Issues a metadata session token bound to the requesting guest.

The metadata listener uses the link-local address 169.254.169.254. Guests must obtain a session token before reading versioned metadata. Token requests use the token endpoint and the Infra-Metadata-Token-TTL-Seconds header.

The TTL must be an integer from 60 through 21600, inclusive. Omission defaults to 300 seconds. Invalid values return 400 without issuing a token. The token is bound to this guest identity and cannot read another droplet's metadata.

Inside a guest with a metadata-capable image, request a token and keep it in a local shell variable:

Shell
metadata_token=$(curl --fail --silent --request PUT \
  --header 'Infra-Metadata-Token-TTL-Seconds: 300' \
  http://169.254.169.254/v1/token)

Use that token in the same shell to read the guest identity:

Shell
curl --fail --silent \
  --header "Infra-Metadata-Token: ${metadata_token}" \
  http://169.254.169.254/v1/instance

An expired token returns 401. Obtain a new token and retry the read. Tokens are not organization API keys and cannot authorize a control-plane mutation.

Available documents

GET/v1/instance
Auth
Infra-Metadata-Token from this guest session

Returns droplet ID, project ID, region, zone, and configured hostname.

GET/v1/network
Auth
Infra-Metadata-Token from this guest session

Returns interface IDs, addresses, routes, resolvers, and applied configuration revision.

GET/v1/user-data
Auth
Infra-Metadata-Token from this guest session

Returns the submitted initialization document when user-data access is enabled. Disabled access returns 403.

Metadata contains the configuration for this guest, not organization inventory. During a pending network update, the document includes its applied revision so an image can distinguish old guest configuration from an accepted control-plane request.

Restrict the listener

Enable Require metadata token for supported images. Legacy tokenless access must be explicitly allowed by project policy. The default response hop limit is 1; increasing it permits additional guest-side forwarding and requires an explicit configuration change.

Do not proxy this listener through an application, load balancer, or shared container endpoint. An application with server-side request capabilities can otherwise expose metadata to untrusted callers. Keep long-lived secrets out of user data even when tokens are required.

Lifecycle

Restarting a guest does not change its resource identity. Replacing or cloning it creates a new identity and invalidates assumptions based on the old metadata. A live migration preserves the droplet identity while the metadata path is reestablished at the destination.

The metadata service is not an application service-discovery directory. Use private DNS for service names and guest initialization for first-boot configuration.