Droplet Metadata Overview

Metadata is a service provided to DigitalOcean Droplets that allows a Droplet to access data about itself, i.e. its metadata. Examples of available Droplet metadata include user-provided data (`user-data`), Droplet ID, data center region, IP addresses, and tags. Aside from allowing an easy way for a user to look-up data about a Droplet, metadata can be used to configure a Droplet and its applications.

It can be queried on a Droplet by sending an HTTP GET request to the following link local address:

http://169.254.169.254/metadata/v1/

This document covers how to retrieve metadata from the service, and provides a description for each available endpoint.

Using cURL

An easy way to access the metadata service is to use cURL from a Droplet.

Here is an example of using the curl command to send an HTTP GET request to the top-level of a Droplet's metadata endpoint, /metadata/v1/:

Using cURL

Curl Example

curl http://169.254.169.254/metadata/v1/:

Running this command would output an index of the Droplet's available metadata--this is demonstrated in the Metadata Endpoints section.

Metadata API Endpoints

There are two types of endpoints in Metadata:

  • Index: Items with a trailing slash, e.g. /metadata/v1/
  • Data: Items without a trailing slash, e.g. /metadata/v1/hostname

An index endpoint will return a directory-like listing of indices and data. A data endpoint will return actual data about the droplet, also known as droplet metadata, e.g. the droplet's ID, hostname, or one of its IP addresses.

The following subsections describe each of the endpoints that are available via the Metadata API.

Metadata in JSON

The entire contents of a Droplet's metadata, in JSON. This endpoint is unique because it returns all of the metadata at once, instead of individual metadata items.

Endpoint:

/metadata/v1.json

Curl Example

curl http://169.254.169.254/metadata/v1.json:

Example Response:

{
  "droplet_id":2756294,
  "hostname":"sample-droplet",
  "vendor_data":"#cloud-config\ndisable_root: false\nmanage_etc_hosts: true\n\ncloud_config_modules:\n - ssh\n - set_hostname\n - [ update_etc_hosts, once-per-instance ]\n\ncloud_final_modules:\n - scripts-vendor\n - scripts-per-once\n - scripts-per-boot\n - scripts-per-instance\n - scripts-user\n",
  "public_keys":["ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCcbi6cygCUmuNlB0KqzBpHXf7CFYb3VE4pDOf/RLJ8OFDjOM+fjF83a24QktSVIpQnHYpJJT2pQMBxD+ZmnhTbKv+OjwHSHwAfkBullAojgZKzz+oN35P4Ea4J78AvMrHw0zp5MknS+WKEDCA2c6iDRCq6/hZ13Mn64f6c372JK99X29lj/B4VQpKCQyG8PUSTFkb5DXTETGbzuiVft+vM6SF+0XZH9J6dQ7b4yD3sOder+M0Q7I7CJD4VpdVD/JFa2ycOS4A4dZhjKXzabLQXdkWHvYGgNPGA5lI73TcLUAueUYqdq3RrDRfaQ5Z0PEw0mDllCzhk5dQpkmmqNi0F [email protected]"],
  "region":"nyc3",
  "interfaces":{
    "private":[
      {
        "ipv4":{
          "ip_address":"10.132.255.113",
          "netmask":"255.255.0.0",
          "gateway":"10.132.0.1"
        },
        "mac":"04:01:2a:0f:2a:02",
        "type":"private"
      }
    ],
    "public":[
      {
        "ipv4":{
          "ip_address":"104.131.20.105",
          "netmask":"255.255.192.0",
          "gateway":"104.131.0.1"
        },
        "ipv6":{
          "ip_address":"2604:A880:0800:0010:0000:0000:017D:2001",
          "cidr":64,
          "gateway":"2604:A880:0800:0010:0000:0000:0000:0001"
        },
        "mac":"04:01:2a:0f:2a:01",
        "type":"public"}
    ]
  },
  "floating_ip": {
    "ipv4": {
      "active": false
    }
  },
  "dns":{
    "nameservers":[
      "2001:4860:4860::8844",
      "2001:4860:4860::8888",
      "8.8.8.8"
    ]
  }
}

Metadata Index

The top-level metadata index. This index can be navigated to find all available Metadata endpoints.

Endpoint:

/metadata/v1/

Curl Example

curl http://169.254.169.254/metadata/v1/

Example Response

