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 and granular cost data at the bucket level.
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. You can also use the tag to analyze detailed usage cost data exported to Cloud Billing.
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.
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 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.