Using Labels

This page gives a brief overview of labels and explains how to create and manage labels using the Google Cloud Resource Manager API and the Google Cloud Platform Console.

What are labels?

A label is a tool that helps you organize your Google Cloud Platform resources. You can attach a label to your resources, for example, you can label resources by environment (test or prod) and owner (alice or bob) and then filter the resources based on what they're used for and who the owners are. Filtering with labels helps you to easily find the resources you're looking for.

A label entity is a key:value pair that you can attach to a project or a virtual machine (VM). VM tags that you defined in the past will also show up as value-less labels.

Common uses of labels

Here are some typical ways for you to use labels:

  • Labels based on team or cost center. Add labels based on team or cost center to distinguish projects owned by different teams. This can be used in cost accounting or budgeting. For example, team:marketing and team:research.

  • Labels based on component. For example, component:redis and component:frontend.

  • Labels based on environment or stage. For example, environment:prod and environment:test.

  • Labels based on owner or contact. Add labels based on owner or a primary contact if there's an individual who is responsible for a resource and is the primary contact for the resource.

  • Labels based on state. For example, state:inuse and state:readyfordeletion.

Labels applied to resources that generate usage metrics are forwarded to the billing system so that you can break down your billing charges based upon label criteria. There are some system limits which, when hit, cause labels data to be discarded. Specifically, for a given reporting service and project, the number of distinct label maps that will be preserved within a 1 hour time window is 1,000. For example, the Compute Engine service reports metrics on VM instances. If you deploy a project with 2,000 VMs, each of which is labeled distinctly, then only the first 1,000 label maps seen within the 1 hour window will be preserved.

Creating and managing labels via the Resource Manager API

To create a new project with a label, just set the label field while creating the project.

REST

Request:
POST https://cloudresourcemanager.googleapis.com/v1beta1/projects

{
 "labels": {
  "color": "red"
 },
 "name": "myproject",
 "projectId": "our-project-123"
}
Response:

{
 "projectNumber": "333197460082",
 "projectId": "our-project-123",
 "lifecycleState": "ACTIVE",
 "name": "myproject",
 "labels": {
  "color": "red"
 },
 "createTime": "2016-01-12T22:18:28.633Z",
}

Python Client Library

...

  project = crm.projects().create(
    body={
        'project_id': flags.projectId,
        'name': 'myproject',
        labels.color: "red"
}).execute()

...


To add labels for existing projects:

  • Get the project using the get() method.
  • Modify the label field.
  • Update the project using the update() method.

For information and code snippets on updating projects see Updating a Project.

One of the main advantages of labels is that it enables you to filter projects. For information and code snippets on filtering projects on labels see Listing Projects.

Creating and managing labels via the Cloud Platform Console

To add labels to a single project:

  1. Open the IAM & Admin page in the Cloud Platform Console.

    Open the IAM page

  2. Select your project from the Select a project drop-down box and click Continue.
  3. In the left nav, click Labels.
  4. Click + Add item.
  5. Add a label key and value and click Save. You can add more label values by clicking + Add item.

To add labels for more than one project at the same time:

  1. Open the IAM & Admin Projects page in the Cloud Platform Console.

    Open the IAM & Admin Projects page

  2. In the center pane, select the projects for which you want to add labels.
  3. In the right pane, click the Labels tab.
  4. Click + Add Item.
  5. Enter the label key and value and click Save.

After adding labels, you can filter projects using the labels. Just type a key or value to the search box above the projects list. The search box will auto-suggest the right queries and allow you to preview results.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Google Cloud Resource Manager Documentation