Tags overview

The Google Cloud resource hierarchy is a way to organize your resources into a tree structure. While the hierarchy is useful to manage resources at scale, it is limited to modeling only a few business dimensions, such as organization structure, regions, workload types, cost centers, and so forth. The hierarchy lacks flexibility to layer multiple business dimensions together.

Tags provides a way to conditionally allow or deny policies based on whether a resource has a specific tag. You can use tags and conditional enforcement of policies for fine-grained control across your resource hierarchy.

Labels are a separate tool that allow you to create annotations for resources. For more information, see Creating and managing labels.

Creating tags

Tags are structured as a key/value pair. A tag key resource can be created under your organization resource, and tag values are resources that are attached to a key. For example, a tag key 'environment' with values 'production' and 'development'.

Tag administration

Administrators can control the usage of tags by restricting who has the ability to create, update, delete, and attach tags to resources. They can select an individual tag to make edits, such as to add or remove values, and update the description. This allows for fine-grained control of tags across your organization.

Tags may be supplied a description, which will be displayed when information about the tag is retrieved. This is so that whoever is attaching the tag to the resource will understand the purpose of that tag.

A tag can only ever have one value for a given key on a particular resource. For example, a project with the tag key environment and value production could not also have the development value for the environment key.

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.

Once you have created a tag, you can apply it to resources. You can then create policies that are conditional based on whether a tag is attached to a resource. The policy will take effect based on the presence or absence of the tags attached to resources.

To see how to use tags with Identity and Access Management (IAM) to help control access to your Google Cloud resources, see Tags and access control.

Tag inheritance

When a tag key-value pair is attached to a resource, it will be inherited by all of the resource's descendants. To prevent a lower-level resource from inheriting a tag, you can apply a tag to the lower-level resource that uses a different value for the same key as the inherited tag.

For example, suppose that you apply the tag environment: dev to a folder, and the folder has two child folders named team-a and team-b. You can also apply a different tag, environment: test, to the team-b folder. As a result, projects and other resources in the team-a folder inherit the tag environment: dev, and projects and other resources in the team-b folder inherit the tag environment: test:

If you remove the environment: test tag from the team-b folder, then that folder and its resources will inherit the tag environment: dev.

When using tags to manage policies, we recommend you create a safe default tag. This means setting a tag at the level of your organization resource that will then be inherited throughout your resource hierarchy. For example, a tag key with the short name enforcement, and values default, on, or off. If you set enforcement: default at the level of your organization, that tag would be inherited by all resources, unless overridden at lower levels.

You could then write policies that address the enforcement tag key, with conditions that would affect a resource if it is enforcement: on or enforcement: off, and a safe case if it is enforcement: default. If the enforcement tag was ever removed from a resource, it would then inherit the tag value for enforcement from its parent resource. If no parent resource has the enforcement tag, it would inherit enforcement: default from the organization resource.

Using a safe default tag can help, but to prevent unintended behaviors you should review the tags and conditional policies in place before moving your resources or removing tags.

Deleting tag keys and values

When removing a tag key or value definition, if that tag is attached to a resource, then the removal will fail. You must delete existing tag attachments, called tag bindings, before deleting the tag definition itself.

What's next

For more information about how to use tags, read the Creating and managing tags page.