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 or project 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 resources or with organization policies to enforce constraints on resources.

When using tags, note the following restrictions:

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

  • Tags cannot be applied to objects.

  • You can have a maximum of 50 tag bindings per bucket.

Required permissions

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

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

These permissions can be inherited through custom roles or predefined roles, such as the Tag User (roles/resourcemanager.tagUser) role or the Storage Admin (roles/storage.admin) role.

Examples for attaching tags to Cloud Storage buckets

Once you've created and defined a tag, you can attach the tag to your 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 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 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 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 for tags

Tags attached to buckets are subject to monthly charges.

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.

Pricing details for labels

Labels set on buckets are not subject to monthly charges.

What's next