Creating and managing labels

Labels are key-value pairs that can be used on Google Cloud to group related or associated resources. For example, on Compute Engine, you can use labels to group VMs in categories such as production, staging, or development so that you can search for resources that belong to each development stage.

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

Before you begin

What are labels?

A label is a key-value pair that helps you organize your Google Cloud instances. You can attach a label to each resource, then filter the resources based on their labels. Information about labels is forwarded to the billing system, so you can break down your billed charges by label.

Labels can be used as queryable annotations for resources, but can't be used to set conditions on policies. Tags provide a way to conditionally allow or deny policies based on whether a resource has a specific tag. For more information, see the Tags overview.

Common uses of labels

We do not recommend creating large numbers of unique labels, such as for timestamps or individual values for every API call. Here are some common use cases for labels:

  • Team or cost center labels: Add labels based on team or cost center to distinguish instances owned by different teams (for example, team:research and team:analytics). You can use this type of label for cost accounting or budgeting.

  • Component labels: For example, component:redis, component:frontend, component:ingest, and component:dashboard.

  • Environment or stage labels: For example, environment:production and environment:test.

  • State labels: For example, state:active, state:readytodelete, and state:archive.

  • Virtual machine labels: A label can be attached to a virtual machine. Virtual machine tags that you defined in the past appear as a label without a value.

Requirements for labels

The labels applied to a resource must meet the following requirements:

  • Each resource can have multiple labels, up to a maximum of 64.
  • Each label must be a key-value pair.
  • Keys have a minimum length of 1 character and a maximum length of 63 characters, and cannot be empty. Values can be empty, and have a maximum length of 63 characters.
  • Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed.
  • The key portion of a label must be unique. However, you can use the same key with multiple resources.
  • Keys must start with a lowercase letter or international character.

These limits apply to the key and value for each label, and to the individual Google Cloud resources that have labels. There is no limit on how many labels you can apply across all resources within a project.

Using labels on Compute Engine

You can apply labels to the following Compute Engine resources:

  • Virtual machine (VM) instances
  • Images
  • Persistent disks
  • Persistent disk snapshots

You can also use labels on related Google Cloud components such as the following:

For example, you can add the following labels as key-value pairs to your resources:

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

Creating resources with labels

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

Console

  1. Go to the resource page that you want to create.

  2. Under Labels, click Add label.

  3. Continue with the creation process.

gcloud

To add a label, use the create sub-command with the --labels flag. You can add labels to the Compute Engine resources by using the following gcloud commands:

Example

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

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, the following snippet makes a POST request to create a VM instance with the labels webserver:backend and media:images:

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

{
 "name": "myVM",
 "machineType": "zones/us-central1-f/machineTypes/custom-2-15360-ext",
  ...,
 "labels": {
   "webserver": "backend",
   "media": "images"
  }
}

Adding or updating labels to existing resources

You can add labels or update existing labels on resources by using the Cloud Console, the gcloud tool, or the Compute Engine API. To add or update labels for forwarding rules, use the gcloud tool or the Compute Engine API.

Console

  1. Go to the resource page for which you want to add labels.

  2. Select the checkboxes next to the resources you want to label.

  3. To expand the labels column, click Show info panel.

  4. In the panel, select Labels.

  5. To add labels, click Add label and add the key-value pair.

  6. To update labels, select the existing labels and modify their values.

  7. Save your changes.

gcloud

To add or change a label, use the update sub-command with the --update-labels flag. You can update labels for the Compute Engine resources by using the following gcloud commands:

Example

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

If you provide a label key that already exists, the gcloud command-line tool updates the existing key with the new label value. If you provide a new key, the tool adds the new key to the list of labels.

API

To add or update labels, make a POST request to the setLabels method of the 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 that you want to add.

For example, the following snippet makes a POST request to a VM instance to set labels environment:test and an-existing-tag:yes:

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

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

Viewing labels

You can view labels for resources by using the Cloud Console, the gcloud tool, or the Compute Engine API. To view labels for forwarding rules, use the gcloud tool or the Compute Engine API.

Console

  1. Go to the resource page.

  2. Click the resource to view its details.

  3. Locate Labels.

gcloud

To view labels, use the describe sub-command. You can view labels for the Compute Engine resources by using the following gcloud commands:

Example

gcloud compute disks describe example-disk

The output contains the labels:

...
id: '5047929990219134234'
kind: compute#disk
labelFingerprint: GHZ1Un209U=0
labels:
  environment: dev
  department: finance
...

API

To retrieve labels, make a GET request to the following resource:

For example, the following snippet makes a GET request to retrieve labels for a VM instance:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

Replace the following:

  • PROJECT_ID: the project ID
  • ZONE: the zone of the VM
  • VM_NAME: the name of the VM

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. A fingerprint is only required for API requests; the Cloud Console and the gcloud command-line tool tool do not require a fingerprint.

To get the latest labelsFingerprint, make a GET request to the following resources:

For example, the following snippet gets a labelsFingerprint for a VM instance:

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

The response contains the labelFingerprint property:

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

You can remove labels from resources by using the Cloud Console, the gcloud tool, or the Compute Engine API. To remove labels for forwarding rules, use the gcloud tool or the Compute Engine API.

Console

  1. Go to the resource page for which you want to remove labels.

  2. Select the checkboxes next to the resources for which you want to remove labels.

  3. To expand the labels column, click Show info panel.

  4. To delete a label, click Delete.

  5. Save your changes.

gcloud

To add or change a label, use the update sub-command with the --remove-labels flag. You can remove labels for the Compute Engine resources by using the following gcloud commands:

Example

gcloud compute disks update example-disk \
    --remove-labels backend,media

API

To remove labels, make a POST request to the setLabels method of the following resource with the latest fingerprint and a full list of labels to apply:

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, the following snippet removes all labels from the VM:

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 by using the Cloud Console, the gcloud tool, or the Compute Engine API. To filter forwarding rules by labels, use the gcloud tool or the Compute Engine API.

Console

  1. Go to the resource page for which you want to get a filtered list of resources.

  2. If prompted, select your project and click Continue.

  3. In the search bar, enter your key, value, or key-value pair. Your results include any partial matches.

    For example, to show only resources with the label env:dev, you can enter any of the following:

    • Enter the key: env
    • Enter the value: dev
    • Enter the key-value pair: env:dev

gcloud

To filter based on labels, use the list sub-command of the following resources with the --filter flag:

The value of --filter flag must be in the labels.KEY=VALUE format. 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 more information about the filter syntax in the gcloud tool, see the gcloud topic filters documentation.

API

To filter resources, make a GET request to the list method of the following resources with a URL-encoded filter query parameter:

For example, to filter based on a label env:dev, make the following GET request with filter=labels.env+eq+dev in the query string:

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 VM labels and network tags

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

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

To learn how to create tags, see Network tags.

What's next