Object Versioning

Object versioning is a feature enabled on the bucket level that automatically preserves all previous versions of every object.

Any change to an S3 object is an overwrite that replaces the object with a new one. With versioning enabled, the replaced object is not deleted; it is stored with a unique version number. You can always access any previous version of any object.

If the bucket's view is accessible via other protocols, those protocols have read-only access to the versioned objects.

S3 versioned objects are stored as numbered files under a version directory per object.

Limitations

When versioning is enabled on a bucket, it cannot be disabled.
Multiprotocol access to versioned objects is not supported. NFS and SMB clients may attempt to access the S3 versioned objects in read-only mode.
MFA Delete is not supported. MFA Delete is an optional configuration that requires multi-factor authentication of the bucket owner for any request to delete a version or change the versioning state of the bucket.
Copy objects from before VAST 4.0 cannot be used as copy sources and cannot be overwritten. The only way to modify a pre-v4.0 copy object is to copy the object onto itself.

Enabling Versioning

Caution
VAST Cluster does not support disabling (suspending) versioning on a bucket. The versioning of a bucket can only be enabled and remain enabled.

You can enable versioning via VMS or via S3 RPC.

Versioning can be enabled on a bucket when you create the bucket via VMS by creating It is possible to enable object versioning via VMS when creating a bucket using the S3 Bucket protocol option in the view creation flow. Otherwise, versioning can be enabled via RPC.

Enabling Versioning in VAST Web UI

For an existing view with an S3 bucket:

On the Views page, open the Actions menu for the view and select Edit. In the Update View dialog, on the S3 tab, enable the S3 Versioning setting and then click Update to save your change.

When creating a new view:

When you create the view, in the Create View dialog, enable the S3 Versioning setting on the S3 tab. The S3 Bucket protocol must be selected already in the Protocols dropdown before you can select the S3 tab.

Enabling Versioning in VAST CLI

For an existing view with an S3 bucket:

Run the view modify command with the --s3-versioning parameter.

For example, this command enables versioning on a bucket whose view has ID 32:

$ view modify --id 32 --s3-versioning

When creating a new view:

Include the --s3-versioning parameter when running the view create command to create the view.

Enabling Versioning with an S3 Command

Invoke the PutBucketVersioning S3 command to set the versioning state to Enabled.

Note
The Suspended state is not supported.

Other Versioning Commands

The following commands are supported:

GetBucketVersioning. Returns information on the state of the bucket's versioning.
ListObjectsVersions. Retrieves metadata about the versions of all the objects in a bucket.

Working with Versioned Objects

Uploading Objects with Versioning

When you upload an object to a version-enabled bucket, a unique version ID is automatically added to the object .

Listing Versioned Objects

Each version of the object is stored as '<object-name>/<version-number>' where <object-name> is the object key and <version-number> is the version number. When listing objects, the S3 service returns objects in ascending order. Newer versions of objects have lower numbers than older versions, so the latest version is listed first.

To list all versions of a given object, send a GET Bucket request to list the object's version directory. Specify the directory by setting the prefix parameter to the object key.

Retrieving a Versioned Object

A simple GET Object request retrieves the current version of an object.

To retrieve a specific version, you need to specify its version ID. Set the versionId to the ID of the version of the object you want to retrieve and send a GET Object versionId request.

Retrieving the metadata of a versioned object

A simple HEAD Object request retrieves metadata of the current version of an object.

To retrieve the metadata of a specific version of an object, send a HEAD Object versionId request, specifying the version ID of the object you want to retrieve.

Deleting a Versioned Object

A DeleteObject request for a versioned object does not delete it. It leaves previous versions of the object in the object version directory and creates a delete marker. A delete marker is an object that indicates that the object has been deleted. It has a key name (or key) and version ID like any other object but it is otherwise not a regular object: It does not have data associated with it nor does it have an access control list (ACL). It is not retrieved in a GET Object request or returned in a GET Bucket request.

You can delete the delete marker by sending a DeleteObject versionId request with the delete marker's version ID. This has the effect of undoing the object deletion.

To delete multiple versions of a versioned object, send a DeleteObjects request with an array of object identifiers (key, versionid).

Restoring a versioned object

The following operations restore a previous version of an object:

Copy the version that you want to restore into the same bucket. The copied object becomes the current version of that object and all object versions are preserved.
Permanently delete the current version of the object. The previous version automatically becomes the current version.