Labeling or Tagging Resources

To help organize your project, you can add arbitrary labels to your resources. Add labels to indicate different environments, services, teams, and so on. Labels also let you take advantage of features like nested filtering so you can perform more precise searches for resources at a later time.

In addition to labels, you can also assign tags to instances that are used for networking purposes. You can only use tags on instances; it is not possible to tag other resources.

Before you begin

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. Labels are added as key/value pairs.

Apply labels to any of these resources:

  • Virtual machine instances
  • Persistent disks
  • Persistent disk snapshots
  • Images

Restrictions

  • Labels can only be managed through the Compute Engine Beta API, or through the Google Cloud Platform Console. Labels are currently not supported through the gcloud command-line tool.
  • You can assign up to 64 labels to each resource.
  • You can only label instances, disks, snapshots, and images.

Relationship between instance labels and instance tags

Instance tags are used for networking purposes, while labels are used to organize and group together related entities. Using the same values for both could simplify your organizational and networking needs.

Tags and labels are designed so that when you add a tag, it is also added as an empty label. The opposite is also true: when you add a label, the key of the label is added as a tag to the instance. Networks and firewalls do not use labels, but will recognize the label keys that are added as instance tags. When you update tags or labels, the same changes are applied to the other property.

Consider a scenario where this would be useful. If you are running a website that has both frontend and backend instances, you could assign the following labels to your frontend instances:

  • webserver-frontend:homepage
  • webserver-frontend:videos
  • webserver-frontend:downloads
  • webserver-frontend:images

When you add these labels to your instances, the key, webserver-frontend, is added as a tag to each of the instances. You can then use the tag to apply networking and firewall settings to all instances with this tag. Additionally, label values are a simple but effective way to keep track of which virtual machine instance is responsible for hosting what content.

