Tags and access control

This page provides an overview of tags. It also describes how to use tags with Identity and Access Management (IAM) to help you control access to your Google Cloud resources.

Overview of tags

A tag is a key-value pair that is attached to an organization, folder, or project. You can conditionally grant IAM roles based on whether a resource has a specific tag.

Other resources inherit tag values from their parent organization, folders, and project. As a result, you can use tags to manage access to any Google Cloud resource.

Common uses for tags

These are some common use cases for managing access with tags:

  • Development, staging, and production environments. For example, you could add the tags environment: dev to your development environment and environment: prod to your production environment.
  • Component types. For example, you could add the tags component: frontend to front-end resources and component: batch to resources for batch processing.
  • Project names. For example, if your team is working on a project with the codename Atlas, you could add the tag project: atlas to the team's development resources.

Tags and the resource hierarchy

In Google Cloud, resources are part of a hierarchy, and lower-level resources can inherit properties from higher-level resources. Tags are one of the properties that resources can inherit. For example, if you attach a tag to an organization, then the folders, projects, and service-specific resources in that organization inherit that tag.

To prevent resources from inheriting a tag value, attach another tag to a folder or project, using the same key but a different value than the tag on the higher-level organization or folder. In effect, each tag on an organization or folder provides a default value, and each tag on a lower-level resource, such as a folder or project, overrides the default value.

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.

Tag definitions and identifiers

Before you attach tags to resources, you must define the key for the tag, as well as the values that the tag allows. These definitions are tied to your organization. You use Resource Manager to manage tag definitions. To learn more, see Creating and defining a new tag.

Each tag key and value has a few different identifiers:

  • A permanent ID, which is globally unique and can never be reused. For example, a tag key could have the permanent ID tagKeys/123456789012, and a tag value could have the permanent ID tagValues/567890123456.
  • A short name. The short name for each key must be unique within your organization, and the short name for each value must be unique for its associated key. For example, a tag key could have the short name env, and a tag value could have the short name prod.
  • A namespaced name, which adds your organization's numeric ID to the short name of a tag key. For example, a tag key could have the namespaced name 123456789012/env. Learn how to get your organization ID.

As explained on this page, after you attach tags to a resource, you can write conditions to grant access based on tags. To write a condition, you must choose which type of identifier to use in the condition. Follow these guidelines to choose between them:

  • To experiment with tags, consider using the namespaced name (for keys) and the short name (for values). These identifiers are easier to understand and remember, especially as you get started.
  • If you manage your configuration declaratively, using a tool such as Terraform, consider using the namespaced name (for keys) and the short name (for values). You can reuse these identifiers over time, which means that a declarative tool can delete and recreate them, and your conditions will continue to work.

    This approach comes with a tradeoff: Suppose you delete a tag key or value, then create a new key or value with the same name but a different meaning. If your condition refers to the namespaced name or short name, then the condition continues to apply to the new key or value.

    In some cases, this behavior might cause principals to get access that you did not intend for them to have.

  • To help minimize risk, consider using permanent IDs, which can never be reused.

    Here's why permanent IDs help minimize risk: Suppose you delete a tag key or value, then create a new key or value with the same name but a different meaning. If your condition refers to the permanent ID, then the condition does not apply to the new key or value. As a result, principals are less likely to get access that you did not intend for them to have.

    One drawback is that if you delete and recreate keys and values, and you want to preserve principals' access, you must also update your IAM policies to refer to the new permanent IDs.

Access to tagged resources

You can use tags with IAM Conditions to grant a role conditionally, depending on the tags that are attached to or inherited by a resource. If a condition evaluates to true, then access is granted; otherwise, access is not granted. To learn more, see the overview of IAM Conditions.

The following sections show examples of condition expressions that check the tags on a resource. The condition calls different functions depending on whether it checks the permanent ID or the short name. To learn more about these functions, see Resource tags.

Conditions that use permanent IDs

This condition grants a role on resources with the tag tagKeys/123456789012: tagValues/567890123456:

resource.matchTagId('tagKeys/123456789012', 'tagValues/567890123456')

This condition grants a role on resources that have any tag with the key tagKeys/123456789012, regardless of its value:

resource.hasTagKeyId('tagKeys/123456789012')

This condition grants a role on resources that have both the tag tagKeys/123456789012: tagValues/567890123456, and any tag that uses the key tagKeys/987654321098:

resource.matchTagId('tagKeys/123456789012', 'tagValues/567890123456') &&
    resource.hasTagKeyId('tagKeys/987654321098')

Conditions that use namespaced names and short names

This condition grants a role on resources with the tag env: prod, indicating that the resource is in a production environment:

resource.matchTag('123456789012/env', 'prod')

This condition grants a role on resources that have any tag with the key env, regardless of its value:

resource.hasTagKey('123456789012/env')

This condition grants a role on resources that have both the tag env: prod and any tag that uses the key project:

resource.matchTag('123456789012/env', 'prod') &&
    resource.hasTagKey('123456789012/project')

What's next