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 until its hard delete time, and cannot be modified while in a soft-deleted state. The hard delete time is at least as long as the latest hard delete time of the bucket's objects. After the hard delete time has elapsed, Cloud Storage permanently deletes the bucket. 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 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.
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.
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.
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.
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.