This page describes how to use the Bucket Lock feature, including working with retention policies and permanently locking them on buckets.
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.
If you use IAM, you should have
storage.buckets.update
andstorage.buckets.get
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.If you use ACLs, you should have OWNER permission on the relevant bucket. See Setting ACLs for instructions on how to do this.
Check that Object Versioning is disabled for the bucket.
Setting a retention policy on a bucket
To set a retention policy on a bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that you want to add a retention policy for.
Select the Retention tab near the top of the page.
In the Retention policy entry, click the + Set Retention Policy link.
The Set a retention policy dialog box appears.
In the drop down, select the unit of time for your retention period.
See Retention periods for information about how the Console converts between different units of time.
In the value box, enter the length of time for your retention period.
Click Save.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil retention set
command:
gsutil retention set TIME_DURATION gs://BUCKET_NAME
Where:
TIME_DURATION
is the amount of time objects in the bucket must be retained. For example,2678400s
. See Retention periods for information about how gsutil converts between different units of time.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
If successful, the response looks like:
Setting retention policy on 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:
{ "retentionPolicy": { "retentionPeriod": "TIME_IN_SECONDS" } }
Where
TIME_IN_SECONDS
is the amount of time in seconds that objects in the bucket must be retained. For example,2678400
. See Retention periods for information about how different units of time are measured using seconds.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=retentionPolicy"
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 set a retention policy on an existing bucket. It can only be used to include a retention policy with a new bucket.
Removing a retention policy from a bucket
To remove a retention policy from a bucket:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that you want to remove the retention policy from.
Select the Retention tab near the top of the page.
In the Retention policy entry, click the Delete button.
The Delete retention policy? dialog box appears.
Click Delete.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the gsutil retention clear
command:
gsutil retention clear gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If successful, the response looks like:
Clearing retention policy on 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:
{ "retentionPolicy": null }
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=retentionPolicy"
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 remove a retention policy from a bucket. Use one of the other Cloud Storage tools, such as gsutil, instead.
Locking a bucket
To lock a bucket and permanently restrict edits to the bucket's retention policy:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the list of buckets, click on the name of the bucket that you want to lock the retention policy for.
Select the Retention tab near the top of the page.
In the Retention policy entry, click the Lock button.
The Lock retention policy? dialog box appears.
Read the Permanent notice.
In the Bucket name text box, type in the name of your bucket.
Click Lock policy.
See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.
gsutil
Use the
gsutil retention lock
command:gsutil retention lock gs://BUCKET_NAME
Where
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.When prompted to continue, type
y
.
If successful, the response looks like:
Locking retention policy on 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.
Use
cURL
to call the JSON API with aPOST
Bucket request:curl -X POST \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/lockRetentionPolicy?ifMetagenerationMatch=BUCKET_METAGENERATION_NUMBER"
Where:
OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.BUCKET_METAGENERATION_NUMBER
is the metageneration value for the bucket. For example,8
. You can find the metageneration value for your bucket by calling the JSON API with aGET
Bucket request.
XML API
The XML API cannot be used to lock a bucket. Use one of the other Cloud Storage tools, such as gsutil, instead.
Viewing a bucket's retention policy and lock status
To view what, if any, retention policy is set on a bucket and whether that retention policy is locked:
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser In the Column display options menu (
), make sure Retention policy is checked.
In the list of buckets, the retention period of each bucket is found in the Retention policy column. If the retention policy is locked, an image of a lock appears directly to the left of the retention period.
gsutil
Use the gsutil retention get
command:
gsutil retention get gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If successful, the response looks like:
gs://my-bucket/ has no retention policy.
or:
gs://retention-test/: Retention policy LOCK_STATUS: Duration: TIME_LENGTH Effective Time: SET_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=retentionPolicy"
Where:
OAUTH2_TOKEN
is the name of 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 a retention policy set on it, the response looks like the following example:
{ "retentionPolicy": { "retentionPeriod": "TIME_IN_SECONDS", "effectiveTime": "DATETIME", "isLocked": "BOOLEAN" }, }
XML API
The XML API cannot be used to view the retention policy on a bucket. Use one of the other Cloud Storage tools, such as gsutil, instead.
What's next
- Learn more about retention policies.
- Learn how to use object holds.
- Learn about Object Lifecycle Management, which can automatically delete files once they reach their retention period.