Labeling Resources

Labels are a lightweight way to group together resources that are related or associated with each other. For example, a common practice is to label resources that are intended for production, staging, or development separately, so you can easily search for resources that belong to each development stage when necessary. Your labels might say production:webserver, production:database, dev:webserver, and so on. You always add labels as key/value pairs:

{
 "labels": {
    "production": "webserver",
    "location": "west",...
 }

Apply labels to any of these resources:

  • Virtual machine instances
  • Forwarding rules (Alpha)
  • Images
  • Persistent disks
  • Persistent disk snapshots
  • Static external IP addresses (Alpha)
  • VPN tunnels (Alpha)

After adding labels to your resources, you can take advantage of features like nested filtering to perform more precise searches for your resources using labels.

Before you begin

Restrictions

  • You can assign up to 64 labels to each resource.
  • Resources listed as Alpha do not yet have support in gcloud or the Google Cloud Platform Console. Instead, use the Alpha API to set labels for these resources.
  • Label keys and values must conform to the following restrictions:

    • Keys and values cannot be longer than 63 characters each.
    • Keys and values can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed.
    • Label keys must start with a lowercase letter and international characters are allowed.
    • Label keys cannot be empty.

Creating resources with labels

When creating a new resource, you can apply labels to the resource.

Console

  1. Go to Create an Instance page

    Go to the Create an Instance page

  2. Expand the Management, disk, networking, SSH keys section.
  3. Under Labels, specify the labels you want to add to this resource.
  4. Continue with the creation process.

gcloud

When creating your resource, include the --labels flag, followed by a comma-separated list of key value pairs of labels. For example:

gcloud compute instances create ... --labels webserver=backend,media=images

The same flag applies when creating images and disks as well.

API

In the API, during the POST request to add a new resource, add the labels property in the request body to apply labels to the new resource. For example, your request body for creating a VM instance have the following labels:

body = {
  "name": "[INSTANCE_NAME]",
  "machineType": "zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
   ...,
  "labels": [{
    "key": "webserver",
    "value": "backend"
    },
    {
    "key": "media",
    "value": "images"
   }]
 }

The same property can be applied when creating images and disks as well.

Adding or updating labels to existing resources

You can add labels or update existing labels on resources.

Console

  1. Go to the respective resource page for which you want to add labels.
  2. Select the checkboxes next to the resources you want to label.
  3. Click Show info panel to expand the labels column.
  4. Update or add new labels as desired.
  5. Save your changes.

gcloud

Using the gcloud command-line tool, use the update subcommand with the --update-labels flag to add or change a label. For example, to add a label to a disk, use the gcloud compute disks update [DISK] --update-labels subcommand:

gcloud compute disks update example-disk --update-labels backend=webserver,media=images

If you provide a label key that already exists, the tool will update the existing key with the new label value. If you provide a new key, the tool will add the new key to the list of labels.

For instances, snapshots, and images, use the gcloud compute instances, gcloud compute snapshots, or gcloud compute images commands.

API

To add or update labels, make a POST request to the setLabels method of the appropriate resource with the latest fingerprint and a full list of labels to apply.

Similar to metadata and tags, if the resource has existing labels you want to keep, you must include those labels in the request, along with any new labels you want to add.

For example, the following snippet makes a request to the setLabels method of an instance. You can also make a request to the setLabels method of a disk, snapshot, or image:

Request

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "env": "test",
  "an-existing-tag": ""
 },
 "labelFingerprint": "42WmSpB8rSM="
}

Similarly, you can add labels to resources when creating the resource by specifying the labels object.

Getting a label fingerprint for API requests

When updating or adding labels in the API, you need to provide the latest labels fingerprint with your request, to prevent any conflicts with other requests. This is only required for API requests; the Cloud Platform Console and the gcloud tool does not require a fingerprint.

To get the latest label fingerprint so you can make your request, perform a GET request to respective resource. For example, the following snippet gets a labelsFingerprint for an instance. You can make a similar request to a disk, snapshot, or image.

Look for the labelFingerprint property:

Request

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance
200 OK

{

 "kind": "compute#instance",
 "id": "4392196237934605253",
 "creationTimestamp": "2015-09-15T14:05:16.475-07:00",
 "zone": "https://content.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "env": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Removing a label

Console

  1. Go to the respective resource page for which you want to add labels.
  2. Select the checkboxes next to the resources for which you want to remove labels.
  3. Click Show info panel to expand the labels column.
  4. Click the X next to all the labels you want to remove.
  5. Save your changes.

gcloud

Using the gcloud command-line tool, run the update command with the --remove-labels flag. Provide a set of label keys to remove. For example:

gcloud compute disks update example-disk --remove-label backend,media

For snapshots and images, use the gcloud compute snapshots or gcloud compute images collections.

API

In the API, make a POST request to the setLabels method of the appropriate API resource: instances, disks, and snapshots.

Provide the current labelsFingerprint and an empty list of labels to remove all labels, or provide a list of labels you want to keep (omitting the labels you want to remove). For example:

Request

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": { },
 "labelFingerprint": "42WmSpB8rSM="
}

Filtering searches using labels

You can search your resources and filter results by labels.

Console

  1. Go to the respective resource page for which you want to add labels.
  2. If prompted, select your project and click Continue.
  3. In the search bar, start typing labels. and the search bar will automatically list labels that you can filter on.

gcloud

In gcloud, make a list request and use the --filter flag. To filter on labels, use the syntax labels.key=[VALUE]. For example, if you wanted to filter on a label with env as the key and dev as the value, you can run this command:

gcloud compute instances list --filter labels.env=dev

For complete documentation about the filter syntax in the gcloud tool, see the gcloud topic filters documentation.

API

In the API, make a list request with a URL encoded filter query parameter. For example, to filter based on a label key env being equal to value dev, make the following GET request:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/list?filter=labels.env+eq+dev

For more information, read the filter documentation in the API reference.

Relationship between instance labels and network tags

In previous iterations of this feature, adding a label to a VM instance also automatically added an instance tag. For example, adding a label webserver:test would automatically add a tag webserver to the VM instance. Likewise, adding a tag added a label with the tag as the label key and an empty string as the label value.

Compute Engine has decoupled labels and tags and this is no longer the behavior. Labels and tags are now two separate features and creating one does not automatically create the other.

To create tags, read the Network Tags documentation.

What's next

Send feedback about...

Compute Engine Documentation