Use soft-deleted buckets

This page describes how to list and restore a soft-deleted bucket.

Overview

After a bucket is soft-deleted, it's retained by Cloud Storage for its soft delete retention duration, and cannot be modified while in a soft-deleted state. After the soft delete retention duration ends, Cloud Storage permanently deletes the bucket and its objects. Buckets with the soft delete feature enabled at time of deletion can be restored within their soft delete retention duration. When you restore a soft-deleted bucket, it is returned to a live state, and objects that were in the bucket at the time of deletion can also be restored.

Considerations

To restore a soft-deleted bucket, you must have the bucket's generation number. To retrieve a soft-deleted bucket's generation number, see List soft-deleted buckets.
Bucket restore operations don't restore the soft-deleted objects that were in the bucket at the time of deletion. To restore soft-deleted objects after the soft-deleted bucket has been restored, you'll need to perform an object restore operation.
To protect against malicious deletion, a soft-deleted bucket cannot be permanently deleted until the bucket has been retained for its full soft delete retention duration.
Once a bucket is a soft-deleted, you must restore the bucket before you can list or restore the soft-deleted objects in it.
A soft-deleted bucket can only be restored if there is no live bucket with the same name. If you or anyone else creates a bucket with the same name as a soft-deleted bucket, you cannot restore the soft-deleted bucket until the new bucket is deleted.
You cannot restore soft-deleted buckets with hierarchical namespace enabled.
Tag bindings might not be recovered when you restore a soft-deleted bucket with tags. To avoid data loss, when you restore a soft-deleted bucket with tag bindings, we recommend checking to ensure the bucket's tag bindings were recovered. If the bucket's tag bindings weren't recovered, you'll need to manually bind the unrecovered tags to the bucket.

Required permissions

To get the permissions that you need to restore soft-deleted buckets, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the Cloud Storage project.

This predefined role contains the permissions required to restore soft-deleted buckets. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to restore soft-deleted buckets:

storage.buckets.list
storage.buckets.restore

List soft-deleted buckets

You can perform list operations to retrieve your soft-deleted buckets' metadata.

Use the following instructions to list all soft-deleted buckets in your project:

Command line

To list all soft-deleted buckets, use the gcloud storage ls command:

gcloud storage ls --buckets --soft-deleted --full

REST APIs

JSON API

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

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?softDeleted=true"

Restore a soft-deleted bucket

Use the following instructions to restore a soft-deleted bucket:

Command line

To restore a soft-deleted bucket, use the gcloud storage restore command:

     gcloud storage restore gs://BUCKET_NAME#GENERATION_NUMBER

Replace the following:

BUCKET_NAME: the name of the soft-deleted bucket you want to restore.
GENERATION_NUMBER: the permanent, unique generation number of the soft-deleted bucket you want to restore. To get your bucket's generation number, see List soft-deleted buckets.

REST APIs

JSON API

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

Use cURL to call the JSON API with a POST Bucket request:
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/restore?generation=GENERATION_NUMBER
```
Where:
- BUCKET_NAME is the name of the bucket you want to restore. For example, my-bucket.
- GENERATION_NUMBER is the permanent, unique generation number of the soft-deleted bucket you want to restore. To get your bucket's generation number, see List soft-deleted buckets.

Cloud Storage restores the soft-deleted bucket to a live state. Note that restoring the bucket doesn't restore the objects that were in the bucket at the time of soft deletion. To restore the soft-deleted objects that were in the bucket at the time of deletion, see Restore a soft-deleted object.

What's next

Restore soft-deleted objects in your bucket.