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.
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 available on DigitalOcean’s latest CoreOS, Ubuntu, and CentOS 7 images. User data may be defined for images that do not support CloudInit, but it is not 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.
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 to 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
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
When creating a Droplet via the DigitalOcean Control Panel, you may check the User data box in the Select additional options section to supply user data. Paste your user data into the form that appears, then select any remaining settings or options for your Droplet.
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 1 GB Droplet named “metadata.example.com” in the NYC3 datacenter, inside your VPC network nyc-example-vpc, using the Ubuntu 20.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":"s-1vcpu-1gb","vpc_uuid":"c33931f2-a26a-4e61-b85c-4e95a2ec431b","image":"ubuntu-20-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":"s-1vcpu-1gb","vpc_uuid":"c33931f2-a26a-4e61-b85c-4e95a2ec431b","image":"ubuntu-20-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.
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 retrieving Droplet metadata, see How to Access Droplet Metadata.
To see how a CloudInit file uses the provided user data, view the /var/log/cloud-init-output.log file. In this example, you can see that it has gone unhandled.
cat /var/log/cloud-init-output.log | grep userdata
2020-05-18 15:32:38,796 - __init__.py[WARNING]: Unhandled non-multipart (text/x-not-multipart) userdata: 'b'USER DATA EXAMPLE'...'
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.