Guide
Training

Use the Metadata service API

Suggest Edits

TheMetadata service offers an API for use in automated deployment configurations. Compatible versions of cloud-init can leverage the Metadata service to automatically configure new Compute Instances at deployment. However, the Metadata service's API can also be accessed directly. Doing so provides access to both instance and user data.

In this reference guide, learn more about the available API endpoints for the Metadata service and how to use them. Follow along to find out how to access the API from your Compute Instance and what to expect from each endpoint.

API endpoints

To access the Metadata API, you need to be on a Compute Instance. If you have not done so already, follow along with our guide on Create a Compute Instance before moving forward.

Once you have an instance deployed, the Metadata API is accessible via link-local addresses, specifically:

  • IPv4: 169.254.169.254
  • IPv6: fd00:a9fe:a9fe::1

Each Metadata API endpoint provides instance data or user data. Instance data includes information related to the deployment and the instance itself, while User data consists of a specific field submitted when deploying the instance.

📘

Only select regions support submission of user data. Additionally, a limited number of distributions are officially supported by ​Akamai​'s Metadata service and cloud-init. To learn more about Metadata and cloud-init support, review the Availability section of our Metadata service guide.

The sections that follow list each endpoint, explain their usage, and provide examples of the expected output. Using the Accept header, output can generally be in either the default text/plain format or the applciation/json format.

To demonstrate, the guide provides example output in the plain-text format and shows the response structure in JSON format where applicable.

Authentication tokens (/v1/token)

Use of the Metadata API always starts with the token endpoint. Use this endpoint to authenticate a new session and receive a Metadata token for accessing subsequent Metadata endpoints from your instance.

While all other Metadata endpoints use GET, requests to this endpoint use the PUT method:

curl -X PUT -H "Metadata-Token-Expiry-Seconds: 3600" http://169.254.169.254/v1/token

These requests provide a Metadata-Token-Expiry-Seconds header, which indicate the token's expiry time in seconds:

e80eb80986f17fcd3df8fcb6ea944774cae47b26ed6d68df63a15b294b7a6e3f

When using the JSON format, the endpoint's response is an array containing the token string:

[ "token" ]

From here on, this guide assumes you have already acquired a Metadata token. For convenience, subsequent examples use $TOKEN in place of the actual token string. Follow along by storing the token in an environment variable, as shown here:

export TOKEN=$(curl -X PUT -H "Metadata-Token-Expiry-Seconds: 3600" http://169.254.169.254/v1/token)

Instance data (/v1/instance)

To receive information about the Compute Instance itself, use the instance endpoint:

curl -H "Metadata-Token: $TOKEN" http://169.254.169.254/v1/instance

The output includes information on the identity of the instance, its specifications, and its backup scheduling:

backups.enabled: false
host_uuid: 123abc456def789ghi
id: 532754976
label: example-linode-instance
region: us-iad
specs.disk: 51200
specs.gpus: 0
specs.memory: 2048
specs.transfer: 2000
specs.vcpus: 1
type: g6-standard-1

The endpoint's response is structured as shown below using the JSON format:

{
  “id”: int,
  “host_uuid”: str,
  “label”: str,
  “region”: str,
  “type”: str,
  “tags”: array of str,
  “specs”: {
    “vcpus”: int,
    “memory”: int,
    “disk”: int,
    “transfer”: int,
    “gpus”: int
  },
  “backups”: {
    “enabled”: bool,
    “status”: str[pending/running/complete] or null
  }
}

The overall object provides identifying information about the instance, such as ID, label, and tags. A nested specs object details the instance specifications, while a nested backups object provides the status of backups for the instance.

Network data (/v1/network)

To retrieve information about how the instance's networking is configured, use the network endpoint:

curl -H "Metadata-Token: $TOKEN" http://169.254.169.254/v1/network

Refer to this endpoint when you need to identify the instance's IP addresses, configured network interfaces, and those interfaces' IPAM addresses:

ipv4.public: 192.0.2.0/24
ipv6.link_local: fe80::db8:1b3d:e5g7::/64
ipv6.slaac: 2600:3c05::db8:1b3d:e5g7::/64

The endpoint's response follows the JSON structuring shown below:

{
  “interfaces”: [
    {
      “purpose”: str[public/vlan],
      “label”: str,
      ipam_address”: str[optional]
    },
  ],
  “ipv4”: {
    “public”: array of str,
    “private”: array of str,
    “elastic”: array of str
  },
  “ipv6”: {
    “ranges”: array of str,
    “link-local”: array of str
    “elastic-ranges”: array of str
  }
}

The interfaces array shows what interfaces, if any, the instance has. However, a default "eth0 - Public Internet" interface alone does not result in any output here. The ipv4 and ipv6 objects list the various addresses configured for the instance.

SSH keys (/v1/ssh-keys)

Use the ssh-keys endpoint to acquire a list of all SSH keys and associated users configured for the instance:

curl -H "Metadata-Token: $TOKEN" http://169.254.169.254/v1/ssh-keys

The output lists each user by username, along with an array of associated keys:

users.example-user: EXAMPLE_SSH_PUBLIC_KEY
users.root: ROOT_SSH_PUBLIC_KEY

The endpoint's output uses the structure shown below for JSON requests:

{
  “users”: {
    “root”: array of str,
    “username”: array of str
  }
}

A root array lists keys for the root user. Other users each have their own array of keys, with the username acting as a label.

User data (/v1/user-data)

The user-data endpoint returns the user data submitted during the instance's deployment. Typically, this user data consists of a cloud-config script to be used by cloud-init for automating deployment. However, when accessing the Metadata service directly, you may utilize the user data for other purposes. If no user data was submitted, nothing will be returned.

Submitted user data is required to be encoded using base64, so you need to decode the returned string to view the expected user data:

curl -H "Metadata-Token: $TOKEN" http://169.254.169.254/v1/user-data | base64 --decode

The output from this endpoint is simply the user data contents. There is no further formatting. For this reason, the endpoint only accepts the text/plain format, not application/json, format.

Below is example cloud-config user data for a basic instance. This is just an example and the specific content varies depending on the user data submitted when initializing the instance.

#Cloud-config

# Configure a limited user
users:
  - default
  - name: example-user
    groups:
      - sudo
    sudo:
      - ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    ssh_authorized_keys:
      - "SSH_PUBLIC_KEY"

# Perform system updates
package_update: true
package_upgrade: true

# Configure server details
timezone: 'US/Central'
hostname: examplehost

# Harden SSH access
runcmd:
  - sed -i '/PermitRootLogin/d' /etc/ssh/sshd_config
  - echo "PermitRootLogin no" >> /etc/ssh/sshd_config
  - systemctl restart sshd

Updated 2 months ago