Google Cloud Storage: Bucket Lock, retention policies and soft delete for backup

About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.

Use a retention policy to stop backup objects being deleted or replaced before a set age. Lock that policy only after testing, because a lock cannot be undone. Keep soft delete on as well, because it recovers objects deleted after retention ends or in buckets with no retention at all.

The three controls answer different questions. Retention asks whether this object may be deleted yet. The lock asks whether anyone may weaken that rule. Soft delete asks whether a deleted object can come back.

Commands below come from Google's documentation or were written for this article where labelled. None was run in a lab.

Why it matters

Backups are only useful if they survive whoever or whatever is deleting data. That includes a faulty script, a mistaken retention change and a stolen administrator credential.

Each control covers part of that risk, and each has a gap. An unlocked retention policy can be removed by someone with permission to update the bucket. Soft delete can be switched off for future deletions. A lock is permanent, so a wrong period becomes a long and costly mistake.

How the controls differ

Google recommends soft delete rather than Object Versioning to protect against accidental or malicious deletion, partly because versioning does not protect against bucket-level events.

How a retention policy works

An object in a bucket with a policy can be deleted or replaced only once its age exceeds the period. Earlier attempts fail with 403 - retentionPolicyNotMet.

The details matter for backup software:

• It is retroactive. The policy applies to objects already in the bucket, using their existing age. Adding a one-year policy does not restart the clock on an object already two years old, so that object can be deleted at once.
• Replacing resets age. A new object written over an old name starts again at zero.
• Units are fixed conversions. In the console and gcloud, a month is 31 days and a year is 365.25 days. The maximum is 3,155,760,000 seconds, or 100 years.
• Metadata is not protected. An object's editable metadata can change even while the object cannot be deleted.
• Parallel composite uploads should be avoided. Google says not to use them on a retention bucket, because component pieces cannot be deleted until each meets the period.
• XML API multipart completion fails if the result would overwrite an object still under retention.
• Versioned buckets need a test. The Bucket Lock page says a live object under retention can still be made noncurrent. The JSON API reference describes retained objects as ones that cannot be made noncurrent. Confirm the behaviour before relying on either.

Lifecycle rules still work on a locked bucket. A Delete action waits until holds are gone and retention is met, then proceeds if its conditions are still true.

What a lock adds

Locking is irreversible. Trying to remove or shorten a locked policy returns a 400 BadRequestException. The bucket cannot be deleted until every object in it has met the period.

Locking also places a lien on the project, which blocks project deletion. A Project Owner or Organization Administrator can remove a lien. So the lien is a guard against casual deletion, not a barrier to the most privileged account. Google's control for that gap is about people: whoever is tasked with removing the lien should have legal or compliance accountability and sit outside the IT department's accountability chain.

For customer-managed encryption, a key version cannot be destroyed while it encrypts a locked object that has not met its retention time or still has a hold.

How soft delete works

Soft delete is on by default for buckets that support it, with a 7-day duration. You can set 7 to 90 days, or 0 to turn it off.

While soft-deleted, a resource cannot be read, modified or overwritten, and it cannot be permanently deleted until its duration ends. The only operations are listing and restoring.

Five behaviours catch people out:

1. Duration is fixed at deletion. A change applies only to resources deleted afterwards. The change takes up to 30 seconds to propagate.
2. Disabling affects later deletions. Objects already soft-deleted stay until their previous duration expires. Google warns that once soft delete is off, deleted data cannot be recovered.
3. Restores land in Standard. Every restored object is written to Standard, whatever its original class.
4. Restores can overwrite. If a live object has the same name, the restored copy replaces it and the former live object becomes soft-deleted.
5. Not everything is covered. XML API multipart parts have no soft delete, and managed folder IAM policies are not restored.

Retention and soft delete stack. Google says the lock features stop deletion until retention is met, and soft delete then retains the deleted object for its own duration.

Object-level controls

Object Retention Lock sets a retain-until time per object. It suits data with different periods in one bucket. A new bucket needs --enable-per-object-retention, existing buckets can enable it only in the console, and it cannot be disabled. If an object also has a bucket policy, both must be satisfied.

