How to Tag Droplets

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.


Tags are custom labels you can apply to Droplets and other DigitalOcean resources. You can filter tagged Droplets, automatically include Droplets in DigitalOcean Firewall or Load Balancer configurations by tag, create monitoring alert policies for groups of tagged Droplets, and use the DigitalOcean API to initiate an action across multiple Droplets with the same tag.

Choosing terms that describe a Droplet’s function can help you locate and administer Droplets that share common roles. For example, you might tag Droplets by:

  • Environment, like production, staging or development.
  • Application, like web servers (Apache) or database servers (MariaDB).
  • Purpose, like a project name or any other key term that describes the use of the Droplet.
  • Person, like the individual or team responsible for managing the Droplet.

You can add tags to Droplets during or after creation.

Limits

  • Tags must be a single word containing only letters, numbers, colons, dashes, and underscores.

Known Issues

  • You cannot edit existing tags. Instead, create a new tag, apply it to the appropriate resources, and delete the old one.
  • Tag names are case stable, which means the capitalization you use when you first create a tag is canonical.
    • Tagged resources in the control panel always displays the canonical capitalization. For example, if you create a tag named PROD, you can tag resources in the control panel by entering prod. The tag still displays with its canonical capitalization, PROD.
    • When working with tags in the API, you must use the tag’s canonical capitalization. For example, if you create a tag named PROD, the URL to add that tag to a resource would be https://api.digitalocean.com/v2/tags/PROD/resources (not /v2/tags/prod/resources).

Automate the Tagging of Droplets

Note
When tagging a Droplet via API you will need to have already created a tag. Using doctl has no such requirement.
How to tag a Droplet using the DigitalOcean CLI

To tag a Droplet via the command-line, follow these steps:

  1. Install doctl, the DigitalOcean command-line tool.

  2. Create a personal access token, and save it for use with doctl.

  3. Use the token to grant doctl access to your DigitalOcean account.

                  doctl auth init
                
  4. Finally, tag a Droplet with doctl compute droplet tag. The basic usage looks like this, but you'll want to read the usage docs for more details:

                  doctl compute droplet tag <droplet-id|droplet-name> [flags]
                
How to tag a Droplet using the DigitalOcean API

To tag a Droplet using the DigitalOcean API, follow these steps:

  1. Create a personal access token, and save it for use with the API.

  2. Send a POST request to https://api.digitalocean.com/v2/tags/{tag_id}/resources

    cURL

    To tag a Droplet with cURL, call:

    
                    curl -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
      -d '{"resources":[{"resource_id":"9569411","resource_type":"droplet"},{"resource_id":"7555620","resource_type":"image"},{"resource_id":"3d80cb72-342b-4aaa-b92e-4e4abb24a933","resource_type":"volume"}]}' \
      "https://api.digitalocean.com/v2/tags/awesome/resources"

    Go

    Go developers can use Godo, the official DigitalOcean V2 API client for Go. To tag a Droplet with Godo, use the following code:

    
                    import (
        "context"
        "os"
    
        "github.com/digitalocean/godo"
    )
    
    func main() {
        token := os.Getenv("DIGITALOCEAN_TOKEN")
    
        client := godo.NewFromToken(token)
        ctx := context.TODO()
    
        opt := &godo.ListOptions{
            Page:    1,
            PerPage: 200,
        }
        tags, _, err := client.Tags.List(ctx, opt)
    }

    Ruby

    Ruby developers can use DropletKit, the official DigitalOcean V2 API client for Ruby. To tag a Droplet with DropletKit, use the following code:

    
                    require 'droplet_kit'
    token = ENV['DIGITALOCEAN_TOKEN']
    client = DropletKit::Client.new(access_token: token)
    
    client.tags.tag_resources(name: 'awesome', resources: [{ resource_id: '9569411', resource_type: 'droplet' },{ resource_id: '7555620', resource_type: 'image' },{ resource_id: '3d80cb72-342b-4aaa-b92e-4e4abb24a933', resource_type: 'volume'}])

    Python

    
                    import os
    from pydo import Client
    
    client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
    
    req = {
      "resources": [
        {
          "resource_id": "9569411",
          "resource_type": "droplet"
        },
        {
          "resource_id": "7555620",
          "resource_type": "image"
        },
        {
          "resource_id": "3d80cb72-342b-4aaa-b92e-4e4abb24a933",
          "resource_type": "volume"
        }
      ]
    }
    
    resp = client.tags.assign_resources(tag_id="awesome", body=req)

Tag Droplets During Creation

To add tags while creating a new Droplet, at the bottom of the Droplet create page, look for the Finalize Details section.

The Finalize Details section of the Droplet creation menu, including the Tags section.

In the Tags field, enter the tags. Add multiple tags by pressing SPACEBAR or ENTER after each term. Navigate between tags with the arrow keys, and remove the highlighted tag with DELETE or the last tag on the list with BACKSPACE.

Tag Existing Droplets

To add or modify tags for existing Droplets, use the Droplet’s More menu and select Edit tags or, from the Droplet’s detail page, use the Tags link.

The Droplet tags page

On a project’s dashboard, you can hover over an untagged Droplet’s row of information to reveal the Add tags link.

No matter which way you navigate, the Manage Tags window opens.

The Manage Tags window

Add tags by pressing SPACEBAR or ENTER after each term. Navigate between tags with the arrow keys, and remove the highlighted tag with DELETE or the last tag on the list with BACKSPACE.

When you’re done, click Save Tags.

Filter by Tag

If you click on a tag from anywhere in the control panel, like on the dashboard of a project or on a Droplet’s Tags page, you go to the list of all resources with that tag.

An example of a list of resources with a tag. There are 3 Droplets with the tag 'webserver'.

Filter lists are limited to a single tag, displayed at the top of the list.