Tags overview

The Google Cloud resource hierarchy is a way to organize your resources into a tree structure. This hierarchy helps you manage resources at scale, but it models only a few business dimensions, including organization structure, regions, workload types, and cost centers. The hierarchy lacks the flexibility to layer multiple business dimensions together.

Tags provide a way to create annotations for resources, and in some cases 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.

Tags and labels

Labels are a separate way to create annotations for resources. The following table lists some of the differences between tags and labels:

Tags Labels
Resource structure Tag keys, tag values, and tag bindings are all discrete resources Not a resource in itself, but metadata for resources
Definition Defined at the organization or project level Defined by each resource
Access control Management and attachment of tags requires Identity and Access Management (IAM) roles Attachment of labels requires IAM roles, which will vary based on the service resource
Prerequisite for attachment The tag key and tag value must be defined before a tag can be attached to a resource No prerequisites for attachment
Inheritance Tag bindings are inherited by children of the resource in the Google Cloud hierarchy Not inherited by children of the resource
Deletion requirements Tags can't be deleted unless no tag bindings for that tag exist Can be removed from a resource at any time
Naming requirements Requirements for Tag values and Tag keys Requirements for labels
Key/value name length 256 characters maximum 63 characters maximum
IAM policy support Tags can be referenced by IAM policy conditions No IAM policy support
Organization policy support Tags on some resources can be referenced by Organization Policy conditional constraints No Organization Policy support
Cloud Billing integration Perform chargebacks, audits, and other cost allocation analysis, export Cloud Billing cost data to BigQuery Filter resources by label in Cloud Billing, export Cloud Billing data to BigQuery

For more information about labels, 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 or project resources, 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 can 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 your tags.

Tags may be supplied a description, which will be displayed when information about the tag is retrieved. This description ensures that whoever is attaching the tag to the resource understands 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 and conditionally deny IAM permissions based on whether a resource has a specific tag.

After you create 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 supported 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, all descendants of the resource inherit the tag. You can override an inherited tag on a descendant resource. To override an inherited tag, apply a tag using the same key as the inherited tag, but use a different value.

For example, suppose that you apply the tag environment: development 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: development, 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: development.

All of the tags that are both attached to and inherited by a resource are collectively called the effective tags. The effective tags for a resource are a combination of the tags directly attached to it, as well as all tags attached to all of the resource's ancestors throughout the hierarchy.

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.

Protecting tag values from deletion

You can create an additional layer of protection for your tag values by attaching a tag hold to a tag value. A tag hold, like a tag binding, prevents a user from deleting the tag value.

Some resources automatically create a tag hold on each tag value attached to the resource. This tag hold must be removed before a user can delete the tag value.

What's next