Swarm Versioning is an optional feature introduced in release 8.0; it is modelled on Amazon S3 Versioning to extend Gateway's support for S3.

Guidelines for Versioning

Review these guidelines before implementing versioning in your cluster:

• Plan for higher disk utilization with versioning: each update to a versioned object adds a new object to the cluster (one object updated twice results in three objects stored).

• Make use of lifepoints (Lifepoint Metadata Headers) to control the lifetime - and thus the cost of storing - multiple versions of your objects.

• For resource management, limit versioning to the specific domains and/or buckets for which it is needed.

• For best performance, enable the Overlay Index (Configuring the Overlay Index) on your cluster.

• When replicating between clusters that both enable versioning, avoid unnecessary updates to versioning policies: new policies cannot take effect in the remote cluster until the domain or bucket is replicated, which may take a while.

• Legal hold buckets cannot be versioning-enabled. If using legal hold, the ETag header value (which is the version identifier) needs to be used to hold a previous object version. 

• Upgrades: Versioning is integrated with Swarm and available on upgrade, but take these steps before enabling versioning:

  • Complete the upgrade of both the storage cluster (Upgrading a Storage Cluster) and the search cluster (Installing Elasticsearch).

  • If you are using Replication Feeds, upgrade both the source and target clusters to the same release of Swarm before enabling versioning.

Configuring Versioning

Versioning is one of several content protection features in Swarm, all are controlled by way of policies. Swarm evaluates policies for each object based on its cluster and context values:

• Policy-related settings for the cluster (required) 

• Policy-related headers on domain and bucket objects (optional)

For how to set policies at the cluster level, see Configuring Cluster Policies.

Context

The versioning state of a given object depends on its context:

• Alias Object: context = cluster + domain in which it is tenanted

• Named Object: context = cluster + domain + bucket

Policy 

Swarm uses the versioning policy (set via cluster settings and domain/bucket headers) to determine what versioning-related operations are allowed on each object. The versioning state of the immediate context applies to every object in that context, without exception. 

Each alias or named object has one of three versioning states: 

To implement versioning, you need to enable it by setting your versioning policy across all affected container objects, starting with the cluster:

• Cluster: set the configuration parameter policy.versioning. (This is a Persisted Settings (SNMP), so set it via SNMP.)

• Domain(s): set the domain object's Policy-Versioning and Policy-Versioning-Unnamed  header values. 

• Bucket(s): set the bucket object's Policy-Versioning header value.

Status Settings

The statuses for versioning vary by type of container object: 

You can verify versioning is enabled within a domain or bucket by making a HEAD request and checking the policy-related headers, Policy-Versioning[-Unnamed] (which you add) and Policy-Versioning[-Unnamed]-Evaluated (which Swarm generates). You control all Policy-Versioning[-Unnamed] headers, but Swarm computes and Policy-Versioning[-Unnamed]-Evaluated based on the policy of the complete context.

The versioning state of a domain depends on the cluster's state:

The versioning state of a bucket depends on the parent domain's state:

Managing Policies across Clusters

If you are using Replication Feeds while using versioning, both the source and target clusters must run the same release of Swarm, but you choose how versioning occurs in the target:

Policies are carried on contexts, and a remote cluster evaluates policies locally based on the contexts it currently holds. Rapid changes to policies in a source cluster with changing content in those domains and buckets returns the correct results, but when those changes are replicated to the target cluster, results may differ.