Use soft delete

Overview Usage

This page describes how to enable, update, and check the status of the soft delete policy on a bucket. To learn how to list and restore soft-deleted objects, see Use soft-deleted objects. To list and restore soft-deleted buckets, see Use soft-deleted buckets. 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 enable 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 enable 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 enable 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

The new soft delete retention duration only applies to objects or buckets that you delete after the soft delete policy takes effect. Existing soft-deleted objects aren't affected by updates made to the soft delete policy and are retained for the duration that was in effect when they were deleted.

Use the following instructions to edit a bucket's soft delete policy:

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

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

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

  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.

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

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for 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