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.

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.

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