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 the Required permissionssection:

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, see Use 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, see Check object ACL usage .

Console

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

In the Google Cloud console, go to the Metrics explorer page:

Go to Metrics explorer

If you use the search bar to find this page, then select the result whose subheading is Monitoring .
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.
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 ..
To add filters, which remove time series from the query results, use the Filter element .
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 Sum and the second menu to acl_operation .
For more information about configuring a chart, see Select metrics when using Metrics Explorer.

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

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Use cURL to call the Monitoring JSON API:

 curl 
  
 \ 
 'h 
 tt 
 ps 
 : 
 //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 
  
 'Au 
 t 
 horiza 
 t 
 io 
 n 
 : 
  
 Bearer 
  
 $(gcloud 
  
 au 
 t 
 h 
  
 pri 
 nt 
 - 
 access 
 - 
 t 
 oke 
 n 
 )' 
  
 \ 
 -- 
 header 
  
 'Accep 
 t 
 : 
  
 applica 
 t 
 io 
 n 
 /jso 
 n 
 '

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.

Set uniform bucket-level access

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
In the list of buckets, click the name of the bucket for which you want to enable or disable uniform bucket-level access.
Select the Permissionstab near the top of the page.
In the field named Access Control, click the Switch tolink.
In the menu that appears, select Uniformor Fine-grained.
Click Save.

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 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-access to enable uniform bucket-level access or no-uniform-bucket-level-access to disable it.

Client libraries

C++

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 gcs 
 :: 
 BucketIamConfiguration 
  
 configuration 
 ; 
  
 configuration 
 . 
 uniform_bucket_level_access 
  
 = 
  
 gcs 
 :: 
 UniformBucketLevelAccess 
 { 
 true 
 , 
  
 {}}; 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 updated 
  
 = 
  
 client 
 . 
 PatchBucket 
 ( 
  
 bucket_name 
 , 
  
 gcs 
 :: 
 BucketMetadataPatchBuilder 
 (). 
 SetIamConfiguration 
 ( 
  
 std 
 :: 
 move 
 ( 
 configuration 
 ))); 
  
 if 
  
 ( 
 ! 
 updated 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 updated 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Successfully enabled Uniform Bucket Level Access on bucket " 
 << 
 updated 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
 }

The following sample disables uniform bucket-level access on a bucket:

  namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 gcs 
 :: 
 BucketIamConfiguration 
  
 configuration 
 ; 
  
 configuration 
 . 
 uniform_bucket_level_access 
  
 = 
  
 gcs 
 :: 
 UniformBucketLevelAccess 
 { 
 false 
 , 
  
 {}}; 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 updated 
  
 = 
  
 client 
 . 
 PatchBucket 
 ( 
  
 bucket_name 
 , 
  
 gcs 
 :: 
 BucketMetadataPatchBuilder 
 (). 
 SetIamConfiguration 
 ( 
  
 std 
 :: 
 move 
 ( 
 configuration 
 ))); 
  
 if 
  
 ( 
 ! 
 updated 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 updated 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Successfully disabled Uniform Bucket Level Access on bucket " 
 << 
 updated 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
 }

C#

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  using 
  
 Google.Apis.Storage.v1.Data 
 ; 
 using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 EnableUniformBucketLevelAccessSample 
 { 
  
 public 
  
 Bucket 
  
 EnableUniformBucketLevelAccess 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 bucket 
 . 
 IamConfiguration 
 . 
 UniformBucketLevelAccess 
 . 
 Enabled 
  
 = 
  
 true 
 ; 
  
 bucket 
  
 = 
  
 storage 
 . 
 UpdateBucket 
 ( 
 bucket 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Uniform bucket-level access was enabled for {bucketName}." 
 ); 
  
 return 
  
 bucket 
 ; 
  
 } 
 }

