This page describes how to enable, disable, update, and check the status of the soft delete policy on a bucket. To learn how to list and restore the soft-deleted objects, see Use soft-deleted objects.
Before you begin
To create and manage the soft delete policy on a bucket, make sure
that you have the Storage Admin (roles/storage.admin
) IAM
role on the bucket or the project that contains the bucket. This
predefined role includes the permissions required to create and manage
soft delete on a bucket.
To see the exact permissions that are required, expand the Required permissions section:
Required permissions
storage.buckets.get
storage.buckets.update
storage.buckets.list
- This permission is required if you plan to use Google Cloud console to perform the instructions on this page.
For information about granting roles on buckets, see Use IAM with buckets. For information about granting roles on projects, see Manage access to projects.
Manage a bucket's soft delete policy
To add, remove, or change the soft delete policy for a bucket:
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket whose soft delete policy you want to manage.
Click the Protection tab.
In the Soft delete policy section, perform one of the following actions:
If the bucket does not have a soft delete policy, click Set soft delete policy, choose a unit of time and a length of time for your retention duration, and click Save.
If the bucket has a soft delete policy, click Edit to change the length of time for your retention duration, or click Delete to remove the soft delete policy for the bucket.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
To add or modify the soft delete policy on a bucket, use the
gcloud storage buckets update
command with the
--soft-delete-duration
flag:
gcloud storage buckets update gs://BUCKET_NAME --soft-delete-duration=SOFT_DELETE_DURATION
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.SOFT_DELETE_DURATION
specifies the duration to retain soft-deleted objects. For example,2w1d
is two weeks and one day. For more information, see soft delete retention duration.
To remove the soft delete policy from a bucket, use the
gcloud storage buckets update
command with the --clear-soft-delete
flag:
gcloud storage buckets update gs://BUCKET_NAME --clear-soft-delete
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Create a JSON file that contains the following information:
{ "softDeletePolicy": { "retentionDurationSeconds": "RETENTION_DURATION" } }
Where
RETENTION_DURATION
is the amount of time you want to retain soft-deleted objects for. For example,2w1d
retains soft-deleted objects for two weeks and one day. For more information, see soft delete retention duration.To disable the soft delete policy for a bucket, use the value
0
forRETENTION_DURATION
.Use
cURL
to call the JSON API with aPATCH
Bucket request: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"
Where:
JSON_FILE_NAME
is the path for the JSON file that you created in Step 2.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Check if the soft delete policy is enabled on a bucket
Console
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the list of buckets, click the name of the bucket whose soft delete policy you want to check.
Click the Protection tab.
The status displays in the Soft delete policy (for data recovery) section.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
To check the soft delete policy status of a bucket, use the
gcloud storage buckets describe
command:
gcloud storage buckets describe gs://BUCKET_NAME \ --format="default(soft_delete_policy)"
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.
REST APIs
JSON API
Have gcloud CLI installed and initialized, in order to generate an access token for the
Authorization
header.Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the
Authorization
header.Use
cURL
to call the JSON API with aGET
Bucket request:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=softDeletePolicy"
Where
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
What's next
- Learn more about soft delete.
- Learn how to use soft-deleted objects.