Object Versioning

Go to examples

To support the retrieval of objects that are deleted or replaced, Cloud Storage offers the Object Versioning feature. This page describes the feature and the options available when using it.

Caution: Objects cannot be recovered from a deleted bucket, even if the bucket used Object Versioning.

Introduction

You enable Object Versioning for a bucket. Once enabled:

• Cloud Storage retains a noncurrent object version each time you replace or delete a live object version, as long as you do not specify the generation number of the live version.

  • Noncurrent versions retain the name of the object, but are uniquely identified by their generation number.

  • Noncurrent versions only appear in requests that explicitly call for them to be included.

• You permanently delete versions of objects by including the generation number in the deletion request or by using Object Lifecycle Management.

  Caution: Specifying the generation number in a deletion request permanently deletes the version, even if the version is live.

• Noncurrent versions of objects exist independently of any live version.

If you disable Object Versioning:

• The bucket no longer accumulates new noncurrent versions of objects.

• Object versions that already exist in the bucket are unaffected.

Important: If you change the versioning configuration for a bucket, the change may take time to propagate, and object deletions or replacements in the bucket may behave according to the previous setting for a short period of time. In order to ensure object deletions and replacements behave according to your change, wait at least 30 seconds between changing the versioning configuration and deleting or replacing objects.

Considerations

• Object Versioning cannot be enabled on a bucket that currently has a retention policy.

• There is no default limit on the number of object versions you can have. Each noncurrent version of an object is charged at the same rate it was when it was live.

  • Early deletion charges apply only when an object version is removed from the bucket, not when the version becomes noncurrent. The storage duration for a version removed from a bucket is based on the time it was added to the bucket, not the time it became noncurrent.

  • If you enable versioning, consider using Object Lifecycle Management, which can remove older versions of an object after a specified length of time or as newer versions become noncurrent. For one possible setup, see the lifecycle configuration example for deleting objects.

Noncurrent object metadata

Noncurrent versions of objects have their own metadata, which may differ from the metadata of the live version. Most importantly, a noncurrent version retains its ACLs and does not necessarily have the same permissions as the live version.

Each version, whether live or noncurrent, has one set of metadata; only the latest metageneration number refers to metadata. Older metageneration numbers cannot be used to access metadata that has since been changed.

You can update metadata for a noncurrent version of an object by specifying its generation in your request. To ensure safe read-modify-write semantics, you can use a metageneration-match precondition. Using this precondition causes the update to fail if the metadata you are attempting to update was changed between the time you read the metadata and sent the update.

Object Versioning example

This example shows what happens to the file cat.jpg in a bucket with Object Versioning enabled as you replace, update, and delete the file.

You upload a new image

When you first upload cat.jpg to Cloud Storage, it receives a generation number and a metageneration number. In this example, the generation number is 1360887697105000. Because the object is new, the metageneration number is 1.

cat.jpg receives generation and metageneration numbers even though Object Versioning is not enabled. You can view these numbers by using the stat command in gsutil. For instructions, see viewing the object metadata.

You enable Object Versioning

At this point, you decide to enable Object Versioning for your bucket. Doing so does not affect the generation or metageneration numbers of cat.jpg.

You change the metadata of the image

You update the metadata for cat.jpg by adding custom metadata: color:black. Updating metadata causes the metageneration value of cat.jpg to increase, in this case from 1 to 2. However, the object itself remains unchanged, so Cloud Storage continues to store only one version of cat.jpg, and the version continues to have a generation number of 1360887697105000.

You upload a new version of the image

You upload a new version of cat.jpg to your Cloud Storage bucket. When you do so, Object Versioning moves the existing cat.jpg object into a noncurrent state. The noncurrent version retains the same storage class and metadata it previously had. The noncurrent version appears only if you perform a versioned listing: it does not appear in normal listing commands. The noncurrent version is now referenced as: cat.jpg#1360887697105000.

Meanwhile, the newly uploaded cat.jpg becomes the live version of the object. This new cat.jpg gets its own generation number, in this example 1360887759327000. It also gets its own metadata and a metageneration number of 1, which means it does not contain the color:black metadata unless you specify it. When you access or modify cat.jpg, this is the version that is used. You can alternatively refer to this version of cat.jpg using its generation number. For example, when using the gsutil tool you would refer to it as cat.jpg#1360887759327000.

You delete the live version of the image

You now delete cat.jpg. When you do this, the version that had generation number 1360887759327000 becomes noncurrent. Your bucket now contains two noncurrent versions of cat.jpg and no live versions. You can still refer to either noncurrent version by using its generation number, but if you try to access cat.jpg without a generation number, it fails.

Similarly, a normal object listing of the bucket will not show cat.jpg as one of the objects in the bucket. For information on listing noncurrent versions of objects, see Listing noncurrent object versions.

You disable Object Versioning

You disable Object Versioning, which stops objects from becoming noncurrent. Existing noncurrent versions of objects remain in Cloud Storage. Even though Object Versioning is disabled, cat.jpg#1360887697105000 and cat.jpg#1360887759327000 remain stored in your bucket until you delete them, either manually or through using Object Lifecycle Management.

You restore one of the noncurrent versions

Even with Object Versioning disabled, you can make a copy of one of the existing noncurrent versions, which effectively restores the version. Once you do this, your bucket has three versions of cat.jpg: the two noncurrent versions and the live version that came from restoring.

Object Versioning reference

This reference table shows what happens when you take certain actions with Object Versioning.

Object Versioning Status	Action	Result
Disabled
	Replace dog.png with a new version.	The new version replaces the live version and receives a new generation number. The old live version is permanently deleted.
	Copy a noncurrent version of dog.png over the live version.^1	A copy of the noncurrent version replaces the live version and receives a new generation number. The old live version is permanently deleted.
	Delete dog.png.	dog.png is permanently deleted.
	Delete a noncurrent version of dog.png by specifying its generation number.^1	The noncurrent version is permanently deleted.
Enabled
	Replace dog.png with a new version.	The new version replaces the live version and receives a new generation number. The old live version becomes a noncurrent version and keeps the same generation number.
	Copy a noncurrent version of dog.png over the live version.	A copy of the noncurrent version replaces the live version and receives a new generation number. The old live version becomes a noncurrent version and keeps the same generation number.
	Delete the live version of dog.png without specifying its generation number.	The live version becomes a noncurrent version and keeps the same generation number.
	Delete the live version of dog.png by specifying its generation number.	The live version is permanently deleted.
	Delete a noncurrent version of dog.png by specifying its generation number.	The noncurrent version is permanently deleted.

¹ A noncurrent version might exist if the bucket had Object Versioning enabled previously.

File restoration behavior

You can effectively restore a noncurrent object version to the current live version. See Restoring noncurrent object versions for a step-by-step guide to doing so.

When you do this with Object Versioning enabled, if there already exists a live version of the object in your bucket, Cloud Storage replaces the existing live version but also retains it as a new noncurrent version. In such a case, your bucket subsequently contains the replaced object (now noncurrent) and two copies of the object that was previously noncurrent (one live copy and one still-noncurrent copy), all of which incur storage charges. To prevent unnecessary charges, delete the noncurrent version that you used to make the current live copy, or configure Object Lifecycyle Management to remove noncurrent objects when they meet the conditions you specify.

What's next

• Learn how to enable Object Versioning.
• Work with noncurrent objects.
• Learn about the generation and metageneration object properties.
• Learn about Object Lifecycle Management, which allows you to automatically manage object versions.
• See an Object Lifecycle Management example that works with Object Versioning.