Create and manage tags

This page describes Google Cloud tags and how to use them withPub/Sub. Tags can be applied to Pub/Sub topics,subscriptions, and snapshots. Support for applying tags to Pub/Subschemas is planned.

About tags

A tag is a key-value pair that can attach to a resource withinGoogle Cloud. You can use tags to conditionally allow or deny policies based onwhether a resource has a specific tag. For example, you can conditionally grantIdentity and Access Management (IAM) roles based on whether a resource has a specific tag.For more information about tags, seeTags overview.

Tags are attached to resources by creating a tag binding resource that links thevalue to the Google Cloud resource.

Required permissions

To get the permissions that you need to manage tags, ask your administrator to grant you the following IAM roles:

  • Tag Viewer (roles/resourcemanager.tagViewer) on the resources the tags are attached to
  • View and manage tags at the organization level:Organization Viewer (roles/resourcemanager.organizationViewer) on the organization
  • Create, update, and delete tag definitions:Tag Administrator (roles/resourcemanager.tagAdmin) on the resource you're creating, updating, or deleting tags for
  • Attach and remove tags from resources:Tag User (roles/resourcemanager.tagUser) on the tag value and the resources that you are attaching or removing the tag value to

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

To attach tags to Pub/Subtopics, subscriptions, or snapshots, you need thePub/SubEditor role (roles/pubsub.editor).

Create tag keys and values

Before you can attach a tag, you need to create a tag and configure its value.To create tag keys and tag values, seeCreating a tag andAdding a tag value.

Add tags during resource creation

You can add tags at the time of creating topics, subscriptions, or snapshots.Adding tags during resource creation, lets you instantly provide essential metadata for your resources and alsohelps with better organization, cost tracking, and automated policy application.

Console

  1. Go to thePub/Sub page in the Google Cloud console.

    2. Go to Pub/Sub

  2. Select the option to create a new topic, subscription, or snapshot.
  3. ClickManage tags.
  4. If your organization doesn't appear in theManage tags panel, clickSelect scope for tags. Choose to add tags defined either at your organization or project level, and then enter the ID for the same.
  5. ClickAdd tag.
  6. Select the key for the tag you want to attach from the list. You can filter the list by typing keywords.
  7. Select the value for the tag you want to attach from the list. You can filter the list by typing keywords.
  8. ClickSave. TheTags section is updated with the tags information.
  9. Create your topic, subscription, or snapshot. The new topic, subscription, or snapshot is created with the provided tags.

gcloud

To add tags duringtopic, subscription, or snapshot creation, run the following command:

       gcloud pubsub topics createTOPIC_ID --tags=TAG_KEY=TAG_VALUE

Replace the following:

  • TOPIC_ID: the ID of the topic
  • TAG_KEY: the permanent ID or namespaced name of the tag key that is attached-for example, tagKeys/567890123456
  • TAG_VALUE: the permanent ID or namespaced name of the tag value that is attached—for example, tagValues/567890123456

Specify multiple tags by separating the tags with a comma, for example,TAGKEY1=TAGVALUE1,TAGKEY2=TAGVALUE2

API

Send aPOST request to the following URL:

      https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID

Provide the following JSON in the request body:

      {  "name": "projects/PROJECT_ID/topics/TOPIC_ID"  "tags": {    "TAGKEY_NAME": "TAGVALUE_NAME"  }}

Replace the following:

  • PROJECT_ID: the ID of the project
  • TOPIC_ID: the ID of the topic
  • TAGKEY_NAME: the permanent ID or namespaced name of the tag key that is attached-for example, tagKeys/567890123456
  • TAGVALUE_NAME: the permanent ID or namespaced name of the tag value that is attached—for example, tagValues/567890123456

Enforce mandatory tags

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

You can enforce mandatory tags on resources to ensure that specific tags arepresent when resources are created, such as a Cost Center tag, to maintaincompliance with organizational policies. You can do this using organizationpolicies and custom constraints. Enforcement occurs at resource creation,preventing the provisioning of resources without the required tags. For moreinformation, seeEnforcement of mandatory tags using organization policies.

Set up a custom constraint to enforce tags

Console

  1. In the Google Cloud console, go to theOrganization policies page.

    Go to Organization policies

  2. Select the project picker at the top of the page.

  3. From the project picker, select the organization where you want toenforce the custom constraint.

  4. Set up a custom constraintwith the following parameters:

    • Enforcement method:Govern tags
    • Resource type: the fully qualified name of the Google CloudREST resource that you want to enforce mandatory tags on, for example,file.googleapis.com/Instance
    • Condition: a Common Expression Language (CEL) condition specifyingthe tag keys that you want to enforce on the resource, for exampleresource.hasDirectTagKey("1234567890/owner") to enforce a tag binding forthe tag key1234567890/owner. Theresource.hasDirectTagKey CEL functiononly matches tags directly applied to a resource and doesn't considertags inherited from ancestors in the resource hierarchy.
    • Action:Allow orDeny.
      • Allow: If the specified condition is met, the action to create or updatethe resource is permitted.
      • Deny: If the specified condition is met, the action to create or updatethe resource is blocked.

  5. ClickCreate constraint.

gcloud

Create a YAML file for the custom constraint:

