DigitalOcean droplets possess metadata that reveal information about the compute instance and its environment. You can supply your own arbitrary data to make custom values accessible from inside your droplet.
Default Metadata
The default metadata available on every droplet lets you query key information such as the DigitalOcean datacentre region, network interface addresses, and tags assigned in the control panel or via the API.
A droplet can retrieve its own metadata by calling the special network address, 169.254.169.254. Connect to your droplet over SSH and use the curl command to experiment with the available API endpoints.
Here’s a basic example that provides a list of supported metadata fields:
You can access any of the fields included in this endpoint’s output by appending the field name to the metadata API’s base URL:
This example will provide the droplet’s IP address in its response.
Metadata Fields
The following metadata fields are currently supported:
id – The droplet’s public IP address. hostname – The droplet’s hostname, matching the name supplied when creating the droplet. It may not reflect the name in /etc/hostname if you manually change it later. user-data – Arbitrary user-supplied data (see the later section in this guide). vendor-data – DigitalOcean-issued data used to configure the droplet. public-keys – SSH public keys that were added to the droplet when it was created via the control panel or API. These keys are added to the root account automatically. region – The DigitalOcean datacentre that the droplet resides in, such as nyc1 or lon1. interfaces – Provides details of the droplet’s network interfaces. The response will contain private and public fields, each an array of objects that describe configured network interfaces. The details include ipv4, to obtain the IP address, and mac, the droplet’s reported MAC address on that network. floating_ip – When a DigitalOcean Floating IP is assigned to the droplet, this field exposes its details. dns – Contains a sub-field nameservers that lists the nameservers used by the droplet when performing DNS lookups. tags – Provides a list of all the user-created tags assigned to the droplet. features – An object describing DigitalOcean features that have been activated for the droplet.
Fields that contain nested data or are arrays of objects can be traversed using API endpoints. Here’s an example that provides the IP address of the droplet’s first private network interface:
This makes it easy to extract specific values for use in your scripts. You don’t always need to manually parse the JSON response bodies.
Once you’ve obtained your droplet’s ID, your scripts could defer to the regular DigitalOcean API to gain more information or perform droplet actions. As an example, you might want to create a snapshot before running a destructive sequence of commands. Your script could use the metadata API to discover the droplet ID it’s running on, then pass the ID to the snapshots REST API to create a new snapshot. The script would still be portable across different droplets as you’re not hardcoding the ID.
Getting All Available Metadata
You can get all the metadata associated with a droplet by appending .json to the base API endpoint:
This will provide a JSON object containing all the fields described above. Fields with a - (hyphen) character will be converted to use _ (underscore) instead in the JSON.
User Data
DigitalOcean lets you provide user data when you create a new droplet. It can be supplied either via the form in the control panel or with the –user-data flag when you’re using doctl compute droplet create. User data is exposed by the user-data field in the metadata API.
Like other forms of metadata, user data is immutable and can’t be modified after the droplet’s creation. It’s normally used to configure first-run package installations and config changes but you could also add arbitrary data fields that make sense to your organization.
User data gets passed to cloud-init. This program runs on a droplet’s first boot and acts as a mechanism to automate initial setup. To use cloud-init, add the contents of a cloud-config-compatible YAML file to your droplet’s user-data. This example updates all existing packages, writes a file, and creates a new user account:
Other Ways of Accessing Metadata
The metadata API is a service that’s only available from within a droplet. You interact with it using curl, alternative terminal HTTP clients, or your programming language’s HTTP library within scripts. DigitalOcean provides an official client library for Go which acts as a basic wrapper around the API.
You can’t directly query a droplet’s metadata from the outside. Neither the Doctl CLI nor the main DigitalOcean REST API support retrieving the exact data structure exposed by the in-droplet metadata service.
If you want to access droplet details such as networking interfaces, tags, and system configuration externally, you’ll need to use other features of the API and Doctl. The doctl compute droplet get command is a good starting point which provides much of the same information as the Metadata service, as well as some extra details including hardware resource limits.
Summary
The DigitalOcean Metadata service is a special API that you can access from within your droplets. It helps you build scripts that need to reference key attributes of your droplet, such as its ID, datacentre region, or IP address.
You can add your own information to a droplet’s metadata during the creation process. The metadata API will expose it as the user-data field. This means you can use metadata as a basic config store for your scripts and bootstrap routines, lessening the need to copy files or set environment variables each time you create a new droplet.
Metadata is always specific to an individual droplet. The API exists to provide a droplet introspection mechanism. Use the regular REST API, either directly or via Doctl, if you want to query your DigitalOcean account to find other droplets with similar attributes.
