Use uniform bucket-level access (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

Use uniform bucket-level access

Overview

This page shows you how to enable, disable, and check the status of uniform bucket-level access on a bucket in Cloud Storage.

Required roles

To get the permissions that you need to set and manage uniform bucket-level access on a bucket, ask your administrator to grant you the Storage Admin (roles/storage.admin) role on the bucket. This predefined role contains the permissions required to set and manage uniform bucket-level access. To see the exact permissions that are required, expand theRequired 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 information about granting roles on buckets, seeUse IAM with buckets.

Check for ACL usage

Before you enable uniform bucket-level access, use Cloud Monitoring to ensure your bucket is not using ACLs for any workflows. For more information, seeCheck object ACL usage.

Console

To view the metrics for a monitored resource by using the Metrics Explorer, do the following:

1. In the Google Cloud console, go to theMetrics explorer page:
   Go to Metrics explorer
   If you use the search bar to find this page, then select the result whose subheading isMonitoring.
2. In the toolbar of the Google Cloud console, select your Google Cloud project. For App Hub configurations, select the App Hub host project or the app-enabled folder's management project.
3. In the Metric element, expand the Select a metric menu, enter ACLs usage in the filter bar, and then use the submenus to select a specific resource type and metric:
   1. In the Active resources menu, select GCS Bucket.
   2. In the Active metric categories menu, select Authz.
   3. In the Active metrics menu, select ACLs usage.
   4. Click Apply.
      The fully qualified name for this metric is storage.googleapis.com/authz/acl_operations_count..
4. To add filters, which remove time series from the query results, use theFilter element.
5. Configure how the data is viewed. For example, to view your data by the ACL operation, for the Aggregation element, set the first menu to Sumand the second menu to acl_operation.
   For more information about configuring a chart, seeSelect metrics when using Metrics Explorer.

See storage for a complete list of metrics available for Cloud Storage. For information about time series, seeMetrics, time series, and resources.

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the MonitoringJSON API:
   curl \
   'https://monitoring.googleapis.com/v3/projects/PROJECT_ID/timeSeries?filter=metric.type%20%3D%20%22storage.googleapis.com%2Fauthz%2Facl_operations_count%22&interval.endTime=END_TIME&interval.startTime=START_TIME' \
   --header 'Authorization: Bearer $(gcloud auth print-access-token)' \
   --header 'Accept: application/json'
   Where:
   • PROJECT_ID is the project ID or number for which you want to view ACL usage. For example, my-project.
   • END_TIME is the end of the time range for which you want to view ACL usage. For example,2019-11-02T15:01:23.045123456Z.
   • START_TIME is the start of the time range for which you want to view ACL usage. For example,2016-10-02T15:01:23.045123456Z.

If the request returns an empty object {}, there is no recent ACL usage for your project.

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 enable or disable uniform bucket-level access.
3. Select the Permissions tab near the top of the page.
4. In the field named Access Control, click the Switch to link.
5. In the menu that appears, select Uniform or Fine-grained.
6. Click Save.

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 update command:

gcloud storage buckets update gs://BUCKET_NAME --STATE

Where:

• BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
• STATE is either uniform-bucket-level-accessto enable uniform bucket-level access or no-uniform-bucket-level-access to disable it.

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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket:

The following sample disables uniform bucket-level access on 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:
   {
   "iamConfiguration": {
   "uniformBucketLevelAccess": {
   "enabled": STATE
   }
   }
   }
   Where STATE is either true or false.
3. Use cURL to call the JSON API with a PATCH Bucketrequest:
   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=iamConfiguration"
   Where:
   • JSON_FILE_NAME is the path for the file that you created in Step 2.
   • BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

XML API

The XML API cannot be used to work with uniform bucket-level access. Use one of the other Cloud Storage tools, such as the gcloud CLI, instead.

View uniform bucket-level access status

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 status you want to view.
3. Click the Configuration tab.
   The uniform bucket-level access status for the bucket is found in theAccess control 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(uniform_bucket_level_access)"

Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.

If successful, the response looks like:

uniform_bucket_level_access: true

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.

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.

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.

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.

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.

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.

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.

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.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.
2. Use cURL to call the JSON API with a GET Bucketrequest that includes the desired fields:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=iamConfiguration"
   Where BUCKET_NAME is the name of the relevant bucket. For example, my-bucket.
   If the bucket has uniform bucket-level access enabled, the response looks like the following example:
   {
   "iamConfiguration": {
   "uniformBucketLevelAccess": {
   "enabled": true,
   "lockedTime": "LOCK_DATE"
   }
   }
   }

XML API

The XML API cannot be used to work with uniform bucket-level access. Use one of the other Cloud Storage tools, such as the gcloud CLI, instead.

What's next

• Learn more about uniform bucket-level access.
• Set IAM permissions on buckets and projects.

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-09 UTC.