The following sample disables uniform bucket-level access on a bucket:

  using 
  
 Google.Apis.Storage.v1.Data 
 ; 
 using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 public 
  
 class 
  
 DisableUniformBucketLevelAccessSample 
 { 
  
 public 
  
 Bucket 
  
 DisableUniformBucketLevelAccess 
 ( 
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 bucket 
 . 
 IamConfiguration 
 . 
 UniformBucketLevelAccess 
 . 
 Enabled 
  
 = 
  
 false 
 ; 
  
 bucket 
 . 
 IamConfiguration 
 . 
 BucketPolicyOnly 
 . 
 Enabled 
  
 = 
  
 false 
 ; 
  
 bucket 
  
 = 
  
 storage 
 . 
 UpdateBucket 
 ( 
 bucket 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Uniform bucket-level access was disabled for {bucketName}." 
 ); 
  
 return 
  
 bucket 
 ; 
  
 } 
 }

Go

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // enableUniformBucketLevelAccess sets uniform bucket-level access to true. 
 func 
  
 enableUniformBucketLevelAccess 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 bucket 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ) 
  
 enableUniformBucketLevelAccess 
  
 := 
  
 storage 
 . 
  BucketAttrsToUpdate 
 
 { 
  
 UniformBucketLevelAccess 
 : 
  
& storage 
 . 
  UniformBucketLevelAccess 
 
 { 
  
 Enabled 
 : 
  
 true 
 , 
  
 }, 
  
 } 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Update 
 ( 
 ctx 
 , 
  
 enableUniformBucketLevelAccess 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Update: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Uniform bucket-level access was enabled for %v\n" 
 , 
  
 bucketName 
 ) 
  
 return 
  
 nil 
 }

The following sample disables uniform bucket-level access on a bucket:

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // disableUniformBucketLevelAccess sets uniform bucket-level access to false. 
 func 
  
 disableUniformBucketLevelAccess 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 ) 
  
 error 
  
 { 
  
 // bucketName := "bucket-name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 bucket 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ) 
  
 disableUniformBucketLevelAccess 
  
 := 
  
 storage 
 . 
  BucketAttrsToUpdate 
 
 { 
  
 UniformBucketLevelAccess 
 : 
  
& storage 
 . 
  UniformBucketLevelAccess 
 
 { 
  
 Enabled 
 : 
  
 false 
 , 
  
 }, 
  
 } 
  
 if 
  
 _ 
 , 
  
 err 
  
 := 
  
 bucket 
 . 
 Update 
 ( 
 ctx 
 , 
  
 disableUniformBucketLevelAccess 
 ); 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Update: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Uniform bucket-level access was disabled for %v\n" 
 , 
  
 bucketName 
 ) 
  
 return 
  
 nil 
 }

Java

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. BucketInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
. BucketTargetOption 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 public 
  
 class 
 EnableUniformBucketLevelAccess 
  
 { 
  
 public 
  
 static 
  
 void 
  
 enableUniformBucketLevelAccess 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 throws 
  
  StorageException 
 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
 // first look up the bucket, so we will have its metageneration 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 ); 
  
  BucketInfo 
 
 . 
  IamConfiguration 
 
  
 iamConfiguration 
  
 = 
  
  BucketInfo 
 
 . 
 IamConfiguration 
 . 
 newBuilder 
 (). 
  setIsUniformBucketLevelAccessEnabled 
 
 ( 
 true 
 ). 
 build 
 (); 
  
 storage 
 . 
  update 
 
 ( 
  
 bucket 
 . 
 toBuilder 
 () 
  
 . 
 setIamConfiguration 
 ( 
 iamConfiguration 
 ) 
  
 . 
 setAcl 
 ( 
 null 
 ) 
  
 . 
 setDefaultAcl 
 ( 
 null 
 ) 
  
 . 
 build 
 (), 
  
 BucketTargetOption 
 . 
 metagenerationMatch 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Uniform bucket-level access was enabled for " 
  
 + 
  
 bucketName 
 ); 
  
 } 
 }

The following sample disables uniform bucket-level access on a bucket:

  import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. BucketInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