id
hostname
user-data
vendor-data
public-keys
region
interfaces/
dns/
floating_ip/

Droplet ID

The Droplet's unique identifier. This is automatically generated upon Droplet creation.

Endpoint:

/metadata/v1/id

Droplet ID

Curl Example

curl http://169.254.169.254/metadata/v1/id

Example Response

2756294

Hostname

The Droplet's hostname, as specified by the user during Droplet creation.

Endpoint:

/metadata/v1/hostname

Hostname

Curl Example

curl http://169.254.169.254/metadata/v1/hostname

Example Response

sample-droplet

User Data

The user data that was provided by the user during Droplet creation. User data can contain arbitrary data for miscellaneous use or, with certain Linux distributions, an arbitrary shell script or cloud-config file that will be consumed by a variation of cloud-init upon boot. At this time, cloud-config support is included with CoreOS, Ubuntu 14.04, and CentOS 7 images on DigitalOcean.

Endpoint:

/metadata/v1/user-data

Curl Example

curl http://169.254.169.254/metadata/v1/user-data

Example Response

#! /bin/bash
echo "Data from user"

Vendor Data

Vendor-provided data that can be used to configure Droplets upon their creation. This is similar to user data, but it is provided by DigitalOcean instead of the user.

Endpoint:

/metadata/v1/vendor-data

Curl Example

curl http://169.254.169.254/metadata/v1/vendor-data

Example Response

#cloud-config
disable_root: false
manage_etc_hosts: true

cloud_config_modules:
 - ssh
 - set_hostname
 - [ update_etc_hosts, once-per-instance ]

cloud_final_modules:
 - scripts-vendor
 - scripts-per-once
 - scripts-per-boot
 - scripts-per-instance
 - scripts-user

Public Keys

Public SSH key(s) that were added to the Droplet's root user's authorized_keys file during Droplet creation.

Endpoint:

/metadata/v1/public-keys

Curl Example

curl http://169.254.169.254/metadata/v1/public-keys

Example Response

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCcbi6cygCUmuNlB0KqzBpHXf7CFYb3VE4pDOf/RLJ8OFDjOM+fjF83a24QktSVIpQnHYpJJT2pQMBxD+ZmnhTbKv+OjwHSHwAfkBullAojgZKzz+oN35P4Ea4J78AvMrHw0zp5MknS+WKEDCA2c6iDRCq6/hZ13Mn64f6c372JK99X29lj/B4VQpKCQyG8PUSTFkb5DXTETGbzuiVft+vM6SF+0XZH9J6dQ7b4yD3sOder+M0Q7I7CJD4VpdVD/JFa2ycOS4A4dZhjKXzabLQXdkWHvYGgNPGA5lI73TcLUAueUYqdq3RrDRfaQ5Z0PEw0mDllCzhk5dQpkmmqNi0F [email protected]

Droplet Region

The region code of where the Droplet resides.

Endpoint:

/metadata/v1/region

Curl Example

curl http://169.254.169.254/metadata/v1/region

Example Response

nyc3

Network Interfaces Index

An index of all network interfaces by type, e.g. "public" and "private".

Endpoint:

/metadata/v1/interfaces/

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/

Example Response

public/
private/

Interface Type Index

An enumerated index of all network interfaces that are of the specified interface type.

Example Endpoint:

/metadata/v1/interfaces/public/

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/

Example Response

0/

Enumerated Interface Index

An index of the attributes of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/

Example Response

mac
type
ipv4/
ipv6/

Interface MAC Address

The MAC address of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/mac

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/mac

Example Response

04:01:2a:0f:2a:03

Interface Type

The type of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/type

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/type

Example Response

public

Interface IPv4 Index

An index of the specified network interface's IPv4 attributes.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv4/

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/

Example Response

address
netmask
gateway

Interface IPv4 Address

The IPv4 address of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv4/address

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address

Example Response

104.131.20.105

Interface IPv4 Netmask

The netmask of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv4/netmask

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/netmask

Example Response

255.255.192.0

Interface IPv4 Gateway

The gateway of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv4/gateway

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/gateway

Example Response

104.131.0.1

Interface IPv6 Index

An index of the specified network interface's IPv6 attributes.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv6/

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv6/

Example Response

address
cidr
gateway

Interface IPv6 Address

The IPv6 address of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv6/address

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv6/address

