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 can be used at higher levels of the resource hierarchy and across Google Cloud. They are managed using the Resource Manager and can be referenced in IAM policy bindings to grant conditional access to resources.
Bucket labels are managed using Cloud Storage tools.
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 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 set tags on Cloud Storage buckets and view tags that apply to those buckets:
storage.buckets.listTagBindings
storage.buckets.listEffectiveTags
storage.buckets.createTagBinding
storage.buckets.deleteTagBinding
These permissions can be inherited through IAM roles such as
resourcemanager.tagUser
and storage.admin
.
Note the following restrictions:
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
andus-east3
regions.Tags cannot be applied to Cloud Storage objects.
You can have a maximum of 50 tag bindings per bucket.
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 for tags
Tags attached to Cloud Storage 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
- Learn how to use bucket tags.
- Learn how to use bucket labels.