Creating and managing tags

This guide describes how to create and manage tags. A tag is a key-value pair that can be attached to a Google Cloud resource. You can use tags to conditionally allow or deny policies based on whether a supported resource has a specific tag.

Before you begin

For more information about what tags are and how they work, see the Tags overview.

Required permissions

The permissions you need depend on the action you need to perform.

To gain these permissions, ask your administrator to grant the suggested role at the appropriate level of the resource hierarchy.

View tags

To view tag definitions and tags that are attached to resources, you need the Tag Viewer role (roles/resourcemanager.tagViewer), or another role that includes the following permissions:

Required permissions

• resourcemanager.tagKeys.get
• resourcemanager.tagKeys.list
• resourcemanager.tagValues.list
• resourcemanager.tagValues.get
• listTagBindings for the appropriate resource type. For example, compute.instances.listTagBindings for viewing tags attached to Compute Engine instances.
• listEffectiveTags
for the appropriate resource type. For example, compute.instances.listEffectiveTags for viewing all tags attached to or inherited by Compute Engine instances.

To view tags at the organization level you need the Organization Viewer role (roles/resourcemanager.organizationViewer) on the organization resource.

Administer tags

To create, update, and delete tag definitions, you need the Tag Administrator role (roles/resourcemanager.tagAdmin), or another role that includes the following permissions:

Required permissions

• resourcemanager.tagKeys.create
• resourcemanager.tagKeys.update
• resourcemanager.tagKeys.delete
• resourcemanager.tagKeys.list
• resourcemanager.tagKeys.get
• resourcemanager.tagKeys.getIamPolicy
• resourcemanager.tagKeys.setIamPolicy
• resourcemanager.tagValues.create
• resourcemanager.tagValues.update
• resourcemanager.tagValues.delete
• resourcemanager.tagValues.list
• resourcemanager.tagValues.get
• resourcemanager.tagValues.getIamPolicy
• resourcemanager.tagValues.setIamPolicy

To administer tags at the organization level you need the Organization Viewer role (roles/resourcemanager.organizationViewer) on the organization resource.

Manage tags on resources

To add and remove tags that are attached to resources, you need the Tag User role (roles/resourcemanager.tagUser), or another role with equivalent permissions, on both the tag value and the resources that you are attaching the tag value to. The Tag User role includes the following permissions:

Required permissions

• Permissions required for the resource you're attaching the tag value
• Resource-specific createTagBinding permission, such as compute.instances.createTagBinding for Compute Engine instances.
• Resource-specific deleteTagBinding permission, such as compute.instances.deleteTagBinding for Compute Engine instances.
• Permissions required for the tag value:
• resourcemanager.tagValueBindings.create
• resourcemanager.tagValueBindings.delete
• Permissions that let you view projects and tag definitions:
• resourcemanager.tagValues.get
• resourcemanager.tagValues.list
• resourcemanager.tagKeys.get
• resourcemanager.tagKeys.list
• resourcemanager.projects.get

Creating and defining a new tag

Tags are comprised of a key-value pair, and are attached to a resource in your Google Cloud hierarchy. To create a new tag, you must first create a tag key that describes the tag you are creating. For example, you might want to specify production, test, and development environments for resources in your resource hierarchy by creating a key with the name environment.

Then, you can create the different values that the key can have. If you created a tag key named environment, you might want to specify that there are three potential environments, and create a value for each: production,development, and test.

You can create a maximum of 1000 keys created under a given organization or project and there can be a total of 1000 values created for each key.

Finally, you can then attach these values to resources in your hierarchy, which carries with it the key-value pair association. For example, you could attach test to multiple test environment folders across your organization, and each one would carry the environment: test key-value pair.

Creating a tag

To begin, you need to create a tag key.

