d813475bc0
Cinder API docs doesn't include Error responses. This change adds details about the common response status codes returned by the Block Storage Service. Changes include modification both at the v2 and v1 layer. Closes-Bug: #1244395 Change-Id: I08f4c3d32e57b56c82f35663f6aed12a706f4a8d
1030 lines
41 KiB
XML
1030 lines
41 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book [
|
|
<!-- 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 v2.0'>
|
|
<!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 v2 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>2013</year>
|
|
<year>2014</year>
|
|
<holder>OpenStack Foundation</holder>
|
|
</copyright>
|
|
<releaseinfo>API v2 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 for software developers who develop
|
|
applications by using the OpenStack Block Storage Application
|
|
Programming Interface (<abbrev>API</abbrev>).</para>
|
|
</abstract>
|
|
<revhistory>
|
|
<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>
|
|
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
|
|
<date>2014-05-01</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added Block Storage extensions to the API
|
|
operations chapter.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2014-02-23</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Updated API call descriptions to point to WADL
|
|
files.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-12-14</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Corrected code example for list volume details
|
|
request.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-05-22</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Updated the book title for consistency.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-04-21</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Corrected request and response examples in the API
|
|
operations chapter.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-04-10</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Adds information about backups.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-02-24</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 the
|
|
OpenStack Compute service.</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 assists 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>
|
|
<section xml:id="Additional_Resources-d1e532">
|
|
<title>Additional resources</title>
|
|
<para>You can download the latest 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>
|
|
<chapter 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>OpenStack Block Storage is a block-level storage solution
|
|
that enables you to: <itemizedlist>
|
|
<listitem>
|
|
<para>Mount drives to OpenStack Cloud Servers<trademark/> to
|
|
scale storage without paying for more compute
|
|
resources.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Use high performance storage to serve database or
|
|
I/O-intensive applications.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
<para>You interact with Block Storage programmatically through the
|
|
Block Storage API as described in this guide.</para>
|
|
<note>
|
|
<para><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>
|
|
<listitem>
|
|
<para>Block Storage allows you to create backups of your
|
|
volumes to Object Storage for archival and disaster
|
|
recovery purposes. These backups can be subsequently
|
|
restored to the same volume or new volumes.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</note>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Concepts">
|
|
<title>Glossary</title>
|
|
<?dbhtml stop-chunking?>
|
|
<para>To use the Block Storage API effectively, you must
|
|
understand several key concepts:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Volume</emphasis></para>
|
|
<para>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>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Volume type</emphasis></para>
|
|
<para>A type of a block storage volume. You can 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 can 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>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Snapshot</emphasis></para>
|
|
<para>A point in time copy of the data contained in a
|
|
volume.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Instance</emphasis></para>
|
|
<para>A virtual machine (VM) that runs inside the
|
|
cloud.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis role="bold">Backup</emphasis></para>
|
|
<para>A full copy of a volume stored in an external service.
|
|
The service can be configured. The only supported service
|
|
for now is Object Storage. A backup can subsequently be
|
|
restored from the external service to either the same
|
|
volume that the backup was originally taken from, or to a
|
|
new volume.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="High_Level_Task_Flow">
|
|
<title>High-level task flow</title>
|
|
<procedure>
|
|
<title>To create and attach a volume</title>
|
|
<step>
|
|
<para>You create a volume.</para>
|
|
<para>For example, you might create a 30 GB volume called
|
|
<literal>vol1</literal>, as follows:</para>
|
|
<screen><prompt>$</prompt> <userinput>cinder create --display-name vol1 30</userinput></screen>
|
|
<para>The command returns the
|
|
<literal>521752a6-acf6-4b2d-bc7a-119f9148cd8c</literal>
|
|
volume ID.</para>
|
|
</step>
|
|
<step>
|
|
<para>You attach that volume to a virtual machine (VM) with
|
|
the
|
|
<literal>616fb98f-46ca-475e-917e-2563e5a8cd19</literal>
|
|
ID, as follows:</para>
|
|
<para>For example:</para>
|
|
<screen><prompt>$</prompt> <userinput>nova volume-attach 616fb98f-46ca-475e-917e-2563e5a8cd19 521752a6-acf6-4b2d-bc7a-119f9148cd8c /dev/vdb</userinput></screen>
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="General_API_Information">
|
|
<title>General API information</title>
|
|
<para>The Block Storage API is implemented using a ReSTful web
|
|
service interface. Like other OpenStack projects, Block Storage
|
|
shares a common token-based authentication system that allows
|
|
access between products and services.</para>
|
|
<note>
|
|
<para>All requests to authenticate against and operate the
|
|
service are performed using SSL over HTTP (HTTPS) on TCP port
|
|
443.</para>
|
|
</note>
|
|
<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, and send the token to a service.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Get an authentication token by providing your user
|
|
name 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
|
|
user name and your password.</emphasis></para>
|
|
<screen><prompt>$</prompt> <userinput>curl -X POST https://localhost:5000/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</userinput></screen>
|
|
<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 programmatically parse an authentication
|
|
response, 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 that 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>Request with headers: Get volume types</title>
|
|
<literallayout class="monospaced">GET /&VERSION;/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>An XML response format is returned:</para>
|
|
<example>
|
|
<title>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-7'?>
|
|
<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="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>The following table shows the absolute limits:</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</td>
|
|
<td colspan="1">1 TB</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
</section>
|
|
<section xml:id="datetimeformat">
|
|
<title>Date and time format</title>
|
|
<para>Block Storage 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>May 19th, 2011 at 8:07:08 AM, GMT-5 has the following
|
|
format:</para>
|
|
<programlisting>2011-05-19T08:07:08-05:00</programlisting>
|
|
</example>
|
|
<para>The following table describes the date time format
|
|
codes:</para>
|
|
<table rules="all">
|
|
<caption>Date 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, Block Storage returns a fault object
|
|
containing an HTTP error response code that denotes the type
|
|
of error. The response body returns 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" width="100%">
|
|
<col width="20%"/>
|
|
<col width="15%"/>
|
|
<col width="65%"/>
|
|
<thead>
|
|
<tr align="center">
|
|
<td>Fault type</td>
|
|
<td>Associated error code</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>badRequest</code></td>
|
|
<td>400</td>
|
|
<td>The user request contains one or more errors.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>unauthorized</code></td>
|
|
<td>401</td>
|
|
<td>The supplied token is not authorized to access the
|
|
resources, either it's expired or invalid.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>forbidden</code></td>
|
|
<td>403</td>
|
|
<td>Access to the requested resource was denied.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>itemNotFound</code></td>
|
|
<td>404</td>
|
|
<td>The back-end services did not find anything matching
|
|
the Request-URI.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>badMethod</code></td>
|
|
<td>405</td>
|
|
<td>The request method is not allowed for this
|
|
resource.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>overLimit</code></td>
|
|
<td>413</td>
|
|
<td>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><code>badMediaType</code></td>
|
|
<td>415</td>
|
|
<td>The requested content type is not supported by this
|
|
service.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>unprocessableEntity</code></td>
|
|
<td>422</td>
|
|
<td>The requested resource could not be processed on at
|
|
the moment.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>instanceFault</code></td>
|
|
<td>500</td>
|
|
<td>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><code>notImplemented</code></td>
|
|
<td>501</td>
|
|
<td>The requested method or resource is not
|
|
implemented.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>serviceUnavailable</code></td>
|
|
<td>503</td>
|
|
<td>Block Storage 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 response: XML</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 response: JSON</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>The following two <code>badRequest</code> examples show
|
|
errors when the volume size is invalid:</para>
|
|
<example>
|
|
<title>Example badRequest fault on volume size errors:
|
|
XML</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 on volume size errors:
|
|
JSON</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 next two examples show <code>itemNotFound</code>
|
|
errors:</para>
|
|
<example>
|
|
<title>Example itemNotFound fault: XML</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</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>
|
|
<section xml:id="Volumes">
|
|
<title>Volumes</title>
|
|
<para>A volume is a detachable block storage device. You can
|
|
think of it as a USB hard drive. You can attach a volume to
|
|
one instance at a time.</para>
|
|
<para>When you create, list, or delete volumes, these status
|
|
values are possible:</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<th>Status</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><para>creating</para></td>
|
|
<td><para>The volume is being created.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>available</para></td>
|
|
<td><para>The volume is ready to be attached to an
|
|
instance.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>attaching</para></td>
|
|
<td><para>The volume is attaching to an
|
|
instance.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>in-use</para></td>
|
|
<td><para>The volume is attached to an
|
|
instance.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>deleting</para></td>
|
|
<td><para>The volume is being deleted.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>error</para></td>
|
|
<td><para>An error occurred during volume
|
|
creation.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>error_deleting</para></td>
|
|
<td><para>An error occurred during volume
|
|
deletion.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>backing-up</para></td>
|
|
<td><para>The volume is being backed up.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>restoring-backup</para></td>
|
|
<td><para>A backup is being restored to the
|
|
volume.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td><para>error_restoring</para></td>
|
|
<td><para>An error occurred during backup restoration to a
|
|
volume.</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#volumes">
|
|
<wadl:method href="createVolume"/>
|
|
<wadl:method href="getVolumesSimple"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#detail">
|
|
<wadl:method href="getVolumesDetail"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#volume_id">
|
|
<wadl:method href="getVolume"/>
|
|
<wadl:method href="updateVolume"/>
|
|
<wadl:method href="deleteVolume"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="Snapshots">
|
|
<title>Snapshots</title>
|
|
<para>A snapshot is a point in time copy of the data that a
|
|
volume contains.</para>
|
|
<para>When you create, list, or delete snapshots, these status
|
|
values are possible:</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<th>Status</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<para>creating</para></td>
|
|
<td><para>The snapshot is being created.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>available</para></td>
|
|
<td><para>The snapshot is ready to be used.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>deleting</para></td>
|
|
<td><para>The snapshot is being deleted.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>error</para></td>
|
|
<td><para>An error occurred during snapshot
|
|
creation.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>error_deleting</para></td>
|
|
<td><para>An error occurred during snapshot
|
|
deletion.</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#snapshots"/>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#detail-snapshot"/>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#snapshot_id"
|
|
/>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="Volume_Types">
|
|
<title>Volume types</title>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#types">
|
|
<wadl:method href="getVolumeTypes"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-api-v2.wadl#volume_type_id">
|
|
<wadl:method href="getVolumeType"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="qos-cinder-v2">
|
|
<title>Quality of service (QoS) specifications
|
|
(qos-specs)</title>
|
|
<para>Administrators only, depending on policy settings. Create,
|
|
list, show details for, associate, disassociate, and delete
|
|
quality of service (QoS) specifications.</para>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-qos-v2.wadl#qos-specs">
|
|
<wadl:method href="#createQoSSpec"/>
|
|
<wadl:method href="#listQoSSpecs"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-qos-v2.wadl#qos_id"/>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-qos-v2.wadl#associate">
|
|
<wadl:method href="#associateQoSSpec"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-qos-v2.wadl#disassociate">
|
|
<wadl:method href="#disassociateQoSSpec"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-qos-v2.wadl#disassociate_all">
|
|
<wadl:method href="#disassociateQoSSpecAll"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-qos-v2.wadl#associations">
|
|
<wadl:method href="#getQoSAssociations"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
<section xml:id="ext-os-quota-sets-cinder">
|
|
<title>Quota sets extension (os-quota-sets)</title>
|
|
<para>Administrators only, depending on policy settings. View,
|
|
update, and delete quotas for a tenant.</para>
|
|
<wadl:resources
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-quota-sets.wadl"
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
|
|
</section>
|
|
<section xml:id="ext-os-limits-cinder">
|
|
<title>Limits extension (limits)</title>
|
|
<para>Show absolute limits for a tenant.</para>
|
|
<wadl:resources
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/os-limits.wadl"
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
|
|
</section>
|
|
<section xml:id="Backups">
|
|
<title>Backups extension</title>
|
|
<para>A backup is a full copy of a volume stored in an external
|
|
service. The service can be configured. The only supported
|
|
service for now is Object Storage. A backup can subsequently
|
|
be restored from the external service to either the same
|
|
volume that the backup was originally taken from, or to a new
|
|
volume. backup and restore operations can only be carried out
|
|
on volumes which are in an unattached and available
|
|
state.</para>
|
|
<para>When you create, list, or delete backups, these status
|
|
values are possible:</para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr>
|
|
<th>Status</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<para>creating</para></td>
|
|
<td><para>The backup is being created.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>available</para></td>
|
|
<td><para>The backup is ready to be restored to a
|
|
volume.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>deleting</para></td>
|
|
<td><para>The backup is being deleted.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>error</para></td>
|
|
<td><para>An error has occurred with the
|
|
backup.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>restoring</para></td>
|
|
<td><para>The backup is being restored to a
|
|
volume.</para></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<para>error_restoring</para></td>
|
|
<td><para>An error occurred during backup restoration to a
|
|
volume.</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<para>In the event of an error, more information about the error
|
|
can be found in the <literal>fail_reason</literal> field for
|
|
the backup.</para>
|
|
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-backups-api-v2.wadl#backups">
|
|
<wadl:method href="#createBackup"/>
|
|
<wadl:method href="#listBackups"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-backups-api-v2.wadl#detail">
|
|
<wadl:method href="#listBackupsDetails"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-backups-api-v2.wadl#backup_id">
|
|
<wadl:method href="#showBackup"/>
|
|
<wadl:method href="#deleteBackup"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/volume-api/src/v2/volume-backups-api-v2.wadl#restore">
|
|
<wadl:method href="#restoreBackup"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
</chapter>
|
|
</book>
|