Create and update labels for projects

This document provides details on how to create and update labels for projects using the Resource Manager API and the Google Cloud console. It provides details on how to understand costs using labels and the services that support labels.

Create labels for projects

Console

To add labels to a single project:

  1. Open the Labels page in the Google Cloud console.

    Open the Labels page

  2. Select your project from the Select a project drop-down.

  3. To add a new label entry, click + Add label and enter a label key and value for each label you want to add.

  4. When you're finished adding labels, click Save.

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

  1. Open the Manage resources page in the Google Cloud console.

    Open the Manage resources page

  2. On the Manage resources page, select the projects for which you want to add labels.

  3. In the info panel, in the Labels tab, click + Add label and enter a label key and value for each label you want to add.

  4. When you're finished adding labels, click Save.

After you add labels, you can filter projects by typing a label key or value in the filter box above the projects list. The filter box will suggest keys and values so you can preview results.

REST

To create a new project with a label, set the labels field when you create the project.

Request:

POST https://cloudresourcemanager.googleapis.com/v3/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",
}

To add labels for existing projects:

Once you add labels, you can filter projects based on labels. For details about using labels to filter projects, see Listing Projects.

Update labels for projects

Console

To update labels for a single project:

  1. Open the Labels page in the Google Cloud console.

    Open the Labels page

  2. Select your project from the Select a project drop-down.

  3. Update the labels for your project:

    1. To edit a label, click the value that you want to edit, then make your desired changes.
    2. To delete a label, hold the pointer over the key or value, then click .
  4. When you're finished updating labels, click Save.

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

  1. Open the Manage resources page in the Google Cloud console.

    Open the Manage resources page

  2. On the Manage resources page, select the projects for which you want to update labels.

  3. In the info panel, click the Labels tab and update labels for the selected projects:

    1. To edit a label, click the value that you want to edit, then make your desired changes.
    2. To delete a label, hold the pointer over the key or value, then click .
  4. When you're finished updating labels, click Save.

REST

To update a project's labels, do the following:

  • Get the project object using the projects.get() method.

  • Modify the labels that you want to update.

  • Call the projects.patch method.

The following example updates the label color:blue:

The following code snippet changes the value of the color label from blue to red.

Request:

PATCH https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_NAME
{
  updateMask=labels
}

Where PROJECT_NAME is the name of the project you want to update.

Request JSON body:

{
    "labels":
      {
        "color": "red"
      }
}

Response:

{
    "projects": [
    {
        "name": "projects/123456789012",
        "parent": "folders/123456789012",
        "projectId": "my-project",
        "state": "ACTIVE",
        "displayName": "PROJECT_NAME"
        "createTime": "2013-11-13T20:31:53.308Z"
        "updateTime": "2013-11-13T20:35:42.308Z"
        "etag": "BwWUlZ6XEfY="
        "labels": {
            "color": "red"
        },
    }
    ]
}