The tag key's shortName can have a maximum length of 256 characters. The permitted character set for the shortName includes UTF-8 encoded Unicode characters except single quotes ('), double quotes ("), backslashes (\), and forward slashes (/).

After the shortName has been created, it cannot be changed, and it must be unique within the same namespace.

Console

To create a tag key, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project under which you want to create a tag key.

3. Click Create.

4. In the Tag key box, enter the display name of your tag key. This becomes part of the namespaced name of your tag.

5. In the Tag key description box, enter a description of your tag key.

6. If you want to add tag values to this key, click Add value for each tag value you want to create.

7. In the Tag value box, enter the display name of your tag value. This becomes part of the namespaced name of your tag.

8. In the Tag value description box, enter a description of your tag value.

9. When you have finished adding tag values, click Create tag key.

gcloud

To create a tag key, use the gcloud resource-manager tags keys create command:

gcloud resource-manager tags keys create SHORT_NAME \
    --parent=RESOURCE_ID

Where:

• SHORT_NAME is the display name for your tag key; for example: environment.

• RESOURCE_ID is the ID of the parent organization or project resource for this tag key; for example: organizations/123456789012, projects/test-project123, or projects/234567890123. To learn how to get your organization ID, see Creating and managing organizations. To learn how to get your project ID, see Creating and managing projects.

You should get a response similar to the following:

Creating tag key environment in organization 1234567890...
<blocking wait until creation completes>
name: tagKeys/123456789012
short_name: environment
namespaced_name: 123456789012/environment
parent: organizations/123456789012

Terraform

Use the google_tags_tag_key resource.

Before you create tag keys using Terraform, enable the Cloud Resource Manager API.

The following example creates tag keys named env and department:

data "google_project" "default" {}

resource "google_tags_tag_key" "env_tag_key" {
  parent     = "projects/${data.google_project.default.project_id}"
  short_name = "env"
}

resource "google_tags_tag_key" "department_tag_key" {
  parent     = "projects/${data.google_project.default.project_id}"
  short_name = "department"
}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

1. Launch Cloud Shell.

2. Set the default Google Cloud project where you want to apply your Terraform configurations.

   You only need to run this command once per project, and you can run it in any directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. If you are following a tutorial, you can copy the sample code in each section or step.

   Copy the sample code into the newly created main.tf.

   Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

3. Review and modify the sample parameters to apply to your environment.
4. Save your changes.
5. Initialize Terraform. You only need to do this once per directory.

   terraform init

   Optionally, to use the latest Google provider version, include the -upgrade option:

   terraform init -upgrade

Apply the changes

1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:

   terraform plan

   Make corrections to the configuration as necessary.

2. Apply the Terraform configuration by running the following command and entering yes at the prompt:

   terraform apply

   Wait until Terraform displays the "Apply complete!" message.

3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

API

To create a tag key, create a JSON representation of the key. For more information about the format of a tag key, see the TagKey reference.

Then, use the tagKeys.create method:

POST https://cloudresourcemanager.googleapis.com/v3/tagKeys/ -d

Request JSON body:

{
    "parent": RESOURCE_ID,
    "shortName": SHORT_NAME,
    "description": DESCRIPTION,
}

Where:

• SHORT_NAME is the display name for your tag key; for example: environment.

• RESOURCE_ID is the ID of the parent organization or project resource for this tag key; for example: organizations/123456789012, projects/test-project123, or projects/234567890123. To learn how to get your organization ID, see Creating and managing organizations. To learn how to get your project ID, see Creating and managing projects.

• DESCRIPTION is a description of the key, and no longer than 256 characters.

After you have created the key, you can find the unique human-readable display name called the namespacedName that is namespaced within its parent resource, and a globally unique permanent ID called the name.

Viewing a tag key

You can find information about a particular tag key using the permanent ID or namespaced name that is displayed when you created it.

Console

To view a created tag, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag.

3. All tags in the selected organization or project appear in the list. Click the tag for which you want to see the tag key.

gcloud

To display the information related to a given tag key, use the gcloud resource-manager tags keys describe command:

gcloud resource-manager tags keys describe TAGKEY_NAME

TAGKEY_NAME is the permanent ID or namespaced name of the tag key for which you want to display information; for example: tagKeys/123456789012 or project-id/environment.

You should get a response similar to the following:

name: tagKeys/123456789012
short_name: environment
namespaced_name: 123456789012/environment
parent: organizations/123456789012

API

To display the information related to a given tag key, use the tagKeys.get method:

GET https://cloudresourcemanager.googleapis.com/v3/{name=TAGKEY_NAME}

TAGKEY_NAME is the permanent ID of the tag key for which you want to display information; for example: tagKeys/123456789012.

To display the information related to a given tag key using its namespaced name, use the tagKeys.getNamespaced method:

GET https://cloudresourcemanager.googleapis.com/v3/tagKeys/namespaced?name={TAGKEY_NAMESPACED_NAME}

TAGKEY_NAMESPACED_NAME is the namespaced name of the tag key and is of the format parentNamespace/tagKeyShortName.

Adding tag values

Once you have created a tag key, you can then add accepted values for the key.

Your tag value's shortName must meet the following requirements:

• A shortName can have a maximum length of 256 characters.

• A shortName must begin with an alphanumeric character.

• A shortName can contain UTF-8 encoded Unicode characters except single quotes ('), double quotes ("), backslashes (\), and forward slashes (/).

• A shortName cannot be changed once it has been created, and must be unique within the same namespace.

Console

To create a tag value, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project under which you want to create a tag value.

3. In the list of tags, click the tag to which you want to add a new value.

4. Click Add value.

5. In the Tag value box, enter the display name of your tag value. This becomes part of the namespaced name of your tag.

6. In the Tag value description box, enter a description of your tag value.

7. Click Save.

gcloud

To create a tag value, use the gcloud resource-manager tags values create command. You must specify the key under which this value is created:

gcloud resource-manager tags values create TAGVALUE_SHORTNAME \
    --parent=TAGKEY_NAME

Where:

• TAGVALUE_SHORTNAME is the short name of the new tag value; for example: production.

• TAGKEY_NAME is the permanent ID or namespaced name of the parent tag key; for example: tagKeys/4567890123.

You should get a response similar to the following:

Creating tag value production in tag key 123456789012/environment...
<blocking wait until creation completes>
name: tagValues/7890123456
short_name: production
namespaced_name: 123456789012/environment/production
parent: tagKeys/123456789012

Terraform

Use the google_tags_tag_value resource.

Before you create tag values using Terraform, enable the Cloud Resource Manager API.

The following example creates tag values named prod and sales:

data "google_project" "default" {}

resource "google_tags_tag_key" "env_tag_key" {
  parent     = "projects/${data.google_project.default.project_id}"
  short_name = "env1"
}

resource "google_tags_tag_key" "department_tag_key" {
  parent     = "projects/${data.google_project.default.project_id}"
  short_name = "department1"
}

resource "google_tags_tag_value" "env_tag_value" {
  parent     = "tagKeys/${google_tags_tag_key.env_tag_key.name}"
  short_name = "prod"
}

resource "google_tags_tag_value" "department_tag_value" {
  parent     = "tagKeys/${google_tags_tag_key.department_tag_key.name}"
  short_name = "sales"
}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

1. Launch Cloud Shell.

2. Set the default Google Cloud project where you want to apply your Terraform configurations.

   You only need to run this command once per project, and you can run it in any directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. If you are following a tutorial, you can copy the sample code in each section or step.

   Copy the sample code into the newly created main.tf.

   Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

3. Review and modify the sample parameters to apply to your environment.
4. Save your changes.
5. Initialize Terraform. You only need to do this once per directory.

   terraform init

   Optionally, to use the latest Google provider version, include the -upgrade option:

   terraform init -upgrade

Apply the changes

1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:

   terraform plan

   Make corrections to the configuration as necessary.

2. Apply the Terraform configuration by running the following command and entering yes at the prompt:

   terraform apply

   Wait until Terraform displays the "Apply complete!" message.

3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

API

To create a tag value, create a JSON representation of the value. For more information about the format of a tag value, see the TagValue reference.

Then, use the tagValues.create method:

POST https://cloudresourcemanager.googleapis.com/v3/tagValues/ -d

Request JSON body:

{
    "parent": TAGKEY_NAME,
    "shortName": SHORT_NAME,
    "description": DESCRIPTION,
}

Where:

• TAGKEY_NAME is the permanent ID of the parent tag key; for example:tagKeys/4567890123.

• SHORT_NAME is the display name for your tag value; for example: environment.

• DESCRIPTION is a description of the value, and no longer than 256 characters. After you have created the value, you can find the unique human-readable display name called the namespacedName that is namespaced within its parent resource, and a globally unique permanent ID called the name.

Retrieving tag values

You can find information about a particular tag value using the permanent ID or namespaced name that is displayed when you created it.

Console

To view a created tag, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag.

3. All tags you have created under this organization or project appear in the list. Click the tag for which you want to see tag values.

gcloud

To display the information related to a given tag value, use the gcloud resource-manager tags values describe command:

gcloud resource-manager tags values describe TAGVALUE_NAME

TAGVALUE_NAME is the permanent ID or namespaced name of the tag value; for example: tagValues/4567890123 or 123456789012/environment/production.

You should get a response similar to the following:

name: tagValues/456789012345
short_name: production
namespaced_name: 123456789012/environment/production
parent: tagKeys/123456789012

API

To display the information related to a given tag value, use the tagValues.get method:

GET https://cloudresourcemanager.googleapis.com/v3/{name=TAGVALUE_NAME}

TAGVALUE_NAME is the permanent ID of the tag value; for example: tagValues/4567890123.

To display the information related to a given tag value using its namespaced name, use the tagValues.getNamespaced method:

GET https://cloudresourcemanager.googleapis.com/v3/tagValues/namespaced?name={TAGVALUE_NAMESPACED_NAME}

TAGVALUE_NAMESPACED_NAME is the namespaced name of the tag value and is of the format parentNamespace/tagKeyShortName/tagValueShortName.

When referencing tags using the Google Cloud CLI, you can use either the namespaced name or the permanent ID for tag keys and values. Calls to the API except getNamespaced should only use the permanent ID. See Tag definitions and identifiers for more information about the types of identifiers a tag uses.

Updating existing tags

You can modify an existing tag by updating the key or values associated with it. You can update a tag description, but not the short name.

Console

To update a tag key's description, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag key.

3. Click Actions next to the tag key you want to update, then click View details.

4. Click Edit next to Description near the top of the screen.

5. Update the description of the tag key.

6. Click Save.

gcloud

To modify a tag key description, use the gcloud resource-manager tags keys update command:

gcloud resource-manager tags keys update TAGKEY_NAME \
    --description=NEW_DESCRIPTION

Where:

• TAGKEY_NAME is the permanent ID or namespaced name of the key to be updated; for example: tagKeys/123456789012.

• NEW_DESCRIPTION is a string of no more than 256 characters to use as the new description.

You should get a response similar to the following:

name: tagKeys/123456789012
short_name: environment
namespaced_name: 123456789012/environment
description: "new description"
parent: organizations/123456789012

API

To modify a tag key description, use the tagKeys.patch method:

PATCH https://cloudresourcemanager.googleapis.com/v3/{tagKey.name=TAGKEY_NAME} -d

Request JSON body:

{
    "description": DESCRIPTION,
}

Where:

• TAGKEY_NAME is the permanent ID of the tag key; for example: tagKeys/123456789012.

• DESCRIPTION is a description of the key, and no longer than 256 characters.

You can also change the description of tag values.

Console

To update a tag value's description, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag value.

3. Click Actions next to the tag key for the value you want to update, then click View details.

4. Click Actions next to the tag value you want to update, then click View details.

5. Click Edit next to Description near the top of the screen.

6. Update the description of the tag value.

7. Click Save.

gcloud

To modify a tag value description, use the gcloud resource-manager tags values update command:

gcloud resource-manager tags values update TAGVALUE_NAME \
    --description="NEW_DESCRIPTION"

Where:

• TAGVALUE_NAME is the permanent ID or namespaced name of the tag value to be updated; for example: tagValues/4567890123.

• NEW_DESCRIPTION is a string of no more than 256 characters to use as the new description.

You should get a response similar to the following:

short_name: production
namespaced_name: 123456789012/environment/production
parent: tagKeys/123456789012
description: "new description"

API

To modify a tag key description, use the tagValues.patch command:

PATCH https://cloudresourcemanager.googleapis.com/v3/{tagKey.name=TAGVALUE_NAME} -d

Request JSON body:

{
    "description": DESCRIPTION,
}

Where:

• TAGVALUE_NAME is the permanent ID name of the tag value; for example: tagValues/4567890123.

• DESCRIPTION is a description of the key, and no longer than 256 characters.

Listing tag keys

You can list all tag keys associated with a particular organization or project resource using the Google Cloud console, the gcloud CLI, or with a call to the API.

Console

To view all tags:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tags.

3. All tags you have created under this organization or project appear in the list.

gcloud

To return a list of all tag keys created under a organization or a project resource, use the gcloud resource-manager tags keys list command:

gcloud resource-manager tags keys list --parent=RESOURCE_ID

RESOURCE_ID is the ID of the organization or project resource for which you want to find attached tag keys.

• An organization or project ID should be provided in the format organizations/ORGANIZATION_ID or projects/PROJECT_NAME; for example: organizations/123456789012 and projects/test-project123. To learn how to get your organization ID, see Creating and managing organizations. To learn how to get your project ID, see Creating and managing projects. You should get a response similar to the following:

NAME                     SHORT_NAME      DESCRIPTION
tagKeys/123456789012     environment     description of tag key

API

To return a list of all tag keys for a given resource, use the tagKeys.list method, with the parent resource specified in the query:

GET https://cloudresourcemanager.googleapis.com/v3/tagKeys

{
    "parent": "RESOURCE_ID"
}

RESOURCE_ID is the ID of the organization or project resource for which you want to find attached tag keys; for example: organizations/123456789012 and projects/test-project123.

List tag values

You can list all tag values associated with a particular tag key using the Google Cloud console, the gcloud CLI, or with a call to the API.

Console

To view all tag values attached to a tag key, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag key.

3. Click Actions next to the tag key containing the tag values you want to find, then click View details.

4. All tag values you have created under this tag key appear in the list.

gcloud

To return a list of all tag values attached to a key, use the gcloud resource-manager tags values list command:

gcloud resource-manager tags values list --parent=TAGKEY_NAME

TAGKEY_NAME is the permanent ID or namespaced name of the tag key for which you want to find attached values; for example: tagKeys/123456789012 or 1234567/environment.

You should get a response similar to the following:

NAME                     SHORT_NAME
tagValues/123456789012   production

API

To return a list of all tag values attached to a key, use the tagValues.list method, with the parent tag key specified in the query:

GET https://cloudresourcemanager.googleapis.com/v3/tagValues

{
    "parent": "TAGKEY_NAME"
}

TAGKEY_NAME is the permanent ID name of the tag key; for example: tagKeys/123456789012.

Managing access to tags

You can give users specific access to manage tags and attach tag values to resources using the Google Cloud console. See Required permissions for a list of the roles related to tags, and the permissions they contain.

Tag keys

To manage access for users on a tag key, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains the tag key on which you want to manage access.

3. Click the checkbox next to the tag for which you want to manage access.

4. Click Manage access.

5. To add a role to a principal, click Add principal.

   1. In the New principals text box, enter the email address of the principal you want to grant a new role.

   2. Select a role from the Select a role dropdown menu. If you want to add more than one role, click Add another role.

   3. Click Save.

6. To edit a principal's role, click Edit next to the principal you want to edit.

   1. You can change any roles that are assigned to the principals on this tag by clicking on the Role dropdown menu and choosing a new role.

   2. If you want to add more roles, click Add another role.

   3. To delete a role from this principal on this tag, click Delete role next to the role you want to delete.

   4. Click Save.

7. To delete a principal's role, click Delete role next to the role you want to delete.

   1. Click Remove.

Tag values

To manage access for users on a tag value, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains the tag key for which you want to manage access.

3. Click Actions next to the tag key for the value for which you want to manage access, then click View details.

4. Click Manage access.

5. To add a role to a principal, click Add principal.

   1. In the New principals text box, enter the email address of the principal you want to grant a new role.

   2. Select a role from the Select a role dropdown menu. If you want to add more than one role, click Add another role.

   3. Click Save.

6. To edit a principal's role, click Edit next to the principal you want to edit.

   1. You can change any roles that are assigned to the principals on this tag by clicking on the Role dropdown menu and choosing a new role.

   2. If you want to add more roles, click Add another role.

   3. To delete a role from this principal on this tag, click Delete role next to the role you want to delete.

   4. Click Save.

7. To delete a principal's role, click Delete role next to the role you want to delete.

   1. Click Remove.

Attaching tags to resources

After a tag is created and appropriate access is granted to both the tag and the resource, the tag can be attached to a Google Cloud resource as a key-value pair. Exactly one value can be attached to a resource for a given key. For example, if environment: development is attached, then environment: production or environment: test cannot be attached. Each resource can have a maximum of 50 key-value pairs attached.

Tags are attached to resources by creating a tag binding resource that links the value to the Google Cloud resource. The following workflow describes how to attach a tag to an organization, folder, or project resource. For details about how to attach tags to another type of resource, see the documentation for that resource in Services that support tags.

Console

To attach a tag to an organization, folder, or project resource, do the following:

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

   Open Manage resources page

2. Click the organization, folder, or project to which you want to attach a tag.

3. Click Tags.

4. In the Tags panel, click Select scope.

5. Select the organization or project that contains your tags, and then click Open.

6. In the Tags panel, select Add tag.

7. In the Key field, select the key for the tag you want to attach from the list. You can filter the list by typing keywords.

8. In the Value field, select the value for the tag you want to attach from the list. You can filter the list by typing keywords.

9. If you want to attach more tags, click Add Tag, and then select the key and value for each.

10. Click Save.

11. In the Confirm dialog, click Confirm to attach the tag.

12. A notification confirms that your tags are updated. The new tags appear under the Tags column on the Manage resources page.

gcloud

To attach a tag to a resource, you must create a tag binding resource by using the gcloud resource-manager tags bindings create command:

gcloud resource-manager tags bindings create \
--tag-value=TAGVALUE_NAME \
--parent=RESOURCE_ID \
--location=LOCATION

Where:

• TAGVALUE_NAME is the permanent ID or namespaced name of the tag value to be attached; for example: tagValues/4567890123 or 12345678/environment/production.

• RESOURCE_ID is the full ID of the resource, including the API domain name to identify the type of resource (//cloudresourcemanager.googleapis.com/). For example, to attach a tag to projects/7890123456, the full ID would be: //cloudresourcemanager.googleapis.com/projects/7890123456.

• LOCATION is the location of your resource. If you are attaching a tag to a global resource, such as a folder or a project, you should omit this flag. If you are attaching a tag to a regional resource, such as a Compute Engine instance, you must specify the location; for example: us-central1.

API

To attach a tag to a resource, you must first create a JSON representation of a tag binding that includes the permanent ID or namespaced name of the tag value and the permanent ID of the resource. For more information about the format of a tag binding, see the TagBinding reference.

If you are attaching the tag to a global resource such as an organization, use the tagBindings.create method with the global endpoint hostname:

POST https://cloudresourcemanager.googleapis.com/v3/tagBindings

If you are attaching the tag to a regional resource, such as a Compute Engine instance, use the tagBindings.create method with the regional endpoint where your resource is located.

POST https://LOCATION-cloudresourcemanager.googleapis.com/v3/tagBindings

Request JSON body:

{
    "parent": RESOURCE_ID,
    "tagValue": TAGVALUE_NAME,
}

OR

{
    "parent": RESOURCE_ID,
    "tagValueNamespacedName": TAGVALUE_NAMESPACED_NAME,
}

Where:

• RESOURCE_ID is the full ID of the resource, including the API domain name to identify the type of resource (//cloudresourcemanager.googleapis.com/). For example, to attach a tag to projects/7890123456, the full ID would be: //cloudresourcemanager.googleapis.com/projects/7890123456.

• TAGVALUE_NAME is the permanent ID of the tag value that is attached; for example: tagValues/4567890123.

• TAGVALUE_NAMESPACED_NAME is the namespaced name of the tag value that is attached and is of the format: parentNamespace/tagKeyShortName/tagValueShortName.

Listing all tags attached to a resource

You can get a list of all tags attached to a resource, for tags that are either inherited or directly attached.

Console

To see all tags that are attached to or inherited by a resource, do the following:

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

   Open Manage resources page

2. Find your organization, folder, or project in the list of resources.

3. The tags attached to the resource appear under the Tags column. Tags that are inherited will be marked as Inherited.

gcloud

To get a list of tag bindings directly attached to a resource, use the gcloud resource-manager tags bindings list command. If you add the --effective flag, you will also return a list of tags inherited by this resource.

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

Where:

• RESOURCE_ID is the full ID of the resource; for example: //cloudresourcemanager.googleapis.com/projects/7890123456

• LOCATION is the location of your resource. If you are listing the tags attached to a global resource, such as a folder or a project, you should omit this flag. If you are attaching a tag to a regional resource, such as a Compute Engine instance, you must specify the location; for example: us-central1.

You should get a response similar to the following:

name: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F7890123456/tagValues/567890123456
tagValue: tagValues/567890123456
resource: //cloudresourcemanager.googleapis.com/projects/7890123456

If you add the --effective flag to the tags bindings list command, you will also return a list of all tags inherited by this resource. You should get a respond similar to the following:

namespacedTagKey: 961309089256/environment
namespacedTagValue: 961309089256/environment/production
tagKey: tagKeys/417628178507
tagValue: tagValues/247197504380
inherited: true

If all tags evaluated on a resource are directly attached, the inherited field is false and is omitted.

API

To get a list of tag bindings directly attached to a global resource such as an organization, use the tagBindings.list method, specifying the parent resource in the query:

GET https://cloudresourcemanager.googleapis.com/v3/tagBindings

{
    "parent": "RESOURCE_ID"
}

If you want to list the tag bindings attached to a regional resource, such as Compute Engine instances, use the tagBindings.list method with the regional endpoint where your resource is located.

GET https://LOCATION-cloudresourcemanager.googleapis.com/v3/tagBindings

{
    "parent": "RESOURCE_ID"
}

Where:

• RESOURCE_ID is the full ID of the resource; for example: //cloudresourcemanager.googleapis.com/projects/7890123456.

• LOCATION is the regional endpoint for your resource; for example: us-central1.

If successful, the response body should include a list of TagBinding objects. For example:

name: tagBindings/cloudresourcemanager.googleapis.com/projects/7890123456/567890123456
tagValue: tagValues/567890123456
resource: //cloudresourcemanager.googleapis.com/projects/7890123456

Detaching a tag from a resource

You can detach a tag from a resource by deleting the tag binding resource.

Console

To detach a tag from an organization, folder, or project resource, do the following:

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

   Open Manage resources page

2. Click the organization, folder, or project from which you want to detach a tag.

3. Click Tags.

4. In the Tags panel, next to the tag you want to detach, click Delete item.

5. Click Save.

6. In the Confirm dialog, click Confirm to detach the tag.

7. A notification confirms that your tags are updated. The updated list of tags appears under the Tags column on the Manage resources page.

gcloud

To delete a tag binding, use the gcloud resource-manager tags bindings delete command:

gcloud resource-manager tags bindings delete \
--tag-value=TAGVALUE_NAME \
--parent=RESOURCE_ID \
--location=LOCATION

Where:

• TAGVALUE_NAME is the permanent ID or namespaced name of the tag value that is attached; for example: tagValues/567890123456.

• RESOURCE_ID is the full ID of the resource. For example: //cloudresourcemanager.googleapis.com/projects/7890123456

• LOCATION is the location of your resource. If you are deleting a tag binding that is attached to a global resource, such as a folder or a project, you should omit this flag. If you are deleting a tag binding attached to a regional resource, such as a Compute Engine instance, you must specify the location; for example: us-central1.

API

To delete a tag binding that is attached to a global resource such as an organization, use the tagBindings.delete method:

DELETE https://cloudresourcemanager.googleapis.com/v3/{name=TAGBINDINGS_NAME}

If you want to delete a tag binding that is attached to a regional resource, such as a Compute Engine instance, use the tagBindings.delete method with the regional endpoint where your resource is located.

DELETE https://LOCATION-cloudresourcemanager.googleapis.com/v3/{name=TAGBINDINGS_NAME}

Where:

• TAGBINDINGS_NAME is the permanent ID of the TagBinding; for example: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F1234567890/tagValues/567890123456.

• LOCATION is the regional endpoint for your resource; for example: us-central1.

Protecting tag values with tag holds

A tag hold is a resource that you can create to protect a tag value from being deleted. If a tag value has a tag hold, it cannot be deleted by users unless the tag hold is first deleted.

Creating tag holds

You can manually create a tag hold using the gcloud CLI or the API.

gcloud

To create a tag hold, use the gcloud resource-manager tags holds create gcloud CLI command:

  gcloud resource-manager tags holds create TAGVALUE_NAME \
  --holder=HOLDER_NAME \
  --location=LOCATION

Where:

• TAGVALUE_NAME is the permanent ID or namespaced name of the tag value for which this tag hold should be created; for example: tagValues/567890123456.

• HOLDER_NAME is the name of the resource where the tag value is attached. Must be less than 200 characters.

• LOCATION is the location of your resource. If you are creating a tag hold for a global resource, such as a Google Cloud project, you should omit this flag. If you are creating a tag hold for a regional or zonal resource you must specify the location; for example: us-central1.

API

To create a tag hold for a tag value, you must first create a JSON representation of a tag hold. This JSON reference must include a reference to the resource to which the tag value is attached. For more information about the format of a tag hold, see the TagHolds reference.

If you are creating a tag hold for a tag value attached to a global resource such as an organization, use the tagHolds.create method with the global endpoint hostname:

POST https://cloudresourcemanager.googleapis.com/v3/tagValues/TAGVALUE_NAME/tagHolds

If you are creating a tag hold for a tag value attached to a regional resource, such as a Compute Engine instance, use the tagHolds.create method with the regional endpoint where your resource is located.

POST https://LOCATION-cloudresourcemanager.googleapis.com/v3/TAGVALUE_NAME/tagHolds

Request JSON body:

{
    "holder":HOLDER_NAME,
    "origin":ORIGIN_NAME
}

Where:

• TAGVALUE_NAME is the permanent ID of the tag value that is attached; for example: tagValues/4567890123.

• HOLDER_NAME is the name of the resource where the tag value is attached. Must be less than 200 characters.

• ORIGIN_NAME is an optional string representing the origin of this request. This field should include human-understandable information to distinguish origins from each other. Must be less than 200 characters.

Listing tag holds

You can list all tag holds under a particular tag value using the gcloud CLI or the API.

gcloud

To list tag holds that are under a tag value, use the gcloud resource-manager tags holds list gcloud CLI command:

  gcloud resource-manager tags holds list TAGVALUE_NAME \
  --location=LOCATION

Where:

• TAGVALUE_NAME is the permanent ID or namespaced name of the tag value; for example: tagValues/567890123456.

• LOCATION is the location of your resource. If you are looking for tag holds created globally, you should omit this flag. If you are looking for tag holds under a regional or zonal resource, you must specify the location; for example: us-central1.

API

To get a list of tag holds under a tag value, use the tagHolds GET method, specifying the parent tag value in the URL:

GET https://cloudresourcemanager.googleapis.com/v3/{TAGVALUE_NAME}/tagHolds

Where:

• TAGVALUE_NAME is the permanent ID or namespaced name of the tag value; for example: tagValues/567890123456.

Removing tag holds

You can remove tag holds created on a particular tag value using the gcloud CLI or the API.

Some resources add tag holds to a tag value that is attached to that resource. If you attach a tag to such a resource, the resource creates a tag hold that will prevent users from deleting the attached tag value.

You can delete a tag hold using the gcloud CLI or the API.

gcloud

To delete a tag hold, use the gcloud resource-manager tags holds delete gcloud CLI command:

  gcloud resource-manager tags holds delete TAGHOLD_NAME \
  --location=LOCATION

Where:

• TAGHOLD_NAME is the namespaced name of the tag hold, which can be found by using the list command. For example: tagValues/1012910994523/tagHolds/d1c8f5e2-2954-43d6-8f46-5f812ab48c37.

• LOCATION is the location of your resource. If you are deleting a tag hold that is under a tag value attached to a global resource, such as a folder or a project, you should omit this flag. If you are deleting a tag hold created from a regional or zonal process, you must specify the location; for example: us-central1.

API

To delete a tag value, use the tagHolds.delete method:

DELETE https://cloudresourcemanager.googleapis.com/v3/{TAGVALUE_NAME}/tagHolds/{TAGHOLD_NAME}

Where:

• TAGVALUE_NAME is the permanent ID of the tag value to which the tag hold you want to delete is attached; for example: tagValues/567890123456.

• TAGHOLD_NAME is the namespaced name of the tag hold you want to delete, which can be found by using the list command. For example: tagValues/1012910994523/tagHolds/d1c8f5e2-2954-43d6-8f46-5f812ab48c37.

Deleting tags

To delete a tag, you must delete each of its defining components. First, you must delete any tag bindings that attach this tag to resources in your hierarchy. For instructions on deleting tag bindings, see Detaching a tag from a resource.

If the tag is used by another resource, or a user has manually created a tag hold, you might need to remove tag holds as well as delete tag bindings before you can delete the tag values. For information about removing tag holds, see Removing tag holds.

Once there are no more tag bindings for the tag values you want to delete, you can delete the values.

Console

To delete a tag value, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag value.

3. Click Actions next to the tag key containing the tag value you want to delete, then click View details.

4. In the list of tag values associated with this tag key, click the tag value you want to delete.

5. Click the checkbox next to the tag value you want to delete, then click Delete values.

6. Click Confirm.

gcloud

To delete a tag value, use the gcloud resource-manager tag values delete command:

gcloud resource-manager tags values delete TAGVALUE_NAME

TAGVALUE_NAME is the permanent ID or namespaced name of the tag value you want to delete; for example: tagValues/567890123456.

API

To delete a tag value, use the tagValues.delete method:

DELETE https://cloudresourcemanager.googleapis.com/v3/{name=TAGVALUE_NAME}

TAGVALUE_NAME is the permanent ID of the tag value you want to delete; for example: tagValues/567890123456.

Once all tag values associated with a key have been deleted, you can then delete the key.

Console

To delete a tag key, do the following:

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

   Open Tags page

2. From the Scope picker at the top of the page, select the organization or project that contains your tag key.

3. Click the checkbox next to the tag key you want to delete.

4. Click Delete tags.

5. Click Confirm.

gcloud

To delete a tag key, use the gcloud resource-manager tags keys delete command:

gcloud resource-manager tags keys delete TAGKEYS_NAME

TAGKEYS_NAME is the permanent ID or namespaced name of the tag key you want to delete; for example: tagKeys/123456789012.

API

To delete a tag key, use the tagKeys.delete method:

DELETE https://cloudresourcemanager.googleapis.com/v3/{name=TAGKEYS_NAME}

TAGKEYS_NAME is the permanent ID of the tag key you want to delete; for example: tagKeys/123456789012.

Policies and tags

You can use tags with policies that support them to conditionally enforce those policies. You can make the presence or absence of a tag value the condition for that policy.

For example, you can conditionally grant Identity and Access Management (IAM) roles based on whether a resource has a specific tag.

Note: In general, any tag changes take effect within 2 minutes. However, changes can potentially take 7 minutes or longer to fully propagate across the system.

Identity and Access Management conditions and tags

You can use tags and Identity and Access Management conditions to conditionally grant roles to users in your hierarchy. This process makes resources inaccessible to users until a tag which is associated with a conditional policy is attached. For example, you may want to require that your developers assign a cost center to a resource before they can use it.

1. Create a tag that you can use to associate resources with something that will identify whether the resources have had proper governance applied. For example, you could create a tag with the key costCenter and values 0001, 0002, and so forth, to associate the resources with the various cost centers at your company.

2. Create an organization-level custom role that allows users to add tags to the resources you require tags on. This gives these permissions to the specified principals anywhere in your organization.

   For example, a custom role that allows users to add tags to projects would include the following permissions:

   • resourcemanager.projects.get
   • resourcemanager.hierarchyNodes.create
   • resourcemanager.hierarchyNodes.delete
   • resourcemanager.hierarchyNodes.list

3. When creating projects for your developers, assign them this custom role on the project.

4. Assign any other roles to your developers that include the permissions for them to perform any desired actions inside of that project. When you grant roles to users on the project, the roles should always be conditionally granted to require the attachment of the costCenter tag.

   resource.hasTagKey('123456789012/costCenter')
   

   Important: Ensure that any roles you grant to your developers do not include any setIamPolicy permissions, as these allow your developers to modify the project's IAM policy, where they could remove any conditional restrictions you may have put into place.

Now, any time a project is created, your developers must attach the costCenter tag to it before they're able to perform the actions in it that are granted by the IAM policy.

Organization policies and tags

You can use tags and conditional enforcement of organization policies to provide centralized control of the resources in your hierarchy. For more information, see Setting an organization policy with tags.

Supported services

For a list of services that support tags, see Services that support tags.

Troubleshooting known issues

Condition expression fails

If you run one of the add-iam-policy-binding commands using Google Cloud CLI, and the IAM policy on that resource contains conditional role bindings for that role, the gcloud CLI tool prompts you to choose one of the condition expressions that exists in the policy. If you choose a condition expression that contains a comma, the command fails. To work around this issue, use the --condition flag to specify a condition expression on the command line.