Example Response

2604:A880:0800:0010:0000:0000:017D:2001

Interface IPv6 CIDR Block Size

The IPv6 CIDR block size of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv6/cidr

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv6/cidr

Example Response

64

Interface IPv6 Gateway

The IPv6 gateway of the specified network interface.

Example Endpoint:

/metadata/v1/interfaces/public/0/ipv6/gateway

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/ipv6/gateway

Example Response

2604:A880:0800:0010:0000:0000:0000:0001

Anchor Interface IPv4 Index

An index of the specified "Anchor" network interface's IPv4 attributes.

Note: An "Anchor" interface is an implementation detail of DigitalOcean Floating IPs.

Example Endpoint:

/metadata/v1/interfaces/public/0/anchor_ipv4/

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/

Example Response

address
netmask
gateway

Anchor Interface IPv4 Address

The IPv4 address of the specified "Anchor" network interface.

Note: An "Anchor" interface is an implementation detail of DigitalOcean Floating IPs.

Example Endpoint:

/metadata/v1/interfaces/public/0/anchor_ipv4/address

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/address

Example Response

10.17.0.160

Anchor Interface IPv4 Netmask

The netmask of the specified "Anchor" network interface.

Note: An "Anchor" interface is an implementation detail of DigitalOcean Floating IPs.

Example Endpoint:

/metadata/v1/interfaces/public/0/anchor_ipv4/netmask

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/netmask

Example Response

255.255.0.0

Anchor Interface Anchor IPv4 Gateway

The gateway of the specified "Anchor" network interface.

Note: An "Anchor" interface is an implementation detail of DigitalOcean Floating IPs.

Example Endpoint:

/metadata/v1/interfaces/public/0/anchor_ipv4/gateway

Curl Example

curl http://169.254.169.254/metadata/v1/interfaces/public/0/anchor_ipv4/gateway

Example Response

10.17.0.1

Floating IP Index

An index of Floating IP attributes.

Endpoint:

/metadata/v1/floating_ip/

Curl Example

curl http://169.254.169.254/metadata/v1/floating_ip/

Example Response

ipv4/

IPv4 Index

An index of IPv4 Floating IP attributes.

Endpoint:

/metadata/v1/floating_ip/ipv4/

Curl Example

curl http://169.254.169.254/metadata/v1/floating_ip/ipv4/

Example Response

active
ip_address

Active

Displays true if a Floating IP is currently assigned to the Droplet and false if it is not.

Endpoint:

/metadata/v1/floating_ip/ipv4/active

Curl Example

curl http://169.254.169.254/metadata/v1/floating_ip/ipv4/active

Example Response

true

IP Address

The IP address of the Floating IP that is currently assigned to the Droplet.

Endpoint:

/metadata/v1/floating_ip/ipv4/ip_address

Curl Example

curl http://169.254.169.254/metadata/v1/floating_ip/ipv4/ip_address

Example Response

45.55.96.17

DNS Index

An index of DNS attributes.

Endpoint:

/metadata/v1/dns/

Curl Example

curl http://169.254.169.254/metadata/v1/dns/

Example Response

nameservers

DNS Nameservers

The nameserver entries that are added to a Droplet's /etc/resolv.conf file during creation.

Endpoint:

/metadata/v1/dns/nameservers

Curl Example

curl http://169.254.169.254/metadata/v1/dns/nameservers

Example Response

2001:4860:4860::8844
2001:4860:4860::8888
8.8.8.8

Tags Index

An index of tags associated with the droplet.

Endpoint:

/metadata/v1/tags/

Curl Example

curl http://169.254.169.254/metadata/v1/tags/

Example Response

production
application
v1

Metadata Errors

Metadata uses standard HTTP response codes when responding to all requests. As such, a succesful request returns a 200 (OK) response.

You may use the -w "\n\n%{http_code}\n" cURL option to append the HTTP response code to the end of the metadata response, like so:

Curl Example

curl -w "\n\n%{http_code}\n" http://169.254.169.254/metadata/v1/

301 Moved Permanently

If you access an index endpoint but forget to add the trailing slash, you will receive a 301 Moved Permanently response with this content:

Moved Permanently.

404 Not Found

If you access an endpoint that does not exist, you will receive a 404 Not Found response with this content:

not found

Resolve this by using an existing endpoint.