Use soft delete

Overview Usage

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

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket whose soft delete policy you want to manage.

  3. Click the Protection tab.

  4. 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

  1. 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.

  2. 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 for RETENTION_DURATION.

  3. Use cURL to call the JSON API with a PATCH 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

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets

  2. In the list of buckets, click the name of the bucket whose soft delete policy you want to check.

  3. 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

  1. 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.

  2. Use cURL to call the JSON API with a GET 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