Organize resources using labels

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

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

Before you begin

Read thepersistent disksdocumentation.
Read theimages documentation.
If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:
  gcloudinit
  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
2. Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

What are labels?

A label is a key-value pair that you can assign to Google Cloud instances.They help you organize these resources and manage your costs at scale, with thegranularity you need. You can attach a label to each resource, then filter theresources based on their labels. Information about labels is forwarded to the billing system thatlets you break down your billed charges by label. With built-inbilling reports,you can filter and group costs by resource labels. You can also use labels toquerybilling data exports.

Requirements for labels

The labels applied to a resource must meet the followingrequirements:

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

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

Common uses of labels

Here are some common use cases for labels:

Team or cost center labels: Add labels based on team orcost center to distinguish instances owned by differentteams (for example,team:research andteam:analytics). You can use thistype of label for cost accounting or budgeting.
Component labels: For example,component:redis,component:frontend,component:ingest, andcomponent:dashboard.
Environment or stage labels: For example,environment:production andenvironment:test.
State labels: For example,state:active,state:readytodelete, andstate:archive.
Ownership labels: Used to identify the teams that areresponsible for operations, for example:team:shopping-cart.

Virtual machine labels: A label can be attached toa virtual machine. Virtual machine tags that you defined in the past appearas a label without a value.

Note: Don't include sensitive information in labels, includingpersonally identifiable information, such as an individual's name or title.Labels are not designed to handle sensitive information.

We don't recommend creating large numbers of unique labels, such asfor timestamps or individual values for every API call.The problem with this approach is that when the values change frequently or withkeys that clutter the catalog, this makes it difficult to effectively filter andreport on resources.

Labels and tags

Labels can be used as queryable annotations for resources, but can't be usedto set conditions on policies. Tags provide a way to conditionally allow ordeny policies based on whether a resource has a specific tag, by providing fine-grainedcontrol over policies. For more information, see the Tags overview.

Use 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 thefollowing:

