How to Access and Use DigitalOcean Droplet Metadata
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.
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.
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/hostnameif 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
region– The DigitalOcean datacentre that the droplet resides in, such as
interfaces– Provides details of the droplet’s network interfaces. The response will contain
publicfields, 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
nameserversthat 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.
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.
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:
users: name: example groups: sudo shell: /bin/bash write_files: - path: /example.txt content: "Arbitrary data here" package_update: true
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.
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.