Using bucket labels (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Using bucket labels

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, seeSet and manage IAM policies on buckets.

Add, modify, or remove a bucket's labels

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. In the list of buckets, click the name of the bucket for which you want to add, modify, or remove labels.
3. In the Bucket details page, click the Configuration tab.
4. Click the Edit icon () for Labels.
   The label editor window appears.
   1. To add a label, click theAdd label button, and specify a key and a value for your label.
   2. To modify an existing label, click its Value and a enter a new value.
   3. To remove a label, click the Trash icon associated with the label you want to remove.
5. Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

To add a new label or update an existing label, use thegcloud storage buckets update command with the --update-labelsflag. 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

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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:

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. 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, use null in place of "<var>VALUE_1</var>".
3. 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

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Create an XML file that contains the following information: 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`. Note that you can add multiple `` elements in a request. If you want to remove all labels on a bucket, use a single, empty`` element in the file:
3. Use cURL to call the XML API with aPUT Bucket request and tagging 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.

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   Go to Buckets
2. Click the name of the bucket whose labels you want to view.
3. 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, seeTroubleshooting.

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

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

To view a bucket's labels, follow the instructions for displaying a bucket's metadata and look for the label field in the response.

REST APIs

What's next

• Learn about bucket tags.
• Get additional bucket metadata.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.