Object Versioning¶
Object versioning in swift is implemented by setting a flag on the container
to tell swift to version all objects in the container. The flag is the
X-Versions-Location
header on the container, and its value is the
container where the versions are stored. It is recommended to use a different
X-Versions-Location
container for each container that is being versioned.
When data is PUT
into a versioned container (a container with the
versioning flag turned on), the existing data in the file is redirected to a
new object and the data in the PUT
request is saved as the data for the
versioned object. The new object name (for the previous version) is
<versions_container>/<length><object_name>/<timestamp>
, where length
is the 3-character zero-padded hexadecimal length of the <object_name>
and
<timestamp>
is the timestamp of when the previous version was created.
A GET
to a versioned object will return the current version of the object
without having to do any request redirects or metadata lookups.
A POST
to a versioned object will update the object metadata as normal,
but will not create a new version of the object. In other words, new versions
are only created when the content of the object changes.
A DELETE
to a versioned object will only remove the current version of the
object. If you have 5 total versions of the object, you must delete the
object 5 times to completely remove the object.
How to Enable Object Versioning in a Swift Cluster¶
This middleware was written as an effort to refactor parts of the proxy server,
so this functionality was already available in previous releases and every
attempt was made to maintain backwards compatibility. To allow operators to
perform a seamless upgrade, it is not required to add the middleware to the
proxy pipeline and the flag allow_versions
in the container server
configuration files are still valid. In future releases, allow_versions
will be deprecated in favor of adding this middleware to the pipeline to enable
or disable the feature.
In case the middleware is added to the proxy pipeline, you must also
set allow_versioned_writes
to True
in the middleware options
to enable the information about this middleware to be returned in a /info
request.
Upgrade considerations: If allow_versioned_writes
is set in the filter
configuration, you can leave the allow_versions
flag in the container
server configuration files untouched. If you decide to disable or remove the
allow_versions
flag, you must re-set any existing containers that had
the ‘X-Versions-Location’ flag configured so that it can now be tracked by the
versioned_writes middleware.
Examples Using curl
¶
First, create a container with the X-Versions-Location
header or add the
header to an existing container. Also make sure the container referenced by
the X-Versions-Location
exists. In this example, the name of that
container is “versions”:
curl -i -XPUT -H "X-Auth-Token: <token>" -H "X-Versions-Location: versions" http://<storage_url>/container
curl -i -XPUT -H "X-Auth-Token: <token>" http://<storage_url>/versions
Create an object (the first version):
curl -i -XPUT --data-binary 1 -H "X-Auth-Token: <token>" http://<storage_url>/container/myobject
Now create a new version of that object:
curl -i -XPUT --data-binary 2 -H "X-Auth-Token: <token>" http://<storage_url>/container/myobject
See a listing of the older versions of the object:
curl -i -H "X-Auth-Token: <token>" http://<storage_url>/versions?prefix=008myobject/
Now delete the current version of the object and see that the older version is gone:
curl -i -XDELETE -H "X-Auth-Token: <token>" http://<storage_url>/container/myobject
curl -i -H "X-Auth-Token: <token>" http://<storage_url>/versions?prefix=008myobject/
How to Disable Object Versioning in a Swift Cluster¶
If you want to disable all functionality, set allow_versioned_writes
to
False
in the middleware options.
Disable versioning from a container (x is any value except empty):
curl -i -XPOST -H "X-Auth-Token: <token>" -H "X-Remove-Versions-Location: x" http://<storage_url>/container