. BucketTargetOption 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 public 
  
 class 
 DisableUniformBucketLevelAccess 
  
 { 
  
 public 
  
 static 
  
 void 
  
 disableUniformBucketLevelAccess 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 throws 
  
  StorageException 
 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
 // first look up the bucket, so we will have its metageneration 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
 bucketName 
 ); 
  
  BucketInfo 
 
 . 
  IamConfiguration 
 
  
 iamConfiguration 
  
 = 
  
  BucketInfo 
 
 . 
 IamConfiguration 
 . 
 newBuilder 
 () 
  
 . 
  setIsUniformBucketLevelAccessEnabled 
 
 ( 
 false 
 ) 
  
 . 
 build 
 (); 
  
 storage 
 . 
  update 
 
 ( 
  
 bucket 
 . 
 toBuilder 
 (). 
 setIamConfiguration 
 ( 
 iamConfiguration 
 ). 
 build 
 (), 
  
 BucketTargetOption 
 . 
 metagenerationMatch 
 ()); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Uniform bucket-level access was disabled for " 
  
 + 
  
 bucketName 
 ); 
  
 } 
 }

Node.js

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 // Enables uniform bucket-level access for the bucket 
 async 
  
 function 
  
 enableUniformBucketLevelAccess 
 () 
  
 { 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 setMetadata 
 ({ 
  
 iamConfiguration 
 : 
  
 { 
  
 uniformBucketLevelAccess 
 : 
  
 { 
  
 enabled 
 : 
  
 true 
 , 
  
 }, 
  
 }, 
  
 }); 
  
 console 
 . 
 log 
 ( 
 `Uniform bucket-level access was enabled for 
 ${ 
 bucketName 
 } 
 .` 
 ); 
 } 
 enableUniformBucketLevelAccess 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

The following sample disables uniform bucket-level access on a bucket:

  /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 disableUniformBucketLevelAccess 
 () 
  
 { 
  
 // Disables uniform bucket-level access for the bucket 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 setMetadata 
 ({ 
  
 iamConfiguration 
 : 
  
 { 
  
 uniformBucketLevelAccess 
 : 
  
 { 
  
 enabled 
 : 
  
 false 
 , 
  
 }, 
  
 }, 
  
 }); 
  
 console 
 . 
 log 
 ( 
 `Uniform bucket-level access was disabled for 
 ${ 
 bucketName 
 } 
 .` 
 ); 
 } 
 disableUniformBucketLevelAccess 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

