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. For more information about soft delete, see the Overview. To disable the feature, see Disable soft delete.
Required roles
To get the permissions that you need to create and manage soft delete policies,
ask your administrator to grant you the
Storage Admin (roles/storage.admin
) IAM role on the bucket or the project that contains the bucket.
This predefined role contains the permissions required to create and manage soft delete policies. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create and manage soft delete policies:
-
storage.buckets.get
-
storage.buckets.update
-
storage.buckets.list
(this permission is only required if you plan to use the Google Cloud console to perform the instructions on this page)
For information about granting roles, see Use IAM with buckets or Manage access to projects.
Edit a bucket's soft delete policy
To enable, disable, or update 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 doesn't have a soft delete policy, click Edit, 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 unit of time and length of time for your retention duration.
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.
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": "TIME_IN_SECONDS" } }
Where
TIME_IN_SECONDS
is the amount of time in seconds you want to retain soft-deleted objects for. For example,2678400
. For more information, see soft delete retention 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
.
Delete a bucket's soft delete policy
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 delete.
Click the Protection tab.
In the Soft delete policy section, click Disable to remove the soft delete policy for the bucket.
Click Confirm.
To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, see Troubleshooting.
Command line
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": "TIME_IN_SECONDS" } }
To disable the soft delete policy for a bucket, use the value
0
forTIME_IN_SECONDS
.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.
You can also use the Protection tab to check if there's a soft delete policy on your bucket.
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
.
Disable soft delete for multiple buckets or all buckets within a project
The following instructions describe how to disable soft delete for multiple or all buckets within a project. If you want to disable soft delete at the organization level, see Disable soft delete.
Console
The Google Cloud console lets you disable soft delete for buckets sorted by the most soft-deleted bytes or the highest ratio of soft-deleted bytes to live bytes, so you can lower costs incurred from using soft delete.
- In the Google Cloud console, go to the Cloud Storage Buckets page.
In the Cloud Storage page, click Settings.
Click the Soft delete tab.
From the Top buckets by deleted bytes list, select the buckets you want to disable soft delete for.
Click Turn off soft delete.
Soft delete is disabled on the buckets you selected.
Command line
To disable soft delete for all buckets within a project, run the
gcloud storage buckets update
command with the --clear-soft-delete
flag:
gcloud storage buckets update --clear-soft-delete gs://*
Client libraries
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.
Python
What's next
- Learn how to use soft-deleted objects.
- Learn how to disable soft delete.