This page shows you how to enable, disable and check the status of uniform bucket-level access on a bucket in Cloud Storage.
Prerequisites
Before using this feature in Cloud Storage, you should:
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 Monitoring page.
If you have never used Cloud Monitoring, then on your first access of Monitoring in the Google Cloud Console, a Workspace is automatically created and your project is associated with that Workspace. Otherwise, if your project isn't associated with a Workspace, then a dialog appears and you can either create a Workspace or add your project to an existing Workspace. We recommend that you create a Workspace. After you make your selection, click Add.
- In the Monitoring navigation pane, click
Metrics Explorer.
- Ensure that Metric is the selected tab.
- In the Find resource type and metric field, select from the menu or
enter the name for the resource and metric. Use the following information to complete the
fields:
- For the Resource, select or enter gcs_bucket.
- For the Metric, select or enter ACLs usage.
- To modify how the data is displayed, use the Filter, Group By, and Aggregator menus. 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 Selecting metrics.
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.
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.
Enable uniform bucket-level access
To enable uniform bucket-level access on your bucket:
Console
- In the Google Cloud Console, go to the Cloud Storage Browser 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 Switch to uniform.
In the pop-up menu that appears, select Uniform.
Click Save.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the on
option in a uniformbucketlevelaccess set
command:
gsutil uniformbucketlevelaccess set on gs://BUCKET_NAME
where 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/...
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
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.
Create a .json file that contains the following information:
{ "iamConfiguration": { "uniformBucketLevelAccess": { "enabled": true } } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -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 name of the file 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 Browser 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 operations in the Cloud Storage browser, see Troubleshooting.
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
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
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.
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.
Disable uniform bucket-level access
You must remove all IAM conditions from the bucket's IAM policy before you can disable uniform bucket-level access.
To disable uniform bucket-level access on your bucket:
Console
- In the Google Cloud Console, go to the Cloud Storage Browser 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 Switch to fine-grained. Note that the text box disappears 90 days after you enable uniform bucket-level access.
In the pop-up menu that appears, select Fine-grained.
Click Save.
To learn how to get detailed error information about failed operations in the Cloud Storage browser, see Troubleshooting.
gsutil
Use the off
option in a uniformbucketlevelaccess set
command:
gsutil uniformbucketlevelaccess set off gs://BUCKET_NAME
where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If successful, the response looks like:
Disabling uniform bucket-level access for gs://my-bucket/...
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
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.
Create a .json file that contains the following information:
{ "iamConfiguration": { "uniformBucketLevelAccess": { "enabled": false } } }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl -X PATCH --data-binary @JSON_FILE_NAME.json \ -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 name of the file 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.