PHP

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  use Google\Cloud\Storage\StorageClient; 
 /** 
 * Enable uniform bucket-level access. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function enable_uniform_bucket_level_access(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucket->update([ 
 'iamConfiguration' => [ 
 'uniformBucketLevelAccess' => [ 
 'enabled' => true 
 ], 
 ] 
 ]); 
 printf('Uniform bucket-level access was enabled for %s' . PHP_EOL, $bucketName); 
 }

The following sample disables uniform bucket-level access on a bucket:

  use Google\Cloud\Storage\StorageClient; 
 /** 
 * Enable uniform bucket-level access. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function disable_uniform_bucket_level_access(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucket->update([ 
 'iamConfiguration' => [ 
 'uniformBucketLevelAccess' => [ 
 'enabled' => false 
 ], 
 ] 
 ]); 
 printf('Uniform bucket-level access was disabled for %s' . PHP_EOL, $bucketName); 
 }

Python

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 enable_uniform_bucket_level_access 
 ( 
 bucket_name 
 ): 
  
 """Enable uniform bucket-level access for a bucket""" 
 # bucket_name = "my-bucket" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 bucket 
 . 
  iam_configuration 
 
 . 
  uniform_bucket_level_access_enabled 
 
 = 
 True 
 bucket 
 . 
 patch 
 () 
 print 
 ( 
 f 
 "Uniform bucket-level access was enabled for 
 { 
 bucket 
 . 
 name 
 } 
 ." 
 )

The following sample disables uniform bucket-level access on a bucket:

  from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 disable_uniform_bucket_level_access 
 ( 
 bucket_name 
 ): 
  
 """Disable uniform bucket-level access for a bucket""" 
 # bucket_name = "my-bucket" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 bucket 
 . 
  iam_configuration 
 
 . 
  uniform_bucket_level_access_enabled 
 
 = 
 False 
 bucket 
 . 
 patch 
 () 
 print 
 ( 
 f 
 "Uniform bucket-level access was disabled for 
 { 
 bucket 
 . 
 name 
 } 
 ." 
 )

Ruby

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 client libraries .

The following sample enables uniform bucket-level access on a bucket:

  def 
  
 enable_uniform_bucket_level_access 
  
 bucket_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 bucket 
 . 
 uniform_bucket_level_access 
  
 = 
  
 true 
  
 puts 
  
 "Uniform bucket-level access was enabled for 
 #{ 
 bucket_name 
 } 
 ." 
 end

The following sample disables uniform bucket-level access on a bucket:

  def 
  
 disable_uniform_bucket_level_access 
  
 bucket_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 bucket 
 . 
 uniform_bucket_level_access 
  
 = 
  
 false 
  
 puts 
  
 "Uniform bucket-level access was disabled for 
 #{ 
 bucket_name 
 } 
 ." 
 end

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"

View uniform bucket-level access status

Console

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets
Click the name of the bucket whose status you want to view.
Click the Configurationtab.

The uniform bucket-level access status for the bucket is found in the Access controlfield.

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(uniform_bucket_level_access)"

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

If successful, the response looks like:

 u 
 n 
 i 
 f 
 orm_bucke 
 t 
 _level_access 
 : 
  
 true

Client libraries

C++

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 client libraries .

  namespace 
  
 gcs 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 storage 
 ; 
 using 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 StatusOr 
 ; 
 []( 
 gcs 
 :: 
 Client 
  
 client 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 bucket_name 
 ) 
  
 { 
  
 StatusOr<gcs 
 :: 
 BucketMetadata 
>  
 bucket_metadata 
  
 = 
  
 client 
 . 
 GetBucketMetadata 
 ( 
 bucket_name 
 ); 
  
 if 
  
 ( 
 ! 
 bucket_metadata 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 bucket_metadata 
 ). 
 status 
 (); 
  
 if 
  
 ( 
 bucket_metadata 
 - 
> has_iam_configuration 
 () 
  
&&  
 bucket_metadata 
 - 
> iam_configuration 
 () 
  
 . 
 uniform_bucket_level_access 
 . 
 has_value 
 ()) 
  
 { 
  
 gcs 
 :: 
 UniformBucketLevelAccess 
  
 uniform_bucket_level_access 
  
 = 
  
 * 
 bucket_metadata 
 - 
> iam_configuration 
 (). 
 uniform_bucket_level_access 
 ; 
  
 std 
 :: 
 cout 
 << 
 "Uniform Bucket Level Access is enabled for " 
 << 
 bucket_metadata 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
  
 std 
 :: 
 cout 
 << 
 "Bucket will be locked on " 
 << 
 uniform_bucket_level_access 
 << 
 " 
 \n 
 " 
 ; 
  
 } 
  
 else 
  
 { 
  
 std 
 :: 
 cout 
 << 
 "Uniform Bucket Level Access is not enabled for " 
 << 
 bucket_metadata 
 - 
> name 
 () 
 << 
 " 
 \n 
 " 
 ; 
  
 } 
 }

C#

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 client libraries .

  using 
  
  Google.Cloud.Storage.V1 
 
 ; 
 using 
  
 System 
 ; 
 using 
  
 static 
  
 Google 
 . 
 Apis 
 . 
 Storage 
 . 
 v1 
 . 
 Data 
 . 
 Bucket 
 . 
 IamConfigurationData 
 ; 
 public 
  
 class 
  
 GetUniformBucketLevelAccessSample 
 { 
  
 public 
  
 UniformBucketLevelAccessData 
  
 GetUniformBucketLevelAccess 
 ( 
  
 string 
  
 bucketName 
  
 = 
  
 "your-unique-bucket-name" 
 ) 
  
 { 
  
 var 
  
 storage 
  
 = 
  
  StorageClient 
 
 . 
  Create 
 
 (); 
  
 var 
  
 bucket 
  
 = 
  
 storage 
 . 
 GetBucket 
 ( 
 bucketName 
 ); 
  
 var 
  
 uniformBucketLevelAccess 
  
 = 
  
 bucket 
 . 
 IamConfiguration 
 . 
 UniformBucketLevelAccess 
 ; 
  
 bool 
  
 uniformBucketLevelAccessEnabled 
  
 = 
  
 uniformBucketLevelAccess 
 . 
 Enabled 
  
 ?? 
  
 false 
 ; 
  
 if 
  
 ( 
 uniformBucketLevelAccessEnabled 
 ) 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Uniform bucket-level access is enabled for {bucketName}." 
 ); 
  
 Console 
 . 
 WriteLine 
 ( 
  
 $"Uniform bucket-level access will be locked on {uniformBucketLevelAccess.LockedTime}." 
 ); 
  
 } 
  
 else 
  
 { 
  
 Console 
 . 
 WriteLine 
 ( 
 $"Uniform bucket-level access is not enabled for {bucketName}." 
 ); 
  
 } 
  
 return 
  
 uniformBucketLevelAccess 
 ; 
  
 } 
 }

Go

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 client libraries .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 "time" 
  
 "cloud.google.com/go/storage" 
 ) 
 // getUniformBucketLevelAccess gets uniform bucket-level access. 
 func 
  
 getUniformBucketLevelAccess 
 ( 
 w 
  
 io 
 . 
  Writer 
 
 , 
  
 bucketName 
  
 string 
 ) 
  
 ( 
 * 
 storage 
 . 
  BucketAttrs 
 
 , 
  
 error 
 ) 
  
 { 
  
 // bucketName := "bucket-name" 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 client 
 , 
  
 err 
  
 := 
  
 storage 
 . 
 NewClient 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "storage.NewClient: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 defer 
  
 client 
 . 
 Close 
 () 
  
 ctx 
 , 
  
 cancel 
  
 := 
  
 context 
 . 
 WithTimeout 
 ( 
 ctx 
 , 
  
 time 
 . 
 Second 
 * 
 10 
 ) 
  
 defer 
  
 cancel 
 () 
  
 attrs 
 , 
  
 err 
  
 := 
  
 client 
 . 
  Bucket 
 
 ( 
 bucketName 
 ). 
 Attrs 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "Bucket(%q).Attrs: %w" 
 , 
  
 bucketName 
 , 
  
 err 
 ) 
  
 } 
  
 uniformBucketLevelAccess 
  
 := 
  
 attrs 
 . 
  UniformBucketLevelAccess 
 
  
 if 
  
 uniformBucketLevelAccess 
 . 
 Enabled 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Uniform bucket-level access is enabled for %q.\n" 
 , 
  
 attrs 
 . 
 Name 
 ) 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Bucket will be locked on %q.\n" 
 , 
  
 uniformBucketLevelAccess 
 . 
 LockedTime 
 ) 
  
 } 
  
 else 
  
 { 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Uniform bucket-level access is not enabled for %q.\n" 
 , 
  
 attrs 
 . 
 Name 
 ) 
  
 } 
  
 return 
  
 attrs 
 , 
  
 nil 
 }

Java

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 client libraries .

  import 
  
 com.google.cloud.storage. Bucket 
 
 ; 
 import 
  
 com.google.cloud.storage. BucketInfo 
 
 ; 
 import 
  
 com.google.cloud.storage. Storage 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageException 
 
 ; 
 import 
  
 com.google.cloud.storage. StorageOptions 
 
 ; 
 import 
  
 java.util.Date 
 ; 
 public 
  
 class 
 GetUniformBucketLevelAccess 
  
 { 
  
 public 
  
 static 
  
 void 
  
 getUniformBucketLevelAccess 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 bucketName 
 ) 
  
 throws 
  
  StorageException 
 
  
 { 
  
 // The ID of your GCP project 
  
 // String projectId = "your-project-id"; 
  
 // The ID of your GCS bucket 
  
 // String bucketName = "your-unique-bucket-name"; 
  
  Storage 
 
  
 storage 
  
 = 
  
  StorageOptions 
 
 . 
 newBuilder 
 (). 
 setProjectId 
 ( 
 projectId 
 ). 
 build 
 (). 
  getService 
 
 (); 
  
  Bucket 
 
  
 bucket 
  
 = 
  
 storage 
 . 
  get 
 
 ( 
  
 bucketName 
 , 
  
 Storage 
 . 
 BucketGetOption 
 . 
 fields 
 ( 
 Storage 
 . 
 BucketField 
 . 
 IAMCONFIGURATION 
 )); 
  
  BucketInfo 
 
 . 
  IamConfiguration 
 
  
 iamConfiguration 
  
 = 
  
 bucket 
 . 
  getIamConfiguration 
 
 (); 
  
 Boolean 
  
 enabled 
  
 = 
  
 iamConfiguration 
 . 
  isUniformBucketLevelAccessEnabled 
 
 (); 
  
 Date 
  
 lockedTime 
  
 = 
  
 new 
  
 Date 
 ( 
 iamConfiguration 
 . 
  getUniformBucketLevelAccessLockedTime 
 
 ()); 
  
 if 
  
 ( 
 enabled 
  
 != 
  
 null 
 && 
 enabled 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Uniform bucket-level access is enabled for " 
  
 + 
  
 bucketName 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Bucket will be locked on " 
  
 + 
  
 lockedTime 
 ); 
  
 } 
  
 else 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Uniform bucket-level access is disabled for " 
  
 + 
  
 bucketName 
 ); 
  
 } 
  
 } 
 }

Node.js

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 client libraries .

  /** 
 * TODO(developer): Uncomment the following lines before running the sample. 
 */ 
 // The ID of your GCS bucket 
 // const bucketName = 'your-unique-bucket-name'; 
 // Imports the Google Cloud client library 
 const 
  
 { 
 Storage 
 } 
  
 = 
  
 require 
 ( 
 ' @google-cloud/storage 
' 
 ); 
 // Creates a client 
 const 
  
 storage 
  
 = 
  
 new 
  
 Storage 
 (); 
 async 
  
 function 
  
 getUniformBucketLevelAccess 
 () 
  
 { 
  
 // Gets Bucket Metadata and checks if uniform bucket-level access is enabled. 
  
 const 
  
 [ 
 metadata 
 ] 
  
 = 
  
 await 
  
 storage 
 . 
 bucket 
 ( 
 bucketName 
 ). 
 getMetadata 
 (); 
  
 if 
  
 ( 
 metadata 
 . 
  iamConfiguration 
 
 ) 
  
 { 
  
 const 
  
 uniformBucketLevelAccess 
  
 = 
  
 metadata 
 . 
  iamConfiguration 
 
 . 
 uniformBucketLevelAccess 
 ; 
  
 console 
 . 
 log 
 ( 
 `Uniform bucket-level access is enabled for 
 ${ 
 bucketName 
 } 
 .` 
 ); 
  
 console 
 . 
 log 
 ( 
  
 `Bucket will be locked on 
 ${ 
 uniformBucketLevelAccess 
 . 
 lockedTime 
 } 
 .` 
  
 ); 
  
 } 
  
 else 
  
 { 
  
 console 
 . 
 log 
 ( 
  
 `Uniform bucket-level access is not enabled for 
 ${ 
 bucketName 
 } 
 .` 
  
 ); 
  
 } 
 } 
 getUniformBucketLevelAccess 
 (). 
 catch 
 ( 
 console 
 . 
 error 
 );

