An Introduction to Droplet Metadata
An Introduction to Droplet Metadata
We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

An Introduction to Droplet Metadata

PostedOctober 13, 2014 106.5k views DigitalOcean API CoreOS Ubuntu CentOS

Introduction

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 user data, droplet ID, data center region, and IP addresses. In addition to basic droplet metadata retrieval, Metadata allows users to provide arbitrary user data to their droplets at creation, which can be consumed by CloudInit to ease the provisioning of cloud servers.

This tutorial covers the following topics:

  • What is user data
  • How to provide user data to a droplet
  • How to retrieve droplet metadata

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

About User Data

User data is arbitrary data that a user can supply to a droplet during its creation time. User data can be consumed by CloudInit, typically during the first boot of a cloud server, to perform tasks or run scripts as the root user--this can be extremely useful when provisioning a server. CloudInit is currently available on DigitalOcean's latest CoreOS, Ubuntu 14.04, and CentOS 7 images. User data may be defined for images that do not support CloudInit, but it will not be consumed automatically on the first boot.

CloudInit accepts cloud-config files or any script that can be interpreted by the new droplet, such as bash scripts. For help with writing cloud-config files, check out our tutorial: An Introduction to Cloud-Config Scripting.

How to Provide User Data

In Metadata, User data can be provided to a droplet when it is being created. User data cannot be modified after a droplet is created. Because droplets can be created through the DigitalOcean Control Panel or API, we will show you how to specify user data using both methods.

In both examples, we will create an Ubuntu cloud server and include a bash script that installs Nginx and replaces the contents of index.html with the droplet's hostname and IP address. Here is the bash script, if you would like to try it yourself:

#!/bin/bash

apt-get -y update
apt-get -y install nginx
export HOSTNAME=$(curl -s http://169.254.169.254/metadata/v1/hostname)
export PUBLIC_IPV4=$(curl -s http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address)
echo Droplet: $HOSTNAME, IP Address: $PUBLIC_IPV4 > /usr/share/nginx/html/index.html

DigitalOcean Control Panel

When creating a droplet via the DigitalOcean Control Panel, you may provide user data in the Available Settings section, in the user data entry box. Simply tick the "Enable User Data" checkbox, and paste your user data into the form that appears. Remember to select any other settings that you may want, such as Private Networking.

User Data

If you are unfamiliar with creating a droplet via the DigitalOcean Control Panel, refer to this guide.

DigitalOcean API

If you use the DigitalOcean API to create your droplets, you can specify your user data via the user_data parameter in your droplet creation POST request.

Let us assume that we want to create a 512 MB droplet named "metadata.example.com", with private networking, in the NYC3 data center, using the Ubuntu 14.04 image slug, and the user data shown in the control panel example. Here is an example of the curl command you would run to create it using the DigitalOcean API, assuming the user data is in ~/user-data.yml:

curl -X POST "https://api.digitalocean.com/v2/droplets" \
      -d'{"name":"metadata.example.com","region":"nyc3","size":"512mb","private_networking":true,"image":"ubuntu-14-04-x64","user_data":
"'"$(cat ~/user-data.yml)"'",
      "ssh_keys":[ <SSH KEY IDs> ]}' \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"

You may also pass the user data directly into the curl request, assuming you escape any double-quote characters, like this:

curl -X POST "https://api.digitalocean.com/v2/droplets" \
      -d'{"name":"metadata.example.com","region":"nyc3","size":"512mb","private_networking":true,"image":"ubuntu-14-04-x64","user_data":
"#!/bin/bash

apt-get -y update
apt-get -y install nginx
export HOSTNAME=$(curl -s http://169.254.169.254/metadata/v1/hostname)
export PUBLIC_IPV4=$(curl -s http://169.254.169.254/metadata/v1/interfaces/public/0/ipv4/address)
echo Droplet: $HOSTNAME, IP Address: $PUBLIC_IPV4 > /usr/share/nginx/html/index.html",
      "ssh_keys":[ <SSH KEY IDs> ]}' \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"

You must substitute your SSH Key ID(s) or fingerprint(s) for <SSH Key ID(s)>, and make sure your $TOKEN environmental variable is set to one of your read/write DigitalOcean Personal Access Tokens. For more information about using the API, please refer to this tutorial.

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/

This prints out 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.

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 will return the user data that was supplied during the droplet's 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

This will return the droplet's public IP address. This metadata endpoint, along with the hostname endpoint, was used in the How to Provide User Data section to create the example Nginx index.html file.

Conclusion

DigitalOcean's Droplet Metadata service can be used to improve your cloud server provisioning experience, by allowing you to spin up new droplets that are automatically configured to your needs. By providing the appropriate user data, you may now create droplets that install software on boot, configure said software, and even register with a service discovery system, without interacting with them!

If you want to learn about all of the available Metadata endpoints, check out the Metadata documentation.

Have a question or suggestion about using Metadata? Leave them in the comment section!

35 Comments

Creative Commons License