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. It’s not yet exposed via the Control Panel, but is available to users of the API. 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 must be created before they can be applied to resources. 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}}}}

Note: This request, like any other request that makes a change to your account, requires that your token has “write” scope assigned to it.

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

Once you have created a tag, you can apply it to 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"

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"

Performing Actions on Tagged Droplets

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

Data	Notes
`{"type":"power_cycle"}`	Turn Droplets off and back on again.
`{"type":"power_on"}`	Power Droplets on. Must be off.
`{"type":"power_off"}`	Power Droplets off. Must be on.
`{"type":"shutdown"}`	Shutdown Droplets, similar to powering down from the command line.
`{"type":"enable_private_networking"}`	Enable private networking.
`{"type":"enable_ipv6"}`	Enable IPv6 addresses for Droplets.
`{"type":"enable_backups"}`	Enable backups for Droplets.
`{"type":"disable_backups"}`	Disable backups.
`{"type":"snapshot, "name": "snapshot_name"}`	Take snapshots of Droplets. Droplets must be powered off first, and a `name` is mandatory.

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"

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"

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 read the official preview documentation for tagging, dig deeper into the detailed DigitalOcean API documentation, or investigate libraries which wrap the API for popular programming languages.

Source: DigitalOcean News

Cloud Init Technologies

More than just the integrator