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 vmrole:webserver, environment:production, location:west, and so on. You always add labels as key/value pairs:

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

Apply labels to any of these resources:

• Virtual machine instances
• Forwarding rules (beta)
• Images
• Persistent disks
• Persistent disk snapshots
• Cloud Storage buckets
• Static external IP addresses (beta)
• VPN tunnels (beta)

Note: You can only add labels to networking resources (forwarding rules, static external IP addresses, and VPN tunnels) when updating the resource. You cannot add labels to these resources when creating them.

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

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Read the persistent disks documentation.
• Read the images documentation.

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 Console. Instead, use the Compute Engine API (alpha) to set labels for these resources.

Label format

• Label keys and values must conform to the following format:

  • Keys and values cannot be longer than 63 characters each.
  • Keys and values can only contain:
    • Lowercase letters
    • Numeric characters
    • Underscores
    • Hyphens
  • International characters are allowed.
  • Label keys must start with a lowercase letter.
  • Label keys cannot be empty.

Creating resources with labels

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

Console

Note: In the console, only creation of VM instances support specifying labels. For other resources, you can add labels after creation.

1. Go to the Create an Instance page

   Go to the Create an Instance page

2. Expand the Management, security, disks, networking, sole tenancy section.
3. Under Management, specify the Labels you want to add to this resource.
4. Continue with the creation process.

gcloud

Note: It is not possible to specify labels when creating a snapshot. However, you can add labels to a snapshot after it has been created.

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

Note: It is not possible to specify labels when creating a snapshot. However, you can add labels to a snapshot after it has been created.

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.
   • For instances, go to the VM instances page.
   • For disks, go to the Disks page.
   • For snapshots, go to the Snapshots page.
   • For images, go to the Images page.
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://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

{
 "labels": {
  "environment": "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 Console and the gcloud tool does not require a fingerprint.

Note: You can only get the label fingerprint by making a query directly to the API.

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://compute.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": {
  "environment": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Removing a label

Console

1. Go to the respective resource page for which you want to add labels.
   • For instances, go to the VM instances page.
   • For disks, go to the Disks page.
   • For snapshots, go to the Snapshots page.
   • For images, go to the Images page.
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-labels 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://compute.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.
   • For instances, go to the VM instances page.
   • For disks, go to the Disks page.
   • For snapshots, go to the Snapshots page.
   • For images, go to the Images page.
   • If prompted, select your project and click Continue.
   • 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://compute.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 Compute Engine API reference.

Relationship between instance labels and network tags

In the past, labels and tags were related. For example, if you added a webserver:test label to a VM instance, Compute Engine automatically added a webserver tag to the instance.

Now, labels and tags are separate. If you create a label on an instance, Compute Engine does not create a tag for the instance. If you need to create a tag on an instance, you must create the tag manually.

To learn how to create tags, read the Network tags page.

What's next

• Learn how to add network tags.
• Learn about filtering.