Pause permanent (hard) deletions of soft-deleted objects

If you need more time to restore soft-deleted objects before they're permanently deleted, you can pause permanent deletions (also called hard deletions) of soft-deleted objects in a Cloud Storage bucket.

By default, soft-deleted objects and buckets are permanently deleted when they reach their soft delete retention duration. When you pause hard deletions for a bucket, soft-deleted objects are instead retained in a soft-deleted state indefinitely, regardless of their soft delete retention durations. Soft-deleted objects are only permanently deleted after you resume hard deletions for the bucket.

Use cases

Pausing hard deletions gives you extra time to perform very large or complicated object restorations that otherwise might take more time to resolve than the soft delete retention duration. For example:

  • Recovering very large buckets containing billions of objects. If a bucket contains a very large number of objects, it might take longer than the retention duration to recover all objects in the bucket, especially if you detect the deletion after part of the retention period has already passed. Pausing hard deletions can help you recover from an unexpected mass deletion incident, without having to set a longer retention duration for day-to-day operations.
  • Unclear scope of deletions. If you aren't sure which objects were incorrectly deleted, it might take time to investigate. Pausing hard deletions can give you more time to figure out what needs to be restored.
  • Complex recoveries. For complex restorations, there might be time to detect and perform a bulk recovery within the retention duration. If that doesn't yield the expected results, pausing hard deletions can give you more time to validate that you are satisfied with your state of recovery.

We recommend the following workflow to temporarily pause hard deletions for a bucket:

  1. When you detect a mass deletion incident that might take more time to resolve than the soft delete retention duration, then pause hard deletions for the affected bucket.

  2. Restore the bucket if necessary, and restore the objects in the bucket.

  3. After you complete the recovery and validate that your data was successfully restored, then resume hard deletions for the bucket.

Considerations

  • You can pause hard deletions for a bucket by updating an existing bucket that has soft delete enabled. Hard deletions can't be paused during bucket creation or for buckets that don't have soft delete enabled.
  • When you resume hard deletions for a bucket, Cloud Storage resumes permanent deletions of all soft-deleted objects in the bucket based on their soft delete retention durations. If any objects have passed their retention duration, they're permanently deleted when you resume hard deletions.
  • Pausing hard deletions takes effect immediately. It might take a few seconds for cached API operations to return updated information.
  • You can continue to delete objects in a bucket when hard deletions are paused. Deleted objects become soft-deleted.
  • You can pause and resume hard deletions on a bucket a maximum of once every 24 hours.
  • You can update the soft delete retention duration while hard deletions are paused. However, you can't disable soft delete while hard deletions are paused.
  • A bucket can't be deleted while hard deletions are paused.

Required roles

To get the permissions that you need to pause or resume hard deletions, 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 pause or resume hard deletions. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to pause or resume hard deletions:

  • storage.buckets.update
  • If you use the Google Cloud console to do the tasks on this page:
    • storage.buckets.get
    • storage.buckets.list

For information about granting roles, see Set and manage IAM policies on buckets or Manage access to projects.

Pause hard deletions

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": {
    "hardDeletePause": {
      "enabled": true
    }
  }
}

  3. To pause hard deletions for a bucket, 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"

    Replace the following:

    • JSON_FILE_NAME: the path to the JSON file that you created in the previous step.
    • BUCKET_NAME: the name of the bucket. For example, my-bucket.

Resume hard deletions

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": {
    "hardDeletePause": {
      "enabled": false
    }
  }
}

  3. To resume hard deletions for a bucket, 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"

    Replace the following:

    • JSON_FILE_NAME: the path to the JSON file that you created in the previous step.
    • BUCKET_NAME: the name of the bucket. For example, my-bucket.

Check whether hard deletions are paused for a bucket

A bucket's soft delete policy provides information about whether hard deletions are paused. For steps to retrieve a bucket's soft delete policy, see Check whether soft delete is enabled on a bucket.

What's next