A description of one of these instances might look like this:

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

 "kind": "compute#instance",
 "id": "4392196237934605253",
 ....
 "tags": {
  "items": [
   "webserver-frontend"
  ],
  "fingerprint": "p1ty_9HoBk0="
 ...
 "labels": {
  "webserver-frontend": "videos"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Labeling instances

Add labels to your instances to organize and manage instances better than with instance names alone. When you add labels to an instance, you also add an instance tag automatically. Although labels primarily help you organize instances and tags are used for networking purposes, understanding how labels and tags work together can help you better manage your instances.

To add or change labels for an instance, make a POST request to the instance().setLabels method. The request body must contain the labels you want to add or update and the latest labelFingerprint value. Similar to the process of updating metadata, a matching fingerprint is required so that only one update can be made at a time, preventing any collisions with other requests.

Console

  1. Go to the Instances page.
  2. Select the checkboxes next to the instances you want to label.
  3. Click on the labels icon in the top-right of the page to add labels to these instances:
    Labels icon screenshot

API

Caution: Making an update to labels will update your tags as well. To make sure your current tags are not removed, include them as value-less labels.

To add a label, make a request to setLabels with the latest fingerprint and a full list of labels to apply to the instance. Make sure to include any existing labels or tags you want to keep:

Request

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

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

  200 OK

{ "kind": "compute#operation", "id": "7267501453944713366", "name": "operation-1442412647955-51fdddd803a39-7b676304-6ad3aeba", "zone": "https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-f", "operationType": "setLabels", "targetLink": "https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-f/instances/example-instance", "targetId": "3695723120564113978", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2015-09-16T07:10:49.402-07:00", "startTime": "2015-09-16T07:10:49.943-07:00", "selfLink": "https://www.googleapis.com/compute/beta/projects/..." }

Labeling other resources

Apply labels to persistent disks, snapshots, and images to easily group together related resources. Add a label through the Cloud Platform Console, or the API. The gcloud tool does not yet support labels.

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 on the labels icon in the top-right of the page to add labels to these resources:
    Labels icon screenshot

API

To add or update a label, make a POST request to the setLabels method of the appropriate resource with the latest fingerprint and a full list of labels to apply. Include any existing labels or tags you want to keep.

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/beta/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels

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

  200 OK

{ "kind": "compute#operation", "id": "7267501453944713366", "name": "operation-1442412647955-51fdddd803a39-7b676304-6ad3aeba", "zone": "https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-f", "operationType": "setLabels", "targetLink": "https://www.googleapis.com/compute/beta/projects/myproject/zones/us-central1-f/instances/example-instance", "targetId": "3695723120564113978", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2015-09-16T07:10:49.402-07:00", "startTime": "2015-09-16T07:10:49.943-07:00", "selfLink": "https://www.googleapis.com/compute/beta/projects/..." }

Getting a label fingerprint

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 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/beta/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/beta/projects/myproject/zones/us-central1-f",
 "status": "RUNNING",
 ...
 "labels": {
  "env": "test"
 },
 "labelFingerprint": "p1ty_9HoBk0="
}

Tagging instances

Assign tags to help you easily apply networking or firewall settings. Tags are used by networks and firewalls to identify which instances that certain firewall rules apply to. For example, if there are several instances that perform the same task, such as serving a large website, you can tag these instances with a shared word or term and then use that tag to give HTTP access to those instances. Tags are also reflected in the metadata server, so you can use them for applications running on your instances.

Console

  1. Go to the VM Instances page.
  2. Click on the instance you want to add or update tags for.
  3. Under Tags, click the Edit button to edit tags.

gcloud

To assign or update tags a running instance using the gcloud tool, use the instances add-tags command:

gcloud compute instances add-tags INSTANCE --tags tag-1,tag-2

The gcloud command-line tool automatically gets and provides the fingerprint for your request and also ensures that any existing tags you have are still applied to the instance if you did not explicitly specify that tag. This is different from direct API requests, where you must provide the fingerprint and explicitly provide new tags and any existing tags you want to keep.

API

Caution: Updating tags in the API will override any existing tags you have, and in turn, also override any labels. If you need to keep existing tags and labels, make sure to include all of the tags you want to apply to the instance in your request. For example, to add a tag my-awesome-vm to a list of current tags that includes butter, cheese, and milk, make sure your request contains all four tags.

To update or add a tag, make a POST request to the instance().setTags method. The request body must contain the tags you want to add or update and the latest fingerprint value. Similar to the process of updating metadata, a matching fingerprint is required so that only one update can be made at a time, preventing any collisions with other requests. For example:

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

{
 "items": [
  "butter",
  "cheese",
  "milk",
  "my-awesome-vm"
 ],
 "fingerprint": "a_a9fkXkDsA="
}

 200 OK

{ "kind": "compute#operation", "id": "9251830049681941507", "name": "operation-1442414898862-51fde63aa57b1-422323e0-c439fb04", "zone": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f", "operationType": "setTags", "targetLink": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance", "targetId": "4392196237934605253", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2015-09-16T07:48:18.946-07:00", "startTime": "2015-09-16T07:48:19.208-07:00", "selfLink": "https://www.googleapis.com/compute/v1/projects/..." }

Getting a tag fingerprint

To get the latest tag fingerprint so you can make your request, get information about the instance. A fingerprint is required only when updating or adding tags through the API.

gcloud

Using the gcloud command-line tool, run the following command, replacing example-instance with the instance name. Look for the fingerprint property under tags property:

  gcloud compute instances describe example-instance

...
tags:
fingerprint: 42WmSpB8rSM=

API

In the API, perform a GET request to the instance and look for the tags.fingerprint property:

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

200 OK

{ ... "tags": { "items": [ "butter", "cheese" ], "fingerprint": "MW8EqhxILtc=" }, ... }

Removing tags

Console

  1. Go to the VM Instances page.
  2. Click on the instance you want to add or update tags for.
  3. Click the Edit button to edit the instance.
  4. Under Tag, click the X for tags you want to remove.
  5. Save your changes.

gcloud

To remove tags using the gcloud tool, use the instances remove-tags command:

gcloud compute instances remove-tags [INSTANCE_NAME] --tags tag-1,tag-2

The gcloud tool automatically gets and provides the fingerprint for your request and also ensures that any existing tags you have are still applied to the instance if you did not explicitly specify that tag. This is different from direct API requests, where you must provide the fingerprint and explicitly specify existing tags you want to keep.

API

Caution: Updating tags in the API will override any existing tags you have. If you need to keep existing tags, make sure to include those tags in your request. For example, to remove a tag my-awesome-vm from a list of current tags that includes butter, cheese, and milk, make sure your request contains all tags but the my-awesome-vm tag.

To remove a tag, make a POST request to the instance().setTags method. The request body must contain the resulting list of the tags you want on the instance, omitting the tags you want to remove, along with the latest fingerprint value. Similar to the process of updating metadata, a matching fingerprint is required so that only one update can be made at a time, preventing any collisions with other requests.

For example, to remove my-awesome-vm from the list of tags but keep butter, cheese, and milk, the API request would contain the latter three tags and omit the my-awesome-vm tag:

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

{
 "items": [
  "butter",
  "cheese",
  "milk"
 ],
 "fingerprint": "a_a9fkXkDsA="
}

 200 OK

{ "kind": "compute#operation", "id": "9251830049681941507", "name": "operation-1442414898862-51fde63aa57b1-422323e0-c439fb04", "zone": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f", "operationType": "setTags", "targetLink": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance", "targetId": "4392196237934605253", "status": "PENDING", "user": "user@example.com", "progress": 0, "insertTime": "2015-09-16T07:48:18.946-07:00", "startTime": "2015-09-16T07:48:19.208-07:00", "selfLink": "https://www.googleapis.com/compute/v1/projects/..." }

Send feedback about...

Compute Engine Documentation