Versioning & Retention Policies

Object versioning and retention policies are two complementary data protection features in Cloud Storage. Versioning preserves historical copies of objects, while retention policies prevent objects from being deleted before a specified time. Together, they provide robust protection against accidental deletion, ransomware, and regulatory compliance requirements.

---

Object Versioning

When versioning is enabled on a bucket, Cloud Storage keeps every version of every object. Overwriting or deleting an object creates a non-current version instead of permanently removing the data.

Enabling Versioning

# Enable versioning
gsutil versioning set on gs://my-bucket

# Check versioning status
gsutil versioning get gs://my-bucket

How Versioning Works

Action	Result
Upload new object	Creates a live (current) version with a generation number
Overwrite object	Previous version becomes non-current; new version becomes live
Delete object	Live version becomes non-current (data is preserved)
Delete non-current version	Permanently removes that specific version

Generation Numbers

Every object version has a unique generation number (a timestamp-based integer). You can reference specific versions:

# List all versions of all objects
gsutil ls -a gs://my-bucket/

# Download a specific version
gsutil cp gs://my-bucket/report.csv#1234567890 ./report-old.csv

# Restore a non-current version by copying it
gsutil cp gs://my-bucket/report.csv#1234567890 gs://my-bucket/report.csv

Cost Impact

Non-current versions consume storage and are billed at the same rate as the object's storage class. Without lifecycle rules, versions accumulate indefinitely and can significantly increase costs.

Managing Versions with Lifecycle Rules

{
  "lifecycle": {
    "rule": [
      {
        "action": { "type": "Delete" },
        "condition": { "numNewerVersions": 3, "isLive": false }
      },
      {
        "action": { "type": "Delete" },
        "condition": { "daysSinceNoncurrentTime": 90, "isLive": false }
      }
    ]
  }
}

This keeps 3 non-current versions and deletes any non-current version older than 90 days.

---

Retention Policies

A retention policy sets a minimum retention period for objects in a bucket. While a retention policy is in effect, objects cannot be deleted or replaced until the retention period has elapsed.

Setting a Retention Policy

# Set a 90-day retention policy
gsutil retention set 90d gs://my-bucket

# Set a 7-year retention policy
gsutil retention set 2555d gs://my-bucket

# View retention policy
gsutil retention get gs://my-bucket

# Remove a retention policy (only if unlocked)
gsutil retention clear gs://my-bucket

How Retention Works