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 an organization, folder, or project. You can use tags to conditionally allow or deny policies based on whether a resource has a specific tag.

Before you begin

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

Note: You must have an organization resource to use tags. For more information about acquiring an organization resource, see Creating and managing organizations.

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.

Note: The following permissions will not appear in the Google Cloud console until they have been set for the first time using the Google Cloud CLI.

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:

• 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

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:

• 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

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:

• Permissions required for the resource you're attaching the tag value to:

  • 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

Note: Granting the role at organization level automatically ensures that you have the required permissions on both the tag value and the resources you're attaching the tag value to. If your administrator does not grant the role at the organization level, ensure that they grant you the role for both the tag value and the resources that you are attaching the tag values to.

Creating and defining a new tag

Tags are comprised of a key-value pair, and are attached to an organization, folder, or project 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 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 63 characters. The permitted character set for the shortName includes upper-and lower-case alphanumerics (no internationalization), hyphens, underscores and periods. The shortName must begin and end with an alphanumeric character. Once the shortName has been created, it cannot be changed, and 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

4. Click Create tag.

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

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

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

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

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

10. When you have finished adding tag values, click Create tag.

gcloud

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

gcloud resource-manager tags keys create SHORT_NAME \
    --parent=organizations/ORGANIZATION_ID

Where:

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

• ORGANIZATION_ID is the ID of the organization to be the parent resource to this tag key; for example: 12345678901. To learn how to get your organization ID, see Creating and managing organizations.

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: 12345678901/environment
parent: organizations/12345678901

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": ORGANIZATION_ID,
    "shortName": SHORT_NAME,
    "description": DESCRIPTION,
}

Where:

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

• ORGANIZATION_ID is the ID of the organization to be the parent resource to this tag key; for example: organizations/12345678901. To learn how to get your organization ID, see Creating and managing organizations.

• 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 organization, 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

4. All tags in this organization appear in the list. Click on 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

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

You should get a response similar to the following:

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

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}

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

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 63 characters.

• A shortName must begin and end with an alphanumeric character.

• A shortName must contain only upper- and lower-case alphanumeric characters (no internationalization), hyphens (-), underscores (_), periods (.), at signs (@), percent signs (%), equals signs (=), plusses (+), colons (:), commas (,), asterisks (*), pound signs (#), ampersands (&), parentheses (( or )) , square braces ([ or ]), curly braces ({ or }), and spaces.

• 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

5. Click Add value.

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

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

8. Click Save.

gcloud

To create a tag value, use the gcloud resource-manager tags keys 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 12345678901/environment...
<blocking wait until creation completes>
name: tagValues/7890123456
short_name: production
namespaced_name: 12345678901/environment/production
parent: tagKeys/123456789012

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 organization, 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

4. All tags you have created in this organization appear in the list. Click on 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

Where TAGVALUE_NAME is the namespaced name of the tag value; for example: 1234567890/environment/production.

You should get a response similar to the following:

short_name: production
namespaced_name: 1234567890/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}

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

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 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

4. Click Actions next to the tag key 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 key.

7. 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: 12345678901/environment
description: "new description"
parent: organizations/12345678901

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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

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

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

7. Update the description of the tag value.

8. 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: 12345678901/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 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

4. All tags you have created in this organization appear in the list.

gcloud

To return a list of all tag keys attached to an organization resource, use the gcloud resource-manager tags keys list command:

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

Where ORGANIZATION_ID is the ID of the organization for which you want to find attached tag keys.

• An organization ID should be provided in the format organizations/ORGANIZATION_ID; for example: organizations/12345678901. To learn how to get your organization ID, see Creating and managing organizations.

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"
}

Where RESOURCE_ID is the ID of the resource for which you want to find attached tag keys; for example: organizations/12345678901.

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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

5. 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

Where 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.

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"
}

Where 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

5. Click Manage access.

6. 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. If you want to send a notification, click the checkbox next to Send notification email.

   4. Click Save.

7. 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.

8. 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

5. Click Manage access.

6. 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. If you want to send a notification, click the checkbox next to Send notification email.

   4. Click Save.

7. 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.

8. 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.

Console

To attach a tag to a resource, do the following:

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

   Open Manage resources page

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

3. In the info panel that appears, click the Tags tab.

4. Click the Attach tags radio button.

5. In the Tag value box, enter the namespaced name of the tag value you want to attach; for example, 456789012345/Environment/Production from the organization ID 456789012345, tag key name Environment, and tag value Production.

6. If you want to attach more tag values, click Add Tag Value, and enter the namespaced name for each tag value.

7. Click Save.

8. The new tag appears 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.

• 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 IDs of the tag value and 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,
}

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.

Listing all tags attached to a resource

You can get a list of all tags attached to a resource. The following examples provide a list of tag bindings attached directly to the resource, but won't return any tags that have been inherited from parent resources.

Console

To see all tags that are attached to 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.

gcloud

To get a list of tag bindings attached to a resource, use the gcloud resource-manager tags bindings list command:

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

API

To get a list of tag bindings 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

Listing effective tags on a resource

Preview

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

If you want to see tag bindings directly attached to the resource as well as any inherited tag bindings, you can use gcloud CLI or the API.

gcloud

To get a list of tag bindings attached to or inherited by a resource, use the gcloud alpha resource-manager tags bindings list command with the --effective flag:

gcloud alpha resource-manager tags bindings list --effective \
    --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:

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 attached to or inherited by a global resource such as an organization, use the effectivetags.list method, specifying the parent resource in the query:

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

{
    "parent": "RESOURCE_ID"
}

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

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

{
    "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:

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.

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 a resource, do the following:

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

   Open Manage resources page

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

3. In the info panel that appears, click the Tags tab.

4. Click the Remove tags radio button.

5. Click the checkbox next to the tag path you want to remove.

6. Click Save.

7. You can find the updated list of attached tags 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 alpha resource-manager tags holds create gcloud CLI command:

  gcloud alpha 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 alpha resource-manager tags holds list gcloud CLI command:

  gcloud alpha 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 alpha resource-manager tags holds delete gcloud CLI command:

  gcloud alpha 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

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

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

7. 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

Where 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}

Where 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. Select the Project picker at the top of the page.

3. From the Organization picker, select your organization.

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

5. Click Delete tags.

6. 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

Where 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}

Where 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 60 seconds. However, under certain circumstances, it may take up to 7 minutes for such changes 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('12345678901/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.

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.