This page describes the tags and labels you can set on Cloud Storage resources.
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 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:
These permissions can be inherited through IAM roles such as
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
Tags are ignored by the domain restricted sharing constraint. For example, say you use the constraint to specify that only users from
exampledomain.comcan 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.comcan 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
- Your bucket is named
- Your bucket is located in
The following gcloud command attaches the tag to
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
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 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.
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 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
has the values
delta, which you will use to indicate
which team is associated with certain Google Cloud resources. You can
apply the labels
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.