openstack/openstack-manuals
Code Issues Proposed changes

Adds swift object versioning to End User Guide

Browse Source 
With the moving of the Object Storage API content from a
long-form dev guide to a specification, some topics needed
To be added to the End User Guide.

Change-Id: I2b6179bec34e1ebaa7f4678f43f69385691c615b
Partial-bug: 1392382
This commit is contained in:
Erik Wilson 2014-12-10 16:17:27 -06:00 committed by Anne Gentle
parent dbc0080f10
commit 042d662c58
3 changed files with 183 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/common/entities/openstack.ent
View File

@ -9,6 +9,14 @@
<!ENTITY times "&#215;"> <!ENTITY times "&#215;">
<!ENTITY hellip "&#133;"> <!ENTITY hellip "&#133;">
<!-- Useful for describing APIs in the User Guide -->
<!ENTITY COPY '<command xmlns="http://docbook.org/ns/docbook">COPY</command>'>
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY HEAD '<command xmlns="http://docbook.org/ns/docbook">HEAD</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook"> <!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject> <imageobject>
<imagedata fileref="../common/figures/Check_mark_23x20_02.svg" <imagedata fileref="../common/figures/Check_mark_23x20_02.svg"

7
doc/user-guide/section_cli_swift_howto.xml
View File

@ -26,7 +26,7 @@
container.</para> container.</para>
<screen><prompt>$</prompt> <userinput>swift post <replaceable>CONTAINER</replaceable></userinput></screen></listitem> <screen><prompt>$</prompt> <userinput>swift post <replaceable>CONTAINER</replaceable></userinput></screen></listitem>
<listitem> <listitem>
<para>To list all containers: run the following command:</para> <para>To list all containers, run the following command:</para>
<screen><prompt>$</prompt> <userinput>swift list</userinput></screen> <screen><prompt>$</prompt> <userinput>swift list</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
@ -116,10 +116,11 @@ X-Timestamp: 1392684036.33306</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>swift list <replaceable>CONTAINER</replaceable></userinput></screen> <screen><prompt>$</prompt> <userinput>swift list <replaceable>CONTAINER</replaceable></userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<para>To download an object from a container:, run the following <para>To download an object from a container, run the
command:</para> following command:</para>
<screen><prompt>$</prompt> <userinput>swift download <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen> <screen><prompt>$</prompt> <userinput>swift download <replaceable>CONTAINER</replaceable> <replaceable>OBJECT_FILENAME</replaceable></userinput></screen>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
<xi:include href="section_object-api-versioning.xml"/>
</section> </section>

171
doc/user-guide/section_object-api-versioning.xml Normal file
View File

@ -0,0 +1,171 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "../common/entities/openstack.ent">
%openstack;
]>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="set-object-versions">
<title>Object versioning</title>
<para>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.</para>
<note>
<para>You cannot version a large-object manifest file, but the
large-object manifest file can point to versioned
segments.</para>
</note>
<para>We strongly recommended that you put non-current objects in
a different container than the container where current object
versions reside.</para>
<procedure>
<title>To enable and use object versioning</title>
<step>
<para>To enable object versioning, ask your cloud provider
to set the <option>allow_versions</option> option to
<literal>TRUE</literal> in the container
configuration file.</para>
</step>
<step>
<para>Create an <literal>archive</literal> container to
store older versions of objects:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx46f8c29050834d88b8d7e-0052e1859d
Date: Thu, 23 Jan 2014 21:11:57 GMT</computeroutput></screen>
</step>
<step>
<para>Create a <literal>current</literal> container to
store current versions of objects.</para>
<para>Include the <literal>X-Versions-Location</literal>
header. This header defines the container that holds
the non-current versions of your objects. You must
UTF-8-encode and then URL-encode the container name
before you include it in the
<code>X-Versions-Location</code> header. This
header enables object versioning for all objects in
the <literal>current</literal> container. Changes to
objects in the <literal>current</literal> container
automatically create non-current versions in the
<literal>archive</literal> container.</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: archive"</userinput></screen>
<screen><computeroutput>HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb91810fb717347d09eec8-0052e18997
Date: Thu, 23 Jan 2014 21:28:55 GMT</computeroutput></screen>
</step>
<step>
<para>Create the first version of an object in the
<literal>current</literal> container:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 1 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>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
Date: Thu, 23 Jan 2014 21:31:22 GMT</computeroutput></screen>
<para>Nothing is written to the non-current version
container when you initially &PUT; an object in the
<literal>current</literal> container. However,
subsequent &PUT; requests that edit an object trigger
the creation of a version of that object in the
<literal>archive</literal> container.</para>
<para>These non-current versions are named as
follows:</para>
<programlisting>&lt;length>&lt;object_name>&lt;timestamp></programlisting>
<para>Where <literal>length</literal> is the 3-character, zero-padded
hexadecimal character length of the object,
<literal>&lt;object_name&gt;</literal> is the object name, and
<literal>&lt;timestamp&gt;</literal> is the time when the object was
initially created as a current version.</para>
</step>
<step>
<para>Create a second version of the object in the
<literal>current</literal> container:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object --data-binary 2 -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>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
Date: Thu, 23 Jan 2014 21:41:32 GMT</computeroutput></screen>
</step>
<step>
<para>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.</para>
<para>List older versions of the object in the
<literal>archive</literal> container:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>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
Date: Thu, 23 Jan 2014 21:45:50 GMT
009my_object/1390512682.92052</computeroutput></screen>
<note>
<para>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.</para>
</note>
</step>
<step>
<para>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.</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current/my_object -X DELETE -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx006d944e02494e229b8ee-0052e18edd
Date: Thu, 23 Jan 2014 21:51:25 GMT</computeroutput></screen>
<para>List objects in the <literal>archive</literal>
container to show that the archived object was moved
back to the <literal>current</literal>
container:</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/archive?prefix=009my_object -X GET -H "X-Auth-Token: $token"</userinput></screen>
<screen><computeroutput>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
Date: Thu, 23 Jan 2014 21:51:41 GMT</computeroutput></screen>
<para>This next-most current version carries with it any
metadata last set on it. If you want to completely
remove an object and you have five versions of it, you
must &DELETE; it five times.</para>
</step>
<step>
<para>To disable object versioning for the
<literal>current</literal> container, remove its
<literal>X-Versions-Location</literal> metadata
header by sending an empty key value.</para>
<screen><prompt>#</prompt> <userinput>curl -i $publicURL/current -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" -H "X-Versions-Location: "</userinput></screen>
<screen><computeroutput>HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe2476de217134549996d0-0052e19038
Date: Thu, 23 Jan 2014 21:57:12 GMT
&lt;html>&lt;h1>Accepted&lt;/h1>&lt;p>The request is accepted for processing.&lt;/p>&lt;/html></computeroutput></screen>
</step>
</procedure>
</section>