Holds stop deletion regardless of age. Releasing an event-based hold resets the object's time in the bucket for retention purposes. A temporary hold does not. Holds are not supported on buckets with hierarchical namespace, and an object cannot have both an event-based hold and its own retention configuration.

Size retention for the backup chain

This section is editorial. The arithmetic is for this article.

Retention counts from each object's creation, but a restore depends on the whole chain. Consider weekly fulls and daily incrementals, with a promise of 30 days of restore points.

• The full from day 0 is needed by the incrementals up to day 6.
• The day 6 restore point must stay until day 36.
• So the full must survive to at least day 36, not day 30.

A 30-day policy would allow the full to go while later restore points still need it. Set the minimum at promised retention plus the longest chain length, then add margin for a missed full. For this example: 30 + 6 = 36 days, or 3,110,400 seconds.

Check three more things before you fix a number:

• Does the backup software rewrite or merge objects? Synthetic fulls, compaction and catalogue updates can hit retentionPolicyNotMet. Ask the vendor how it behaves on immutable storage.
• Does it use parallel composite or XML multipart uploads? Both have the constraints above.
• Is the storage class compatible? Coldline has a 90-day minimum and Archive 365 days. Deleting earlier is charged as if stored for the minimum. Time spent noncurrent or soft-deleted counts towards that minimum.

A safe order of steps

1. Separate duties

Put backups in their own project where you can. Give the backup writer Storage Object Creator, which creates objects but does not view, delete or overwrite them. If the software needs to read or delete, grant only what its vendor documents.

Keep storage.buckets.update away from the backup service account. That permission changes bucket metadata, and Google's soft delete and retention commands depend on it. A separate recovery role should hold what restoring needs: storage.objects.restore and storage.objects.create, storage.objects.delete when a restore overwrites existing objects, and storage.buckets.restore for bulk restores. Pausing or resuming hard deletions needs storage.buckets.update, so the recovery role must hold that permission too.

2. Create the bucket with an unlocked policy

This command was written for this article from the create reference. Google's own duration examples include 1d43200s and P1Y1M1DT5S, and 36d is written here in the first form:

gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION \
  --uniform-bucket-level-access --retention-period=36d \
  --soft-delete-duration=30d

To add a policy to an existing bucket, Google's command is:

gcloud storage buckets update gs://BUCKET_NAME --retention-period=36d

3. Check what was set

gcloud storage buckets describe gs://BUCKET_NAME --format="default(retention_policy)"
gcloud storage buckets describe gs://BUCKET_NAME --format="default(soft_delete_policy)"

Google's sample shows retentionPeriod in seconds and an effectiveTime. A result of null means no policy exists. The bucket resource has a retentionPolicy.isLocked field, which is the one to check after a lock. Each object also carries retention expiration time metadata.

4. Test on a disposable object

Run real backup jobs against the unlocked bucket for at least one full chain. Then try to delete a test object you created for this purpose. This is written for this article:

Use a disposable test object and a reviewed rehearsal procedure. Record the expected refusal, the object identity and its retention expiration; no deletion command is supplied here.

The expected protection result is refusal with retentionPolicyNotMet. Then prove a restore from the bucket, not just that the objects exist.

5. Lock only when the period is proven

Warning: This is permanent. The policy can never be removed or shortened, and the bucket cannot be deleted until every object has met the period. Confirm the bucket name, the period and the cost at that period first.

The bucket owner must approve the irreversible lock after a qualified review of the tested backup chain, retention obligation, existing object ages and full-period cost. Follow the current vendor procedure within that approved plan; this article provides no executable lock instruction.

6. Control the settings across the organisation

Organisation policy constraints can require allowed durations: constraints/storage.retentionPolicySeconds and constraints/storage.softDeletePolicySeconds. Google recommends setting inheritFromParent to true. Both apply when a bucket is created or that setting is updated.

