How to Access Droplet Metadata

DigitalOcean Droplets are Linux-based virtual machines (VMs) that run on top of virtualized hardware. Each Droplet you create is a new server you can use, either standalone or as part of a larger, cloud-based infrastructure.

Metadata is a service provided to DigitalOcean Droplets that allows a Droplet to access data about itself. In addition to basic Droplet metadata retrieval, Metadata allows users to provide arbitrary user data to their Droplets at creation, which CloudInit can consume to ease and expedite the provisioning of cloud servers.

Full documentation of the Metadata service and its endpoints are available at the DigitalOcean Developer's Portal.

The Metadata Service IP

Droplets can access the metadata service using the special static IP address 169.254.169.254. This allows you to use similar scripts on different Droplets without needing change the destination IP address. For example, on any DigitalOcean Droplet, this will return the public IPv4 address:

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

How to Retrieve Droplet Metadata

The Droplet Metadata API is covered in detail in the DigitalOcean Developer's Portal, but we will show a few examples of retrieving metadata here.

The Metadata API can be queried from a Droplet by sending an HTTP GET request to the following link local address:

http://169.254.169.254/metadata/v1/

Top-Level Index

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/:

curl http://169.254.169.254/metadata/v1/
id
hostname
user-data
vendor-data
public-keys
region
interfaces/
dns/
floating_ip/
tags/

This returns an index of the available Droplet metadata, and can be thought of like a directory listing. Items trailed by a slash represent an index, and items that are not trailed by a slash represent data. You can further curl into the indexes to see more entries.

User Data

Here is an example of using curl to retrieve a Droplet's user data:

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

This returns the user data that was supplied during the Droplet's creation. For more information about user data, see How to Provide User Data During Droplet Creation.

Public Network Interface

Here is an example of using curl to retrieve a Droplet's public IP address:

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

Conclusion

By calling into the special IP 169.254.169.254 from a Droplet, you can access metadata about that Droplet. Full details of the accessible metadata are available at the DigitalOcean Developer's Portal.