Tags and labels

This page describes the tags and labels you can set on Cloud Storage resources.

Overview

Google Cloud tags and Cloud Storage bucket labels are two ways to organize your Cloud Storage resources.

Tags and labels work independently of each other, and you can use both on the same bucket.

Tags

Tags are key-value pairs you can apply to your resources for fine-grained access control.

Tags are created at the organization level and managed through the Resource Manager, which is used across Google Cloud. Once you attach a tag to a Cloud Storage bucket, you can use the tag with IAM Conditions to grant access to Cloud Storage resources or with organization policies to enforce constraints on Cloud Storage resources.

Although tags are managed through the Resource Manager, you need the following Cloud Storage IAM permissions to view and set tags on Cloud Storage buckets:

  • storage.buckets.listTagBindings
  • storage.buckets.createTagBinding
  • storage.buckets.deleteTagBinding

These permissions can be inherited through IAM roles such as resourcemanager.tagUser and storage.admin.

Keep these restrictions in mind for Preview:

  • Tags can be attached to a bucket only after the bucket has been created.

  • Tags are not supported for buckets located in the us-east2, us-east3, and us-south1 regions.

  • Tags are ignored by the domain restricted sharing constraint. For example, say you use the constraint to specify that only users from exampledomain.com can be added to a bucket's IAM policy if a tag is attached to the bucket. However, even when a tag is attached to the bucket, users from outside exampledomain.com can still be added to the bucket's IAM policy.

  • In rare cases, you may experience high latencies when reading or modifying tags attached to buckets.

Tags cannot be applied to Cloud Storage objects.

Examples for attaching tags to Cloud Storage buckets

Once you've created and defined a tag, you can attach the tag to your Cloud Storage bucket.

Consider the following scenario:

  • The tag value has a namespaced name of 815471563813/color/blue.
  • Your bucket is named my-bucket.
  • Your bucket is located in us-central1.

The following gcloud command attaches the tag to my-bucket:

gcloud alpha resource-manager tags bindings create \
--tag-value=815471563813/color/blue \
--parent=//storage.googleapis.com/projects/_/buckets/my-bucket
--location=us-central1

The following gcloud command detaches the tag from my-bucket:

gcloud alpha resource-manager tags bindings delete \
--tag-value=815471563813/color/blue \
--parent=//storage.googleapis.com/projects/_/buckets/my-bucket \
--location=us-central1

The following gcloud command lists all tags directly attached to my-bucket, except tags that my-bucket has inherited:

gcloud alpha resource-manager tags bindings list \
    --parent=//storage.googleapis.com/projects/_/buckets/my-bucket \
    --location=us-central1

For more detailed instructions, see Attaching tags to resources.

Pricing details

Tags for Cloud Storage buckets are 100% discounted until September 15, 2022. After September 15, 2022, tags for Cloud Storage buckets are subject to pricing.

Bucket labels are free to use.

Bucket labels

Bucket labels allow you to create arbitrary key:value pairs that are stored as part of the bucket's metadata. You can use labels to organize your buckets along with other Google Cloud resources such as virtual machine instances and persistent disks. For example, say you want a key named team that has the values alpha, beta, and delta, which you will use to indicate which team is associated with certain Google Cloud resources. You can apply the labels team:alpha, team:beta, and team:delta to the desired resources to achieve this.

Keep in mind the following when working with bucket labels:

  • Keys and values cannot be longer than 63 characters each.
  • Keys and values can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed.
  • Label keys must start with a lowercase letter and international characters are allowed.
  • Label keys cannot be empty.
  • Each bucket can have a maximum of 64 labels actively applied to it.
  • As is generally the case for bucket metadata, bucket labels are not associated with individual objects or object metadata.

For a general example of using labels to organize your resources in billing, see Billing Export to BigQuery Query Examples.

What's next