PHP

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 client libraries .

  use Google\Cloud\Storage\StorageClient; 
 /** 
 * Enable uniform bucket-level access. 
 * 
 * @param string $bucketName The name of your Cloud Storage bucket. 
 *        (e.g. 'my-bucket') 
 */ 
 function get_uniform_bucket_level_access(string $bucketName): void 
 { 
 $storage = new StorageClient(); 
 $bucket = $storage->bucket($bucketName); 
 $bucketInformation = $bucket->info(); 
 $ubla = $bucketInformation['iamConfiguration']['uniformBucketLevelAccess']; 
 if ($ubla['enabled']) { 
 printf('Uniform bucket-level access is enabled for %s' . PHP_EOL, $bucketName); 
 printf('Uniform bucket-level access will be locked on %s' . PHP_EOL, $ubla['LockedTime']); 
 } else { 
 printf('Uniform bucket-level access is disabled for %s' . PHP_EOL, $bucketName); 
 } 
 }

Python

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 client libraries .

  from 
  
 google.cloud 
  
 import 
  storage 
 
 def 
  
 get_uniform_bucket_level_access 
 ( 
 bucket_name 
 ): 
  
 """Get uniform bucket-level access for a bucket""" 
 # bucket_name = "my-bucket" 
 storage_client 
 = 
  storage 
 
 . 
  Client 
 
 () 
 bucket 
 = 
 storage_client 
 . 
  get_bucket 
 
 ( 
 bucket_name 
 ) 
 iam_configuration 
 = 
 bucket 
 . 
  iam_configuration 
 
 if 
  iam_configuration 
 
 . 
  uniform_bucket_level_access_enabled 
 
 : 
 print 
 ( 
 f 
 "Uniform bucket-level access is enabled for 
 { 
 bucket 
 . 
 name 
 } 
 ." 
 ) 
 print 
 ( 
 "Bucket will be locked on 
 {} 
 ." 
 . 
 format 
 ( 
  iam_configuration 
 
 . 
 uniform_bucket_level_locked_time 
 ) 
 ) 
 else 
 : 
 print 
 ( 
 f 
 "Uniform bucket-level access is disabled for 
 { 
 bucket 
 . 
 name 
 } 
 ." 
 )

