How To Use Droplet Tagging with the DigitalOcean API

Introduction

The DigitalOcean API provides access to most of the features found in the DigitalOcean Control Panel, and offers a straightforward way to manipulate Droplets and other resources from the command line or your own code.

Droplet tagging is a new feature. The feature allows you to group and locate Droplets by applying tags, as well as initiate actions across all the Droplets with a specific tag.

Prerequisites

This guide uses the curl utility and Bash for all examples. It assumes that you are familiar with the use of the DigitalOcean API, and have already generated a personal access token. For details on this process, and the basics of API usage, see How To Use the DigitalOcean API v2.

Once you have a token, begin by setting the $TOKEN variable in your shell. The export command ensures that child processes can read the variable:

export TOKEN=your_personal_access_token

We’ll use $TOKEN for the rest of the examples in this document, always inside a double-quoted string so that its value, rather than the literal string $TOKEN, will be interpolated. If you receive errors, first make certain that this value is correctly set in your current shell.

Creating, Listing, and Viewing Tags

Tags can either be created before they are applied to resources or created and applied during resource creation.

Creating Tags Independently

Use curl to send a POST to the API endpoint, including headers for the Content-Type, your personal access token, and some JSON data to specify the tag name. Substitute your desired tag name for tag_name:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"tag_name"}' \
"https://api.digitalocean.com/v2/tags"

Output
{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}

Creating and Applying Tags When Creating Other Resources

Resources can also include a tags attribute on creation. This is an array of tag names that will be applied upon creation. Tags that do not already exist will be created to satisfy the request. The only supported resource at the time of this writing is a Droplet, but eventually others will be available.

To create a Droplet and apply tags upon creation, you could type:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"name":"example.com","region":"nyc3","size":"512mb","image":"ubuntu-14-04-x64","tags":["tag_name","another_tag"]}' \
"https://api.digitalocean.com/v2/droplets"

This will create a new Droplet with the tags tag_name and another_tag applied. If the example in the previous section was executed, then this command would apply the existing tag_name tag and create and apply the another_tag tag to the Droplet.

Listing Existing Tags

You can list all of your current tags with a GET request to /v2/tags:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags"

Output
{"tags":[{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}],"links":{},"meta":{"total":1}}

To view an individual tag, use a GET request to /v2/tags/tag_name:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

Output
{"tag":{"name":"tag_name","resources":{"droplets":{"count":0,"last_tagged":null}}}}

The example output above is brief. Notice that the resources.droplets.last_tagged property is null. Once you associate a tag with one or more Droplets, this property will contain detailed information about the last-tagged Droplet.

Tagging and Untagging Droplets

Tags can also be applied to existing resources. The only supported resource at the time of this writing is a Droplet, but eventually others will be available.

Droplets are associated to tags using their id attribute. You can retrieve a JSON object containing a droplets array listing all of your Droplets with a GET request to /v2/droplets:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/droplets"

Once you know a Droplet’s id, you can associate it with a tag by POSTing to /v2/tags/tag_name/resources, including JSON data which sets resource_id to the Droplet id and resource_type to the string droplet:

curl -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources" 

Try a GET request for the tag again, and the resources.droplets.last_tagged property should contain detailed information on the Droplet you just tagged:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

To remove a tag from a specific Droplet, you can issue a DELETE request to /v2/tags/tag_name/resources/, with the same data you used to tag the Droplet in the first place:

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"resources":[{"resource_id":"droplet_id","resource_type":"droplet"}]}' \
"https://api.digitalocean.com/v2/tags/tag_name/resources" 

This will remove the tag from the resource.

Finding Droplets by Tag

To find all Droplets associated with a particular tag, issue a GET request to /v2/droplets?tag_name=tag_name:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/droplets?tag_name=tag_name"

This will filter your Droplets by the requested tag.

Performing Actions on Tagged Droplets

You can perform a number of actions on all the Droplets associated with a specific tag:

In order to perform an action, send a POST to /v2/droplets/actions?tag_name=tag_name with JSON data specifying a type and any additional values required by the action:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"action_type"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=tag_name"

You can retrieve a history of recent actions, including their completion status, with a GET request to /v2/actions:

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/actions"

This is a useful way to determine whether actions have completed or are still in-progress.

Example: Snapshotting Tagged Droplets

Suppose that you have a collection of Droplets associated with a tag named fileserver, and you want to snapshot all of them.

First issue a shutdown action:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"shutdown"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Wait for the shutdown to finish on all Droplets, and issue a snapshot action, including a name value for the snapshot:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"snapshot", "name":"snapshot_name"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

Bear in mind that snapshots may take an hour or more to complete, depending on the size of the Droplet. Once the snapshots have finished, you can bring the Droplets back online with a power_on action:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-d '{"type":"power_on"}' \
"https://api.digitalocean.com/v2/droplets/actions?tag_name=fileserver"

This will start the Droplet again.

Deleting Tags

You can delete a tag itself, and remove its association to all resources, with a DELETE request to /v2/tags/tag_name:

curl -X DELETE \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
"https://api.digitalocean.com/v2/tags/tag_name"

The tag will be completely removed.

Conclusion

Tagging is a simple abstraction, but in combination with basic scripting tools, it can offer a powerful mechanism for inventorying and managing your systems.

From here, you may wish to dig deeper into the detailed DigitalOcean API documentation, or investigate libraries which wrap the API for popular programming languages.