Cloud Storage buckets
Networking resources:
- Forwarding rules used with internal Application Load Balancers (other load balancer forwardingrules aren't supported)
- VPN tunnels
- Static external IP addresses

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

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

Create resources with labels

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

Note: You can't add labels to forwarding rules, static external IP addresses,and VPN tunnels when creating these resources. You can only add labels to thesenetworking resources when you're updating the resource. For instructions onadding labels during an update, see Add or update labels to existing resourcesin this document.

Console

Go to the resource page that you want to create.
- For VM instances, go toCreate an instance.
- For disks, go toCreate a disk.
- For snapshots, go toCreate a snapshot.
- For images, go toCreate an image.
UnderLabels, clickAdd label.
Continue with the creation process.

gcloud

To add a label, use thecreate sub-command with the--labels flag. Youcan add labels to the Compute Engine resources by using thefollowinggcloud commands:

For VM instances, use thegcloud compute instances create command.
For snapshots, use thegcloud compute disks snapshot command.
For images, use thegcloud compute images create command.
For disks, use thegcloud compute disks create command.

Example

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

REST

In the API, during thePOST request to add a new resource, add thelabels property in the request body to apply labels to the new resource.

For VM instances, use theinstances.insert() method.
For snapshots, use thedisks.createSnapshot() method.
For images, use theimages.insert() method.
For disks, use thedisks.insert() method.

For example, the following snippet makes aPOST request to create a VMinstance with the labelswebserver:backend andmedia: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"  }}

Add or update labels to existing resources

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

Console

Go to the resource page for which you want to add labels.
- For VM instances, go toVM instances.
- For snapshots, go toSnapshots.
- For images, go toImages.
- For disks, go toDisks.
- For static external IP addresses, go toExternal IP addresses.
- For VPN tunnels, go toVPN.
Select the checkboxes next to the resources you want to label.
To expand the labels column, clickShow info panel.
In the panel, selectLabels.
To add labels, clickAddlabel and add the key-value pair.
To update labels, select the existing labels and modify their values.
Save your changes.

gcloud

To add or change a label, use theupdate sub-command with the--update-labels flag. You can update labels for the Compute Engineresources by using the followinggcloud commands:

For VM instances, use thegcloud compute instances updatecommand.
For snapshots, use thegcloud compute snapshots updatecommand.
For images, use thegcloud compute images updatecommand.
For disks, use thegcloud compute disks updatecommand.
For forwarding rules, use thegcloud compute forwarding-rulesupdate command.
For static external IP addresses, use thegcloud beta compute addresses update command.
For VPN tunnels, use thegcloud beta compute vpn-tunnels updatecommand.

Example

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

If you provide a label key that already exists, the Google Cloud CLI updatesthe existing key with the new label value. If you provide a new key, thetool adds the new key to the list of labels.

REST

To add or update labels, make aPOST request to thesetLabels method of the resource with the latestfingerprintand a full list of labels to apply:

For VM instances, use theinstances.setLabels() method.
For snapshots, use thesnapshots.setLabels() method.
For images, use theimages.setLabels() method.
For disks, use thedisks.setLabels() method.
For forwarding rules, use theforwardingRules.setLabels() method.
For regional static external IP addresses, use the betaaddresses.setLabels() method.
For global static external IP addresses, use the betaglobalAddresses.setLabels() method.
For VPN tunnels, use thebetavpnTunnels.setLabels() method.

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

For example, the following snippet makes aPOST request to a VM instanceto set labelsenvironment:test andan-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="}

View labels

You can view labels for resources by using the Google Cloud console, thegcloud CLI, or the Compute Engine API. To view labels forforwarding rules, use the gcloud CLI or the Compute Engine API.

Console

Go to the resource page.
- For VM instances, go toVM instances.
- For snapshots, go toSnapshots.
- For images, go toImages.
- For disks, go toDisks.
- For static external IP addresses, go toExternal IP addresses.
- For VPN tunnels, go toVPN.
Click the resource to view its details.
LocateLabels.

gcloud

To view labels, use thedescribe sub-command. You can view labels for theCompute Engine resources by using thefollowinggcloud commands:

For VM instances, use thegcloud compute instances describecommand.
For snapshots, use thegcloud compute snapshots describecommand.
For images, use thegcloud compute images describecommand.
For disks, use thegcloud compute disks describecommand.
For forwarding rules, use thegcloud compute forwarding-rulesdescribe command.
For static external IP addresses, use thegcloud beta compute addressesdescribe command.
For VPN tunnels. use thegcloud beta compute vpn-gateways describecommand.

Example

gcloud compute disks describe example-disk

The output contains the labels:

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

REST

To retrieve labels, make aGET request to the following resource:

For VM instances, use theinstances.get() method.
For snapshots, use thesnapshots.get() method.
For images, use theimages.get() method.
For disks, use thedisks.get() method.
For forwarding rules, use theforwardingRules.get() method.
For regional static external IP addresses, use thebetaaddresses.get() method.
For global static external IP addresses, use thebetaglobalAddresses.get() method.
For VPN tunnels, use thebetavpnTunnels.get() method.

For example, the following snippet makes aGET request to retrieve labelsfor 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

Get a label fingerprint for API requests

When updating or adding labels in the API, you need to provide the latest labelsfingerprint with your request, to prevent any conflicts with other requests.A fingerprint is only required for API requests; theGoogle Cloud console andthe Google Cloud CLI tool do not require a fingerprint.

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

To get the latestlabelsFingerprint, make aGET request to the followingresources:

For VM instances, use the instances.get() method.
For snapshots, use thesnapshots.get() method.
For images, use theimages.get() method.
For disks, use thedisks.get() method.
For forwarding rules, use theforwardingRules.get() method.
For regional static external IP addresses, use thebetaaddresses.get() method.
For global static external IP addresses, use thebetaglobalAddresses.get() method.
For VPN tunnels, use thebetavpnTunnels.get() method.

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

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

The response contains thelabelFingerprint 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="}

Remove a label

You can remove labels from resources by using the Google Cloud console, thegcloud CLI, or the Compute Engine API. To remove labels forforwarding rules, use the gcloud CLI or the Compute Engine API.

Console

Go to the resource page for which you want to remove labels.
- For VM instances, go toVM instances.
- For snapshots, go toSnapshots.
- For images, go toImages.
- For disks, go toDisks.
- For static external IP addresses, go toExternal IP addresses.
- For VPN tunnels, go toVPN.
Select the checkboxes next to the resources for which you want to removelabels.
To expand the labels column, clickShow info panel.
To delete a label, clickDelete.
Save your changes.

gcloud

To add or change a label, use theupdate sub-command with the--remove-labels flag. You can remove labels for the Compute Engineresources by using the followinggcloud commands:

For VM instances, use thegcloud compute instances updatecommand.
For snapshots, use thegcloud compute snapshots updatecommand.
For images, use thegcloud compute images updatecommand.
For disks, use thegcloud compute disks updatecommand.
For forwarding rules, use thegcloud compute forwarding-rulesupdate command.
For static external IP addresses, use thegcloud beta compute addresses updatecommand.
For VPN tunnels, use thegcloud beta compute vpn-tunnels updatecommand.

Example

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

REST

To remove labels, make aPOST request to thesetLabels method of thefollowing resource with the latestfingerprintand a full list of labels to apply:

For VM instances, use theinstances.setLabels() method.
For snapshots, use thesnapshots.setLabels() method.
For images, use theimages.setLabels() method.
For disks, use thedisks.setLabels() method.
For forwarding rules, use theforwardingRules.setLabels() method.
For regional static external IP addresses, use thebetaaddresses.setLabels() method.
For global static external IP addresses, use thebetaglobalAddresses.setLabels() method.
For VPN tunnels, use thebetavpnTunnels.setLabels() method.

Provide the currentlabelsFingerprint and an empty list of labels toremove all labels, or provide a list of labels you want to keep (omittingthe labels you want to remove). For example, the following snippet removesall labels from the VM:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-f/instances/example-instance/setLabels{ "labels": { }, "labelFingerprint": "42WmSpB8rSM="}

Filter searches using labels

You can search your resources and filter results by labels by using theGoogle Cloud console, the gcloud CLI, or the Compute Engine API.To filter forwarding rules by labels, use the gcloud CLI or theCompute Engine API.

Console

Go to the resource page for which you want to get a filtered list ofresources.
- For VM instances, go toVM instances.
- For snapshots, go toSnapshots.
- For images, go toImages.
- For disks, go toDisks.
- For static external IP addresses, go toExternal IP addresses.
- For VPN tunnels, go toVPN.
If prompted, select your project and clickContinue.
In the search bar, enter your key, value, or key-value pair. Yourresults include any partial matches.
For example, to show only resources with the labelenv:dev, youcan 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 thelist sub-command of the followingresources with the--filter flag:

For VM instances, use thegcloud compute instances listcommand.
For snapshots, use thegcloud compute snapshots listcommand.
For images, use thegcloud compute images listcommand.
For disks, use thegcloud compute disks listcommand.
For forwarding rules, use thegcloud compute forwarding-rules listcommand.
For static external IP addresses, use thegcloud beta compute addresses listcommand.
For VPN tunnels, use thegcloud beta compute vpn-tunnels listcommand.

The value of--filter flag must be in thelabels.KEY=VALUE format. For example,if you wanted to filter on a label withenv as the key anddev as thevalue, you can run this command:

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

For more information about the filter syntax in the gcloud CLI,see thegcloud topic filters documentation.

REST

To filter resources, make aGET request to thelist method of thefollowing resources and include the filter field:

For VM instances, use theinstances.list() method.
For snapshots, use thesnapshots.list() method.
For images, use theimages.list() method.
For disks, use thedisks.list() method.
For forwarding rules, use theforwardingRules.list() method.
For regional static external IP addresses, use thebetaaddresses.list() method.
For global static external IP addresses, use thebetaglobalAddresses.list() method.
For VPN tunnels, use thebetavpnTunnels.list() method.

For example, to list all the VMs in the projectmyproject and zoneus-central1-a with a label that has a key-value pair ofenv:dev, set thefilter field tolabels.env:dev in yourlist request. If you include thefilter field as a query string parameter, use a URL-encoded parameter value,filter=labels.env%3Adev:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances?filter=labels.env%3Adev

For more information, read thefilter documentationin the Compute Engine API reference.

Relationship between VM labels and tags

In the past, labels and tags were related. For example, if you added awebserver:test label to a VM, Compute Engine automaticallyadded awebserver 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 youneed to create a tag on a VM, you must create the tag manually.

To learn more about tags and their uses, seeTags overview.

What's next

Learn how tocompare Tags and network tags.
Learn how tomanage tags for Compute Engine resources.
Review thefilter query parameter to learn aboutfiltering.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.

Movatterモバイル変換

Organize resources using labels Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

What are labels?

Requirements for labels

Common uses of labels

Labels and tags

Use labels on Compute Engine

Create resources with labels

Console

gcloud

REST

Add or update labels to existing resources

Console

gcloud

REST

View labels

Console

gcloud

REST

Get a label fingerprint for API requests

Remove a label

Console

gcloud

REST

Filter searches using labels

Console

gcloud

REST

Relationship between VM labels and tags

What's next

Organize resources using labels