<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!ENTITY ndash "–">
<!ENTITY mdash "—">
<!ENTITY hellip "…">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</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 PRODNAME "OpenStack Block Storage">
<!ENTITY API 'Block Storage API v1'>
<!ENTITY VERSION 'v2'>
<!ENTITY PRODABBV "">
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject>
<imagedata fileref="img/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
</inlinemediaobject>'>
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="openstack-blockstorage-devguide">
<title>OpenStack Block Storage API v1 Reference</title>
<?rax title.font.size="28px" subtitle.font.size="28px"?>
<titleabbrev>Block Storage API Reference</titleabbrev>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>OpenStack Foundation</orgname>
</affiliation>
</author>
<copyright>
<year>2010-2014</year>
<holder>OpenStack Foundation</holder>
</copyright>
<releaseinfo>API v1 and extensions</releaseinfo>
<productname>OpenStack Block Storage</productname>
<pubdate/>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the
template.</remark>
</annotation>
</legalnotice>
<abstract>
<para>This document is intended for software developers
interested in developing applications using the &PRODNAME;
Application Programming Interface
(<abbrev>API</abbrev>).</para>
</abstract>
<revhistory xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml">
<revision>
<date>2014-08-05</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Removed and replaced WADL references with link to <link
xlink:href="http://developer.openstack.org/api-ref-blockstorage-v1.html"
><citetitle>Block Storage API v1
(CURRENT)</citetitle></link>.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2014-06-17</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Added common response status codes returned by
Block Storage.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2013-02-18</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Updated v1 documentation.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2012-12-17</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Edits to initial version.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2012-10-17</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Initial release.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>
<preface xml:id="Preface">
<title>Preface</title>
<para>OpenStack Block Storage provides volume management with
OpenStack Compute.</para>
<para>This document describes the features available with the
&API;.</para>
<para>We welcome feedback, comments and bug reports at <link
xlink:href="http://bugs.launchpad.net/cinder"
>bugs.launchpad.net/Cinder</link>.</para>
<section xml:id="Intended_Audience-d1e122">
<title>Intended audience</title>
<para>This guide is for software developers who develop
applications by using the &API;. It assumes the reader has a
general understanding of storage and is familiar with:</para>
<itemizedlist spacing="compact">
<listitem>
<para>ReSTful web services</para>
</listitem>
<listitem>
<para>HTTP/1.1 conventions</para>
</listitem>
<listitem>
<para>JSON and/or XML data serialization formats</para>
</listitem>
</itemizedlist>
</section>
<?hard-pagebreak?>
<section xml:id="Additional_Resources-d1e532">
<title>Resources</title>
<para>You can download the most current versions of the
API-related documents from <link
xlink:href="http://docs.openstack.org/api/"
>docs.openstack.org/api/</link>.</para>
<para>This API uses standard HTTP 1.1 response codes as
documented at: <link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
>www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.</para>
</section>
</preface>
<preface xml:id="Overview" xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml">
<title>Overview</title>
<para>&PRODNAME; is a block-level storage solution that allows
customers to mount drives or volumes to their OpenStack Compute
servers<trademark/>. The two primary use cases are (1) to allow
customers to scale their storage independently from their
compute resources, and (2) to allow customers to utilize high
performance storage to serve database or I/O-intensive
applications.</para>
<para>Interactions with Block Storage occur programmatically via
the Block Storage API as described in this Developer
Guide.</para>
<para>Highlights of &PRODNAME; include:<itemizedlist>
<listitem>
<para>Mount a drive to a Compute server to scale storage
without paying for more compute capability.</para>
</listitem>
</itemizedlist>
</para>
<note>
<title>Notes</title>
<itemizedlist>
<listitem>
<para>&PRODNAME; is an add-on feature to OpenStack Nova
Compute in Folsom versions and earlier.</para>
</listitem>
<listitem>
<para>Block Storage is multi-tenant rather than
dedicated.</para>
</listitem>
<listitem>
<para>Block Storage allows you to create snapshots that you
can save, list, and restore.</para>
</listitem>
</itemizedlist>
</note>
<?hard-pagebreak?>
<section xml:id="Concepts">
<title>Glossary</title>
<?dbhtml stop-chunking?>
<para>To use the &PRODNAME; API effectively, you should
understand several key concepts:</para>
<section xml:id="Volume">
<title>Volume</title>
<para>A volume is a detachable block storage device. You can
think of it as a USB hard drive. It can only be attached to
one instance at a time.</para>
</section>
<section xml:id="Snapshot">
<title>Snapshot</title>
<para>A snapshot is a point in time copy of the data contained
in a volume.</para>
</section>
<section xml:id="Volumetype">
<title>Volume type</title>
<para>The volume type is the type of a block storage volume.
You may define whatever types work best for you, such as
SATA, SCSCI, SSD, etc. These can be customized or defined by
the OpenStack admin.</para>
<para>You may also define extra_specs associated with your
volume types. For instance, you could have a
VolumeType=SATA, with extra_specs (RPM=10000, RAID-Level=5)
. Extra_specs are defined and customized by the
admin.</para>
</section>
<section xml:id="Instance">
<title>Instance</title>
<para>An instance is a virtual machine that runs inside the
cloud.</para>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="High_Level_Task_Flow">
<title>High-level task flow</title>
<para>The high-level task flow for Cinder is as follows:</para>
<para>
<orderedlist>
<listitem>
<para>The tenant creates a volume.</para>
<para>For example, the tenant creates a 30G volume called
vol1.</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt>cinder create --display-name vol1 30</programlisting>
</listitem>
<listitem>
<para>This gives the tenant a volume id
521752a6-acf6-4b2d-bc7a-119f9148cd8c. The tenant
attaches that volume to a virtual machine (VM)
616fb98f-46ca-475e-917e-2563e5a8cd19:</para>
<para>For example A:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb</programlisting>
</listitem>
</orderedlist>
</para>
</section>
</preface>
<chapter xml:id="General_API_Information"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml">
<title>General API information</title>
<section xml:id="Authentication-d1e647">
<title>Authentication</title>
<para>You can use <link xlink:href="http://curl.haxx.se/"
>cURL</link> to try the authentication process in two steps:
get a token; send the token to a service.</para>
<orderedlist>
<listitem>
<para>Get an authentication token by providing your username
and either your API key or your password. Here are
examples of both approaches:</para>
<para><emphasis>You can request a token by providing your
username and your password.</emphasis></para>
<para>
<literallayout class="monospaced">curl -X POST https://auth.api.openstackcloud.com/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</literallayout>
</para>
<para>Successful authentication returns a token which you
can use as evidence that your identity has already been
authenticated. To use the token, pass it to other services
as an <code>X-Auth-Token</code> header.</para>
<para>Authentication also returns a service catalog, listing
the endpoints you can use for Cloud services.</para>
</listitem>
<listitem>
<para>Use the authentication token to send a GET to a
service you would like to use.</para>
</listitem>
</orderedlist>
<para>Authentication tokens are typically valid for 24 hours.
Applications should be designed to re-authenticate after
receiving a 401 (Unauthorized) response from a service
endpoint.</para>
<important>
<para>If you are programmatically parsing an authentication
response, please be aware that service names are stable for
the life of the particular service and can be used as keys.
You should also be aware that a user's service catalog can
include multiple uniquely-named services which perform
similar functions.</para>
</important>
</section>
<section xml:id="Request_Response_Types-d1e903">
<title>Request and response types</title>
<para>The Block Storage API supports both the JSON and XML data
serialization formats. The request format is specified using
the <code>Content-Type</code> header and is required for calls
that have a request body. The response format can be specified
in requests either by using the <code>Accept</code> header or
by adding an <code>.xml</code> or <code>.json</code> extension
to the request URI. Note that it is possible for a response to
be serialized using a format different from the request. If no
response format is specified, JSON is the default. If
conflicting formats are specified using both an
<code>Accept</code> header and a query extension, the query
extension takes precedence.</para>
<para security="writeronly">Some operations support an Atom
representation that can be used to efficiently determine when
the state of services has changed.</para>
<table rules="all">
<caption>Response formats</caption>
<thead>
<tr align="center">
<td>Format</td>
<td>Accept header</td>
<td>Query extension</td>
<td>Default</td>
</tr>
</thead>
<tbody>
<tr>
<td>JSON</td>
<td>application/json</td>
<td>.json</td>
<td>Yes</td>
</tr>
<tr>
<td>XML</td>
<td>application/xml</td>
<td>.xml</td>
<td>No</td>
</tr>
</tbody>
</table>
<para>In the request example below, notice that
<parameter>Content-Type</parameter> is set to
<parameter>application/json</parameter>, but
<parameter>application/xml</parameter> is requested via the
<parameter>Accept</parameter> header:</para>
<example>
<title>Get volume types: Request with headers</title>
<literallayout class="monospaced">
GET /v1/441446/types HTTP/1.1
Host: dfw.blockstorage.api.openstackcloud.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Accept: application/xml
</literallayout>
</example>
<para><?rax-fo keep-with-next?>Therefore an XML response format
is returned:</para>
<example>
<title>Get volume types: Response with headers</title>
<literallayout class="monospaced">
HTTP/1.1 200 OK
Date: Fri, 20 Jul 2012 20:32:13 GMT
Content-Length: 187
Content-Type: application/xml
X-Compute-Request-Id: req-8e0295cd-a283-46e4-96da-cae05cbfd1c7
<?xml version='1.0' encoding='UTF-8'?>
<volume_types>
<volume_type id="1" name="SATA">
<extra_specs/>
</volume_type>
<volume_type id="2" name="SSD">
<extra_specs/>
</volume_type>
</volume_types>
</literallayout>
</example>
</section>
<xi:include href="../v2/section_http_status_codes.xml"/>
<section xml:id="Limits-d1e1208">
<title>Limits</title>
<para>All accounts, by default, have a preconfigured set of
thresholds (or limits) to manage capacity and prevent abuse of
the system. The system recognizes two kinds of limits:
<firstterm>rate limits</firstterm> and <firstterm>absolute
limits</firstterm>. Rate limits are thresholds that are
reset after a certain amount of time passes. Absolute limits
are fixed.</para>
<section xml:id="Rate_Limits-d1e1222" security="writeronly">
<title>Rate limits</title>
<para>Rate limits are specified in terms of both a
human-readable wild-card URI and a machine-processable
regular expression. The regular expression boundary matcher
'^' takes effect after the root URI path. For example, the
regular expression ^/v1.0/instances would match the bolded
portion of the following URI:
https://dfw.blockstorage.api.openstackcloud.com<emphasis
role="bold">/v1.0/instances</emphasis>.</para>
<para>The following table specifies the default rate limits
for all API operations for all &GET;, &POST;, &PUT;, and
&DELETE; calls for volumes:</para>
<table rules="all">
<caption>Default rate limits</caption>
<thead>
<tr align="center">
<td colspan="1">Verb</td>
<td colspan="2">URI</td>
<td colspan="2">RegEx</td>
<td colspan="1">Default</td>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1">&GET; changes-since</td>
<td colspan="2">*/instances/*</td>
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
<td colspan="1">3/minute</td>
</tr>
<tr>
<td colspan="1">&POST;</td>
<td colspan="2">*/instances/*</td>
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
<td colspan="1">10/minute</td>
</tr>
<tr>
<td colspan="1">&POST; instances</td>
<td colspan="2">*/instances/*</td>
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
<td colspan="1">50/day</td>
</tr>
<tr>
<td colspan="1">&PUT;</td>
<td colspan="2">*/instances/*</td>
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
<td colspan="1">10/minute</td>
</tr>
<tr>
<td colspan="1">&DELETE;</td>
<td colspan="2">*/instances/*</td>
<td colspan="2">^/v\d+\.\d+/\d+/instances.*</td>
<td colspan="1">100/minute</td>
</tr>
</tbody>
</table>
<para>Rate limits are applied in order relative to the verb,
going from least to most specific. For example, although the
threshold for &POST; to /v1.0/* is 10 per minute, one cannot
&POST; to /v1.0/* more than 50 times within a single
day.</para>
<para>If you exceed the thresholds established for your
account, a <errorcode>413 (Rate Control)</errorcode> HTTP
response will be returned with a <code>Retry-After</code>
header to notify the client when it can attempt to try
again.</para>
</section>
<section xml:id="Absolute_Limits-d1e1397">
<title>Absolute limits</title>
<para>Refer to the following table for the absolute limits
that are set.</para>
<table rules="all">
<caption>Absolute limits</caption>
<col width="120pt"/>
<col width="201pt"/>
<col width="50pt"/>
<thead>
<tr>
<td colspan="1">Name</td>
<td colspan="1">Description</td>
<td colspan="1">Limit</td>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1">Block Storage</td>
<td colspan="1">Maximum amount of block storage (in
gigabytes)</td>
<td colspan="1">1 TB</td>
</tr>
</tbody>
</table>
</section>
</section>
<section xml:id="datetimeformat">
<title>Date and time format</title>
<para>The Block Storage Service uses an ISO-8601 compliant date
format for the display and consumption of date/time
values.</para>
<example>
<title>DB service date and time format</title>
<programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
<para>See the table below for a description of the date/time
format codes.</para>
<para>May 19th, 2011 at 8:07:08 AM, GMT-5 would have the
following format:</para>
<programlisting>2011-05-19T08:07:08-05:00</programlisting>
</example>
<table rules="all">
<caption>Date and time format codes</caption>
<thead>
<tr>
<td>Code</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>yyyy</td>
<td>Four digit year</td>
</tr>
<tr>
<td>MM</td>
<td>Two digit month</td>
</tr>
<tr>
<td>dd</td>
<td>Two digit day of month</td>
</tr>
<tr>
<td>T</td>
<td>Separator for date/time</td>
</tr>
<tr>
<td>HH</td>
<td>Two digit hour of day (00-23)</td>
</tr>
<tr>
<td>mm</td>
<td>Two digit minutes of hour</td>
</tr>
<tr>
<td>ss</td>
<td>Two digit seconds of the minute</td>
</tr>
<tr>
<td>SSS</td>
<td>Three digit milliseconds of the second</td>
</tr>
<tr>
<td>Z</td>
<td>RFC-822 timezone</td>
</tr>
</tbody>
</table>
</section>
<section xml:id="DB_faults">
<title>Faults</title>
<para>When an error occurs, the Block Storage Service returns a
fault object containing an HTTP error response code that
denotes the type of error. In the body of the response, the
system will return additional information about the
fault.</para>
<para>The following table lists possible fault types with their
associated error codes and descriptions.</para>
<informaltable rules="all">
<thead>
<tr align="center">
<td colspan="2">Fault Type</td>
<td colspan="1">Associated Error Code</td>
<td colspan="3">Description</td>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2"><code>badRequest</code></td>
<td colspan="1">400</td>
<td colspan="3">There was one or more errors in the user
request.</td>
</tr>
<tr>
<td colspan="2"><code>unauthorized</code></td>
<td colspan="1">401</td>
<td colspan="3">The supplied token is not authorized to
access the resources, either it's expired or
invalid.</td>
</tr>
<tr>
<td colspan="2"><code>forbidden</code></td>
<td colspan="1">403</td>
<td colspan="3">Access to the requested resource was
denied.</td>
</tr>
<tr>
<td colspan="2"><code>itemNotFound</code></td>
<td colspan="1">404</td>
<td colspan="3">The back-end services did not find
anything matching the Request-URI.</td>
</tr>
<tr>
<td colspan="2"><code>badMethod</code></td>
<td colspan="1">405</td>
<td colspan="3">The request method is not allowed for this
resource.</td>
</tr>
<tr>
<td colspan="2"><code>overLimit</code></td>
<td colspan="1">413</td>
<td colspan="3">Either the number of entities in the
request is larger than allowed limits, or the user has
exceeded allowable request rate limits. See the
<code>details</code> element for more specifics.
Contact support if you think you need higher request
rate limits.</td>
</tr>
<tr>
<td colspan="2"><code>badMediaType</code></td>
<td colspan="1">415</td>
<td colspan="3">The requested content type is not
supported by this service.</td>
</tr>
<tr>
<td colspan="2"><code>unprocessableEntity</code></td>
<td colspan="1">422</td>
<td colspan="3">The requested resource could not be
processed on at the moment.</td>
</tr>
<tr>
<td colspan="2"><code>instanceFault</code></td>
<td colspan="1">500</td>
<td colspan="3">This is a generic server error and the
message contains the reason for the error. This error
could wrap several error messages and is a catch
all.</td>
</tr>
<tr>
<td colspan="2"><code>notImplemented</code></td>
<td colspan="1">501</td>
<td colspan="3">The requested method or resource is not
implemented.</td>
</tr>
<tr>
<td colspan="2"><code>serviceUnavailable</code></td>
<td colspan="1">503</td>
<td colspan="3">The Block Storage Service is not
available.</td>
</tr>
</tbody>
</informaltable>
<para>The following two <code>instanceFault</code> examples show
errors when the server has erred or cannot perform the
requested operation:</para>
<example>
<title>Example instancefault: XML response</title>
<screen><computeroutput>HTTP/1.1 500 Internal Server Error
Content-Type: application/xml
Content-Length: 121
Date: Mon, 28 Nov 2011 18:19:37 GMT</computeroutput></screen>
<programlisting language="xml"><xi:include href="samples/db-faults-instanceFault.xml" parse="text"/></programlisting>
</example>
<example>
<title>Example fault: JSON response</title>
<screen><computeroutput>HTTP/1.1 500 Internal Server Error
Content-Length: 120
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:33:48 GMT</computeroutput></screen>
<programlisting language="json"><xi:include href="samples/db-faults-instanceFault.json" parse="text"/></programlisting>
</example>
<para>The error code (<code>code</code>) is returned in the body
of the response for convenience. The <code>message</code>
element returns a human-readable message that is appropriate
for display to the end user. The <code>details</code> element
is optional and may contain information that is useful for
tracking down an error, such as a stack trace. The
<code>details</code> element may or may not be appropriate
for display to an end user, depending on the role and
experience of the end user.</para>
<para>The fault's root element (for example,
<code>instanceFault</code>) may change depending on the type
of error.</para>
<para><?rax-fo keep-with-next?>The following
<code>badRequest</code> examples show errors when the volume
size is not valid:</para>
<example>
<title>Example badRequest fault and volume size errors: XML
request</title>
<screen><computeroutput>HTTP/1.1 400 None
Content-Type: application/xml
Content-Length: 121
Date: Mon, 28 Nov 2011 18:19:37 GMT</computeroutput></screen>
<programlisting language="xml"><xi:include href="samples/db-faults-badRequest.xml" parse="text"/></programlisting>
</example>
<example>
<title>Example badRequest fault and volume size errors: JSON
request</title>
<screen><computeroutput>HTTP/1.1 400 None
Content-Length: 120
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:33:48 GMT</computeroutput></screen>
<programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting>
</example>
<para>The following examples show <code>itemNotFound</code>
errors:</para>
<example>
<title>Example itemNotFound fault: XML response</title>
<screen><computeroutput>HTTP/1.1 404 Not Found
Content-Length: 147
Content-Type: application/xml; charset=UTF-8
Date: Mon, 28 Nov 2011 19:50:15 GMT</computeroutput></screen>
<programlisting language="xml"><xi:include href="samples/db-faults-itemNotFound.xml" parse="text"/></programlisting>
</example>
<example>
<title>Example itemNotFound fault: JSON response</title>
<screen><computeroutput>HTTP/1.1 404 Not Found
Content-Length: 78
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:35:24 GMT</computeroutput></screen>
<programlisting language="json"><xi:include href="samples/db-faults-itemNotFound.json" parse="text"/></programlisting>
</example>
</section>
</chapter>
<chapter xml:id="API_Operations"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml">
<title>API operations</title>
<para>For information about Block Storage API operations, see <link
xlink:href="http://developer.openstack.org/api-ref-blockstorage-v1.html"
><citetitle>Block Storage API v1 (CURRENT)</citetitle></link>.</para>
</chapter>
</book>