Watch changes as well. Admin Activity audit logs record operations that change configuration or metadata. They are on by default and cannot be disabled. Data Access audit logs, which include the DATA_WRITE sub-type for changes to stored data, are off until you enable them.

Plan recovery after mass deletion

Google’s recommended order is to restore the bucket if needed, pause hard deletions, restore objects, validate and then resume. This is an operation that can replace live data and later release permanently expired data. The exact procedure needs qualified review and an isolated rehearsal; it is not a command sequence supplied by this source-only article.

Begin with read-only inventory. For a deleted bucket, list its generation and retention evidence:

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

The bucket recovery guidance says a gcloud bucket restore initially returns an empty bucket. Objects need a separate restore. A live bucket using the same name blocks restoration, so an owner must resolve that collision without deleting current data merely to satisfy the example.

The hard-deletion pause preserves soft-deleted objects indefinitely while enabled. Pause and resume are limited to once in 24 hours. Storage charges continue, and resuming permanently deletes objects already beyond their duration. A recovery plan therefore needs a named decision owner and a validation deadline before any resume action.

For the object set, record bucket and generation identities, the incident interval, expected clean versions and any currently live objects with the same names. The gcloud restore reference provides deletion-time filters and a combined created/deleted-time example for erroneous overwrites. Those filters narrow candidates; they do not prove a selected version is clean. Match the selection to the backup catalogue and application integrity evidence.

Overwriting is a separate decision. Google’s concept page describes restoration replacing a live object, while the bulk API and CLI expose an explicit overwrite option. Confirm the behaviour of the exact interface in a disposable bucket before approving the production selection. Preserve current live data and document conflicts; no bulk restore or overwrite command is supplied here.

Bulk work can take an hour or more to begin. Retain the operation ID, final outcome, exact selected generations and validation results. A completed storage restore is only one gate: prove the backup chain and an application restore before accepting recovery or allowing deferred deletions to resume.

What to choose and why

These are editorial recommendations.

Risks and limits

Warning: Disabling soft delete makes later deletions permanent, and a lock cannot be reversed. Change neither on a production backup bucket without a recorded decision.

• Soft delete has a real storage cost. Soft-deleted objects are charged until permanently deleted. At steady state, 2 TiB deleted a day with 30 days of soft delete keeps about 60 TiB extra. That figure is arithmetic for this article.
• Paused hard deletion costs continue with no end date until you resume.
• Project deletion is a separate risk. A bucket with soft delete is kept for the soft delete duration or the project recovery window, whichever is shorter. Buckets without soft delete might be deleted immediately and might not be restorable.
• Account standing limits immutability. Google says that to maintain retention policies and object holds, you must keep your account active and in good standing, and must transfer your data to another compliant service before discontinuing the account. The page gives no deletion timeline, so check the agreement terms.
• Compliance is not automatic. Google says Bucket Lock with Detailed audit logging mode can help with FINRA, SEC and CFTC requirements. Those are United States rules. Take advice on Australian obligations.
• Immutability is not recoverability. A locked object can hold corrupted or already-encrypted data. Test restores.
• One copy is still one copy. These controls work inside one bucket and one provider account. Consider a second location under separate administration.
• Pricing not reviewed. No storage prices are given.
• Not tested here. All behaviour comes from Google documentation opened on 10 November 2026. No command was run.

Sources

Opened 10 November 2026. Sources behind the corrections reopened 10 November 2026.

• Bucket Lock
• Use and lock retention policies
• Soft delete overview
• Set and manage soft delete policies
• Use soft-deleted objects
• Use soft-deleted buckets
• Disable soft delete
• Pause hard deletions
• Object Retention Lock
• Object holds
• Object Versioning
• Object Lifecycle Management
• Storage classes
• Cloud Storage pricing
• IAM roles for Cloud Storage
• IAM permissions for Cloud Storage
• Organisation policy constraints
• Cloud Audit Logs with Cloud Storage
• Customer-managed encryption keys
• Buckets resource, JSON API
• Protect projects with liens
• gcloud storage buckets create
• gcloud storage buckets update
• gcloud storage restore

This article was originally published on 10 November 2026.