openstack/swift
Code Issues Proposed changes
Files
api-ref
bin
doc
manpages
s3api
saio
source
_extra
admin
api
authentication.rst
container_quotas.rst
discoverability.rst
form_post_middleware.rst
large_objects.rst
object_api_v1_overview.rst
object_versioning.rst
temporary_url_middleware.rst
use_content-encoding_metadata.rst
use_the_content-disposition_metadata.rst
images
install
ops_runbook
account.rst
admin_guide.rst
apache_deployment_guide.rst
associated_projects.rst
conf.py
container.rst
cors.rst
crossdomain.rst
db.rst
deployment_guide.rst
development_auth.rst
development_guidelines.rst
development_middleware.rst
development_ondisk_backends.rst
development_saio.rst
first_contribution_swift.rst
getting_started.rst
howto_installmultinode.rst
index.rst
logs.rst
middleware.rst
misc.rst
object.rst
overview_acl.rst
overview_architecture.rst
overview_auth.rst
overview_backing_store.rst
overview_container_sharding.rst
overview_container_sync.rst
overview_encryption.rst
overview_erasure_code.rst
overview_expiring_objects.rst
overview_global_cluster.rst
overview_large_objects.rst
overview_object_versioning.rst
overview_policies.rst
overview_reaper.rst
overview_replication.rst
overview_ring.rst
policies_saio.rst
proxy.rst
ratelimit.rst
replication_network.rst
ring.rst
ring_background.rst
ring_partpower.rst
s3_compat.rst
test-cors.html
requirements.txt
etc
examples
playbooks
releasenotes
swift
test
tools
.alltests
.coveragerc
.functests
.gitignore
.gitreview
.mailmap
.manpages
.probetests
.testr.conf
.unittests
.zuul.yaml
AUTHORS
CHANGELOG
CONTRIBUTING.rst
LICENSE
MANIFEST.in
README.rst
REVIEW_GUIDELINES.rst
babel.cfg
bandit.yaml
bindep.txt
requirements.txt
setup.cfg
setup.py
test-requirements.txt
tox.ini
a3cc7ccc69f6e6df4a54cb414aa844c59bed40b7
swift/doc/source/api/object_versioning.rst
Anh Tran 1c4a16a3f9 Typo fix: curent => current 
Change-Id: Ib7d2c16a755ae1faca5a371d5dae1e143110178f
2017-02-07 13:36:50 +07:00

12 KiB
Raw Blame History

Object versioning

You can store multiple versions of your content so that you can recover from unintended overwrites. Object versioning is an easy way to implement version control, which you can use with any type of content.

Note

You cannot version a large-object manifest file, but the large-object manifest file can point to versioned segments.

Note

It is strongly recommended that you put non-current objects in a different container than the container where current object versions reside.

To allow object versioning within a cluster, the cloud provider should add the versioned_writes filter to the pipeline and set the allow_versioned_writes option to true in the [filter:versioned_writes] section of the proxy-server configuration file.

To enable object versioning for a container, you must specify an "archive container" that will retain non-current versions via either the X-Versions-Location or X-History-Location header. These two headers enable two distinct modes of operation. Either mode may be used within a cluster, but only one mode may be active for any given container. You must UTF-8-encode and then URL-encode the container name before you include it in the header.

For both modes, PUT requests will archive any pre-existing objects before writing new data, and GET requests will serve the current version. COPY requests behave like a GET followed by a PUT; that is, if the copy source is in a versioned container then the current version will be copied, and if the copy destination is in a versioned container then any pre-existing object will be archived before writing new data.

If object versioning was enabled using X-History-Location, then object DELETE requests will copy the current version to the archive container then remove it from the versioned container.

If object versioning was enabled using X-Versions-Location, then object DELETE requests will restore the most-recent version from the archive container, overwriting the current version.

Example Using X-Versions-Location

  1. Create the current container:
# curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
X-Openstack-Request-Id: txb91810fb717347d09eec8-0052e18997
Date: Thu, 23 Jan 2014 21:28:55 GMT

  1. Create the first version of an object in the current container:

    # curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
    HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a
X-Openstack-Request-Id: tx5992d536a4bd4fec973aa-0052e18a2a
Date: Thu, 23 Jan 2014 21:31:22 GMT

    Nothing is written to the non-current version container when you initially PUT an object in the current container. However, subsequent PUT requests that edit an object trigger the creation of a version of that object in the archive container.

    These non-current versions are named as follows:

    <length><object_name>/<timestamp>

    Where length is the 3-character, zero-padded hexadecimal character length of the object, <object_name> is the object name, and <timestamp> is the time when the object was initially created as a current version.

  2. Create a second version of the object in the current container:

    # curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
    HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c
