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
- Images
- Persistent disks
- Persistent disk snapshots
- Cloud Storage buckets
- Static external IP addresses (beta)
- VPN tunnels (beta)
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:
- Install or update to the latest version of the gcloud command-line tool.
- 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.
Label format
Label keys and values must conform to the following regex expression:
- 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
In the Google Cloud Console, go to the Create an instance page.
Under Labels, click Add label.
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
- 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.
- Select the checkboxes next to the resources you want to label.
- Click Show info panel to expand the labels column.
- Update or add new labels as desired.
- Save your changes.
gcloud
Using the gcloud
command-line tool, use the update
subcommand with the
--add-labels
flag to add or change a label. For example, to add a label to
a disk, use the gcloud compute disks update [DISK] --add-labels
subcommand:
gcloud compute disks update example-disk --add-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.
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
- 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.
- Select the checkboxes next to the resources for which you want to remove labels.
- Click Show info panel to expand the labels column.
- Click the
X
next to all the labels you want to remove. - 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
- 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.