5c3f75ba6a
We can set x-versions-location empty to remove this header in API, but to keep consistent, we should allow x-remove-versions-location too. The usage is post "x-remove-versions-locaion: x", just like ACL remove headers. Fixed: bug #1107592 Change-Id: I1271eec6401d4a0e8c1a7c2d63aeb8dfef00bf6d
90 lines
3.5 KiB
ReStructuredText
90 lines
3.5 KiB
ReStructuredText
=================
|
|
Object Versioning
|
|
=================
|
|
|
|
--------
|
|
Overview
|
|
--------
|
|
|
|
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 hexidecimal 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.
|
|
|
|
Note: A large object manifest file cannot be versioned, but a large object
|
|
manifest may point to versioned segments.
|
|
|
|
--------------------------------------------------
|
|
How to Enable Object Versioning in a Swift Cluster
|
|
--------------------------------------------------
|
|
|
|
Set ``allow_versions`` to ``True`` in the container server config.
|
|
|
|
-----------------------
|
|
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_versions`` back to
|
|
``False`` in the container server config.
|
|
|
|
Disable versioning a versioned container (x is any value except empty)::
|
|
|
|
curl -i -HPOST -H "X-Auth-Token: <token>" \
|
|
-H "X-Remove-Versions-Location: x" http://<storage_url>/container
|