This page shows you how to enable, disable, and check the status of uniform bucket-level access on a bucket in Cloud Storage.
Before you begin
Before using this feature in Cloud Storage, you must have sufficient permission to view and update buckets in Cloud Storage:
If you own the project that contains the bucket, you most likely have the necessary permissions.
You should have the
storage.buckets.update
andstorage.buckets.get
IAM permissions on the relevant bucket. See Using IAM Permissions for instructions on how to get a role, such as Storage Admin, that has these permissions.
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 use Metrics Explorer to view the metrics for a monitored resource, follow these steps:
- In the Google Cloud console, go to the Metrics Explorer page within Monitoring.
- In the Select a metric pane, expand the Metric menu,
enter
ACLs usage
in the filter bar, and then use the submenus to select a specific resource type and metric:- In the Active resources menu, select GCS Bucket.
- In the Active metric categories menu, select Authz.
- In the Active metrics menu, select ACLs usage.
- Click Apply.
- Configure how the data is viewed. By default, Metrics Explorer adds a grouping that averages all time series. For example, to group the data by bucket and ACL operation, select acl_operation for Group By and sum for Aggregator. For more information, 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
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the Monitoring JSON 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 OAUTH2_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
.OAUTH2_TOKEN
is the access token you generated in Step 1.
If the request returns an empty object {}
, there is no recent ACL usage for your project.
Set uniform bucket-level access
To enable or disable uniform bucket-level access on your bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click on the name of the desired bucket.
Select the Permissions tab near the top of the page.
In the text box named Access Control, click the Switch to link. Note that the text box disappears 90 days after you enable uniform bucket-level access.
In the pop-up menu that appears, select Uniform or 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
gcloud
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 eitheruniform-bucket-level-access
to enable uniform bucket-level access orno-uniform-bucket-level-access
to disable it.
gsutil
Use the uniformbucketlevelaccess set
command:
gsutil uniformbucketlevelaccess set STATE gs://BUCKET_NAME
Where:
STATE
is eitheron
oroff
.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
If successful, the response looks like:
Enabling uniform bucket-level access for gs://test-bucket/...
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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on 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 enables uniform bucket-level access on a bucket: The following sample disables uniform bucket-level access on a bucket:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Create a JSON file that contains the following information:
{ "iamConfiguration": { "uniformBucketLevelAccess": { "enabled": STATE } } }
Where STATE is either
true
orfalse
.Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer OAUTH2_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.OAUTH2_TOKEN
is the access token you generated in Step 1.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 gsutil, instead.
View uniform bucket-level access status
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the Column display options menu (
), make sure Access control is checked.
In the list of buckets, the uniform bucket-level access status of each bucket is found in the Access control column.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
gcloud
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(iamConfiguration[uniformBucketLevelAccess])"
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If successful, the response looks like:
iamConfiguration: uniformBucketLevelAccess: enabled: true
gsutil
Use the uniformbucketlevelaccess get
command:
gsutil uniformbucketlevelaccess get gs://BUCKET_NAME
where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If uniform bucket-level access is enabled, the response looks like:
Uniform bucket-level access setting for gs://my-bucket/: Enabled: True LockedTime: LOCK_DATE
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
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the JSON API with aGET
Bucket request that includes the desiredfields
:curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=iamConfiguration"
Where:
OAUTH2_TOKEN
is the access token you generated in Step 1.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 gsutil, instead.