X-Openstack-Request-Id: tx468287ce4fc94eada96ec-0052e18c8c
Date: Thu, 23 Jan 2014 21:41:32 GMT

  3. Issue a GET request to a versioned object to get the current version of the object. You do not have to do any request redirects or metadata lookups.

    List older versions of the object in the archive container:

    # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"
    HTTP/1.1 200 OK
Content-Length: 30
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e
X-Openstack-Request-Id: tx9a441884997542d3a5868-0052e18d8e
Date: Thu, 23 Jan 2014 21:45:50 GMT

009my_object/1390512682.92052

    Note

    A POST request to a versioned object updates only the metadata for the object and does not create a new version of the object. New versions are created only when the content of the object changes.

  4. Issue a DELETE request to a versioned object to remove the current version of the object and replace it with the next-most current version in the non-current container.

    # curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token"
    HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
X-Openstack-Request-Id: tx006d944e02494e229b8ee-0052e18edd
Date: Thu, 23 Jan 2014 21:51:25 GMT

    List objects in the archive container to show that the archived object was moved back to the current container:

    # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"
    HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 0
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed
X-Openstack-Request-Id: tx044f2a05f56f4997af737-0052e18eed
Date: Thu, 23 Jan 2014 21:51:41 GMT

    This next-most current version carries with it any metadata last set on it. If want to completely remove an object and you have five versions of it, you must DELETE it five times.

Example Using X-History-Location

  1. Create the current container:
# curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-History-Location: archive"
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
X-Openstack-Request-Id: txb91810fb717347d09eec8-0052e18997
Date: Thu, 23 Jan 2014 21:28:55 GMT

  1. Create the first version of an object in the current container:

    # curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
    HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:31:22 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5992d536a4bd4fec973aa-0052e18a2a
X-Openstack-Request-Id: tx5992d536a4bd4fec973aa-0052e18a2a
Date: Thu, 23 Jan 2014 21:31:22 GMT

    Nothing is written to the non-current version container when you initially PUT an object in the current container. However, subsequent PUT requests that edit an object trigger the creation of a version of that object in the archive container.

    These non-current versions are named as follows:

    <length><object_name>/<timestamp>

    Where length is the 3-character, zero-padded hexadecimal character length of the object, <object_name> is the object name, and <timestamp> is the time when the object was initially created as a current version.

  2. Create a second version of the object in the current container:

    # curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
    HTTP/1.1 201 Created
Last-Modified: Thu, 23 Jan 2014 21:41:32 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx468287ce4fc94eada96ec-0052e18c8c
X-Openstack-Request-Id: tx468287ce4fc94eada96ec-0052e18c8c
Date: Thu, 23 Jan 2014 21:41:32 GMT

  3. Issue a GET request to a versioned object to get the current version of the object. You do not have to do any request redirects or metadata lookups.

    List older versions of the object in the archive container:

    # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"
    HTTP/1.1 200 OK
Content-Length: 30
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx9a441884997542d3a5868-0052e18d8e
X-Openstack-Request-Id: tx9a441884997542d3a5868-0052e18d8e
Date: Thu, 23 Jan 2014 21:45:50 GMT

009my_object/1390512682.92052

    Note

    A POST request to a versioned object updates only the metadata for the object and does not create a new version of the object. New versions are created only when the content of the object changes.

  4. Issue a DELETE request to a versioned object to copy the current version of the object to the archive container then delete it from the current container. Subsequent GET requests to the object in the current container will return 404 Not Found.

    # curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token"
    HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
X-Openstack-Request-Id: tx006d944e02494e229b8ee-0052e18edd
Date: Thu, 23 Jan 2014 21:51:25 GMT

    List older versions of the object in the archive container:

    .. code::

    # curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"

    HTTP/1.1 200 OK
Content-Length: 90
X-Container-Object-Count: 3
Accept-Ranges: bytes
X-Timestamp: 1390513280.79684
X-Container-Bytes-Used: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx044f2a05f56f4997af737-0052e18eed
X-Openstack-Request-Id: tx044f2a05f56f4997af737-0052e18eed
Date: Thu, 23 Jan 2014 21:51:41 GMT

009my_object/1390512682.92052
009my_object/1390512692.23062
009my_object/1390513885.67732

    In addition to the two previous versions of the object, the archive container has a "delete marker" to record when the object was deleted.

    To permanently delete a previous version, issue a DELETE to the version in the archive container.

Disabling Object Versioning

To disable object versioning for the current container, remove its X-Versions-Location metadata header by sending an empty key value.

# curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: "
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe2476de217134549996d0-0052e19038
X-Openstack-Request-Id: txe2476de217134549996d0-0052e19038
Date: Thu, 23 Jan 2014 21:57:12 GMT

<html><h1>Accepted</h1><p>The request is accepted for processing.</p></html>