This page shows you how to add, modify, remove, and view the labels set on a bucket in Cloud Storage.
Required roles
In order to get the required permissions for adding and managing bucket labels,
ask your administrator to grant you the Storage Admin
(roles/storage.admin
) IAM role on the bucket.
This predefined role contains the permissions required to add and manage bucket labels. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
storage.buckets.get
storage.buckets.list
- This permission is only required if you plan on using the Google Cloud console to perform the instructions on this page.
storage.buckets.update
You might also be able to get these permissions with custom roles.
For instructions on granting roles on buckets, see Use IAM with buckets.
Add, modify, or remove a bucket's labels
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket for which you want to add, modify, or remove labels.
In the Bucket details page, click the Configuration tab.
Click the Edit icon (edit) for Labels.
The label editor window appears.
To add a label, click the add_box Add label button, and specify a
key
and avalue
for your label.To modify an existing label, click its Value and a enter a new value.
To remove a label, click the Trash icon associated with the label you want to remove.
Click Save.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
To add a new label or update an existing label, use the
gcloud storage buckets update
command with the --update-labels
flag. For example:
gcloud storage buckets update gs://BUCKET_NAME --update-labels=KEY_1=VALUE_1
Where
BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
.
To remove an existing label, use the -remove-labels
flag. For example:
gcloud storage buckets update gs://BUCKET_NAME --remove-labels=KEY_1
You can change multiple labels using the previous commands by including the
labels in a comma-separated list within the relevant flag. For example,
--update-labels=blue-key=cyan,red-key=ruby
.
To remove all labels attached to a bucket, use the following command:
gcloud storage buckets update gs://BUCKET_NAME --clear-labels
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample adds the specified label to a bucket, or modifies the label if it already exists for the bucket: The following sample removes the specified label from a bucket:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Create a JSON file that contains the following information:
{ "labels": { "KEY_1": "VALUE_1" } }
Where
KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
. If you want to remove a key, usenull
in place of"<var>VALUE_1</var>"
.
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=labels"
Where:
JSON_FILE_NAME
is the path for the JSON file that you created in Step 2.BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.
You can add, edit, or remove multiple key:value
pairs in a request.
XML API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Create an XML file that contains the following information:
<Tagging> <TagSet> <Tag> <Key>KEY_1</Key> <Value>VALUE_1</Value> </Tag> </TagSet> </Tagging>
Where:
KEY_1
is the key name for your label. For example,pet
.VALUE_1
is the value for your label. For example,dog
.
Note that you can add multiple
<Tag>
elements in a request. If you want to remove all labels on a bucket, use a single, empty<Tag>
element in the file:<Tagging> <TagSet> <Tag> </Tag> </TagSet> </Tagging>
Use
cURL
to call the XML API with aPUT
Bucket request andtagging
query string parameter:curl -X PUT --data-binary @XML_FILE_NAME \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?tagging"
Where:
XML_FILE_NAME
is the path for the XML file that you created in Step 2.BUCKET_NAME
is the name of the bucket that the label applies to. For example,my-bucket
.
View bucket labels
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
Click the name of the bucket whose labels you want to view.
Click the Configuration tab.
The labels set on the bucket are listed in the Labels field.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(labels)"
Where BUCKET_NAME
is the name of the bucket
whose labels you want to view. For example, my-bucket
.
If successful and labels exist for the bucket, the response is similar to the following:
labels: red-key: ruby blue-key: cyan
If successful and labels to not exist for the bucket, the response is similar to the following:
null
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the JSON API with aGET
Bucket request that includes thefields=labels
query string parameter:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=labels"
Where
BUCKET_NAME
is the name of the bucket whose labels you want to view. For example,my-bucket
.
The response looks like the following example:
{ "labels" : { (your_label_key): your_label_value }, }
XML API
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Use
cURL
to call the XML API with aGET
Bucket request andtagging
query string parameter:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?tagging"
Where
BUCKET_NAME
is the name of the bucket whose labels you want to view. For example,my-bucket
.
The response looks like the following example:
<Tagging> <TagSet> <Tag> <Key>your_label_key</Key> <Value>your_label_value</Value> </Tag> </TagSet> </Tagging>
What's next
- Learn about bucket tags.
- Get additional bucket metadata.