This page describes how to use the Bucket Lock feature, including working with retention policies and permanently locking them on buckets.
Before you begin
Before using this feature in Cloud Storage, you must meet the following requirements:
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.
Have Object Versioning disabled for the bucket. See Use Object Versioning for instructions on how to check whether Object Versioning is disabled for a bucket.
Set a retention policy on a bucket
To add, modify, or remove a retention policy on a 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 bucket whose retention policy you want to change.
Select the Protection tab near the top of the page.
In the Retention policy section, set your retention policy:
If no retention policy currently applies to the bucket, click the + Set Retention Policy link. Choose a unit of time and a length of time for your retention period.
If a retention policy currently applies to a bucket, it appears in the section. Click Edit to modify the retention time or Delete to remove the retention policy entirely.
See Retention periods for information about how the Google Cloud console converts between different units of time.
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 with the
appropriate flag:
gcloud storage buckets update gs://BUCKET_NAME FLAG
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.FLAG
is the desired setting for the bucket's retention period. Use one of the following formats:--retention-period
and a retention period, if you want to add or change a retention policy. For example,--retention-period=1d43200s
.--clear-retention-period
, if you want to remove the retention policy on the bucket.
If successful, the response looks like:
Updating gs://my-bucket/... Completed 1
gsutil
Use the gsutil retention
command:
gsutil retention STATE gs://BUCKET_NAME
Where:
STATE
is the desired state of the retention policy on the bucket. Use one of the following formats:set
and a retention period, if you want to add or change a retention policy. For example,set 2678400s
.clear
, if you want to remove the retention policy on the bucket.
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/...
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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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 sets a retention policy on a bucket: The following sample removes the retention policy from 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:
{ "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.To remove the retention policy from a bucket, use the following in the JSON file:
{ "retentionPolicy": null }
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=retentionPolicy"
Where:
JSON_FILE_NAME
is the path for the JSON 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 set or remove a retention policy on an existing bucket. It can only be used to include a retention policy with a new bucket.
Lock a bucket
To lock a bucket and permanently restrict edits to the bucket's retention policy:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click on the name of the bucket that you want to lock the retention policy for.
Select the Protection tab near the top of the page.
In the Retention policy section, 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.
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 with the
--lock-retention-period
flag:
gcloud storage buckets update gs://BUCKET_NAME --lock-retention-period
Where BUCKET_NAME
is the name of the relevant
bucket. For example, my-bucket
.
If successful, the response looks similar to the following example:
Updating gs://my-bucket/... Completed 1
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/...
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 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.
View 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
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the Column display options menu (
), make sure Retention policy is checked.
In the list of buckets, if a bucket has a retention policy, the retention period is displayed in the Protection column for the bucket. If the retention policy is locked, an image of a lock appears directly to the left of the retention period.
Command line
gcloud
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(retentionPolicy)"
Where BUCKET_NAME
is the name of the bucket
whose retention policy you want to view. For example, my-bucket
.
If successful and a retention policy exists for the bucket, the response is similar to the following:
retentionPolicy: effectiveTime: '2022-10-04T18:51:22.161000+00:00' retentionPeriod: '129600'
If successful and a retention policy does not exist for the bucket, the response is similar to the following:
null
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 and a retention policy exists for the bucket, the response is similar to the following:
gs://retention-test/: Retention policy LOCK_STATUS: Duration: TIME_LENGTH Effective Time: SET_DATE
If successful and a retention policy does not exist for the bucket, the response is similar to the following:
gs://my-bucket/ has no retention policy.
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=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.