Ruby

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 client libraries .

  def 
  
 get_uniform_bucket_level_access 
  
 bucket_name 
 : 
  
 # The ID of your GCS bucket 
  
 # bucket_name = "your-unique-bucket-name" 
  
 require 
  
 "google/cloud/storage" 
  
 storage 
  
 = 
  
 Google 
 :: 
 Cloud 
 :: 
  Storage 
 
 . 
  new 
 
  
 bucket 
  
 = 
  
 storage 
 . 
 bucket 
  
 bucket_name 
  
 if 
  
 bucket 
 . 
  uniform_bucket_level_access? 
 
  
 puts 
  
 "Uniform bucket-level access is enabled for 
 #{ 
 bucket_name 
 } 
 ." 
  
 puts 
  
 "Bucket will be locked on 
 #{ 
 bucket 
 . 
  uniform_bucket_level_access_locked_at 
 
 } 
 ." 
  
 else 
  
 puts 
  
 "Uniform bucket-level access is disabled for 
 #{ 
 bucket_name 
 } 
 ." 
  
 end 
 end

What's next

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

Use uniform bucket-level access

Required roles

Required permissions

Check for ACL usage

Console

JSON API

Set uniform bucket-level access

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

View uniform bucket-level access status

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

What's next

Use uniform bucket-level access Stay organized with collections Save and categorize content based on your preferences.

Required roles

Required permissions

Check for ACL usage

Console

JSON API

Set uniform bucket-level access

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

View uniform bucket-level access status

Console

Command line

Client libraries

C++

C#

Go

Java

Node.js

PHP

Python

Ruby

REST APIs

JSON API

XML API

What's next

Use uniform bucket-level access