name:organizations/ORGANIZATION_ID/customConstraints/CONSTRAINT_NAMEresourceTypes:-RESOURCE_NAMEmethodTypes:-GOVERN_TAGScondition:"CONDITION"actionType:ACTIONdisplayName:DISPLAY_NAMEdescription:DESCRIPTION

Replace the following:

  • ORGANIZATION_ID: your organization ID, such as1234567890.

  • CONSTRAINT_NAME: the name you want for your newcustom constraint. A custom constraint must start withcustom., and canonly include uppercase letters, lowercase letters, or numbers, forexample,custom.enforceMandatoryTags.

  • RESOURCE_NAME: the fully qualified name of theGoogle Cloud REST resource that you want to enforce mandatory tags on,for example,file.googleapis.com/Instance.

  • CONDITION: a Common Expression Language (CEL) conditionspecifying the tag keys that you want to enforce on the resource, for exampleresource.hasDirectTagKey("1234567890/owner") to enforce a tag binding forthe tag key1234567890/owner.

  • ACTION: the action to take if thecondition ismet. This can be eitherALLOW orDENY.

    The deny action means that if the specified condition is met, theoperation to create or update the resource is blocked.

    The allow action means that if the specified condition is met,the operation to create or update the resource is permitted. This alsomeans that every other case except the one explicitly listed in thecondition is blocked.

  • DISPLAY_NAME: a human-friendly name for theconstraint. This field has a maximum length of 200 characters.

  • DESCRIPTION: a human-friendly description of theconstraint to display as an error message when the policy is violated. Thisfield has a maximum length of 2000 characters.

Set up the custom constraint to make itavailable for organization policies in your organization.

After you've defined the custom constraint, you cantest and analyze the organization policy changes andenforce the constraint.

Add tags to existing resources

To add a tag to existing topics, subscriptions, or snapshots, follow these steps:

Console

  1. Go to thePub/Sub page in the Google Cloud console.

    2. Go to Pub/Sub

  2. Select the page for the resource to which you want to attach a tag. For example, to attach a tag to a topic, go to theTopics page.
  3. ClickTags.
  4. If your organization doesn't appear in theTags panel, clickSelect scope. Select your organization and clickOpen.
  5. ClickAdd tag.
  6. Select the key for the tag you want to attach from the list. You can filter the list by typing keywords.
  7. Select the value for the tag you want to attach from the list. You can filter the list by typing keywords.
  8. ClickSave.
  9. In theConfirm dialog, clickConfirm to attach the tag.

    10. A notification confirms that your tags updated.

gcloud

To attach a tag to a topic, subscription, or snapshot, you must create a tag binding resource by using thegcloud resource-manager tags bindings create command:

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

Replace the following:

  • TAGVALUE_NAME: 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, includingthe API domain name to identify the type of resource(//pubsub.googleapis.com/). For example, to attach a tag to/projects/PROJECT_ID/topics/TOPIC_ID,the full ID is//pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID.

List tags attached to resources

You can view a list of tag bindings directly attached to or inherited by thetopic, subscription, or snapshot.

Console

  1. Go to thePub/Sub page in the Google Cloud console.

    2. Go to Pub/Sub

  2. Select the page for the resource to which you want to view tags. For example, to view tags for topic, go to theTopics page.

    Tags are displayed in theTags section of the topic page in the console.

gcloud

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

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

Replace the following:

  • RESOURCE_ID is the full ID of the resource, includingthe API domain name to identify the type of resource(//pubsub.googleapis.com/). For example, to attach a tag to/projects/PROJECT_ID/topics/TOPIC_ID,the full ID is//pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID.

You should get a response similar to the following:

name: tagBindings/%2F%2Fcloudresourcemanager.googleapis.com%2Fprojects%2F7890123456/tagValues/567890123456          tagValue: tagValues/567890123456          resource: //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

Detach tags from resources

You can detach tags that have been directly attached toa topic, subscription, or snapshot. Inherited tags can be overridden by attachinga tag with the same key and a different value, but they can't be detached.

Console

  1. Go to thePub/Sub page in the Google Cloud console.

    2. Go to Pub/Sub

  2. Select the page for the resource to which you want to remove a tag. For example, to remove a tag from a topic, go to theTopics page.
  3. ClickTags.
  4. In theTags panel, next to the tag you want to detach, clickDelete item.
  5. ClickSave.
  6. In theConfirm dialog, clickConfirm to detach the tag.

A notification confirms that your tags updated.

gcloud

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

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

Replace the following:

  • TAGVALUE_NAME: 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, includingthe API domain name to identify the type of resource(//pubsub.googleapis.com/). For example, to attach a tag to/projects/PROJECT_ID/topics/TOPIC_ID,the full ID is//pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID.

Delete tag keys and values

When removing a tag key or value definition, ensure that the tag is detached from thetopic, subscription, or snapshot. You must delete existing tag attachments, called tagbindings, before deleting the tag definition itself. To delete tag keys and tagvalues, seeDeleting tags.

Identity and Access Management conditions and tags

You can use tags and IAM conditions to conditionallygrant role bindings to users in your hierarchy. Changing or deleting the tagattached to a resource can remove user access to that resource if anIAM policy with conditional role bindings has been applied. Formore information, seeIdentity and Access Management conditions and tags.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.