1433 lines
81 KiB
XML
Executable File
1433 lines
81 KiB
XML
Executable File
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
<!ENTITY plusmn "±">
|
|
|
|
<!-- 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 CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="../figures/Check_mark_23x20_02.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
|
|
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="../figures/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="os-cs-devguide">
|
|
<title>OpenStack Compute API v2 Reference</title>
|
|
<?rax title.font.size="26px" subtitle.font.size="26px"?>
|
|
<titleabbrev>Compute API Reference</titleabbrev>
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<affiliation>
|
|
<orgname>OpenStack Foundation</orgname>
|
|
</affiliation>
|
|
</author>
|
|
<copyright>
|
|
<year>2009</year>
|
|
<year>2010</year>
|
|
<year>2011</year>
|
|
<year>2012</year>
|
|
<year>2013</year>
|
|
<year>2014</year>
|
|
<holder>OpenStack Foundation</holder>
|
|
</copyright>
|
|
<releaseinfo>API v2 and extensions</releaseinfo>
|
|
<productname>OpenStack Compute</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 OpenStack Compute Application Programming Interface
|
|
(<abbrev>API</abbrev>).</para>
|
|
</abstract>
|
|
<revhistory>
|
|
<revision>
|
|
<date>2014-07-30</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Removed <parameter>changes-since</parameter> parameter from the list flavors operation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2014-08-01</date>
|
|
<revdescription>
|
|
<para>Removes and replaces all WADL references with links to the <link
|
|
xlink:href="http://developer.openstack.org/api-ref.html"
|
|
><citetitle>OpenStack API Complete
|
|
Reference</citetitle></link>.</para>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-09-10</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Added the 422 return code to the reboot server operation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-05-22</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Updated the book title for consistency.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-04-27</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Changed title of this book to reflect that it contains Compute
|
|
extensions.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2013-04-17</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Added the server admin actions extension.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-05-30</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Added more descriptive information about the request body
|
|
attributes to the create server API operation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-05-02</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Added <code>SHUTOFF</code> to the list of server status values for
|
|
the list servers API operation.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Updated the description for the <code>SUSPENDED</code> server
|
|
status value for the list servers API operation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-04-24</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Updated to use color-coded syntax formatting in request and
|
|
response examples.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-03-25</date>
|
|
<revdescription>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Added descriptions of URI parameters and request body attributes
|
|
for API operations.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-02-14</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Updated the API version from v1.1 to v2.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>No longer use mimetype parameters to denote version.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-11-08</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Removed DRAFT designation.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-09-08</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added <parameter>limit</parameter> and
|
|
<parameter>marker</parameter> parameters to list
|
|
operations.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The rebuild action behaves the same as the create action: an
|
|
imageRef is used and a password can be specified.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added tenant and user_id attributes to server and image.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added vcpus attribute to flavors.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The flavorRef attribute is now used in the resize action.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-07-23</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added missing response examples for server update.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Ensure consistent HTTP status codes for all resources.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Clarifications on setting and changing a server password.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Minor updates to metadata section for clarity.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Discuss alternate links.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Removed version number from compute media types — use a
|
|
media type parameter instead.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Bought back the flavorRef and imageRef server attributes these are
|
|
now only used when creating a server.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Made the create image operation a server action.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added minDisk and minRam filters to flavor lists.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added minDisk and minRam attributes to images.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Asynchronous faults may now contain a time stamp.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Changes-since request returns an empty list rather than a
|
|
304.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added DELETED image status.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Fix content length in image create response sample.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Fixed bad request error code in server passwords.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Compact image, server, and flavor lists should contain IDs, names,
|
|
and links (Any kind of link can be included — not just self
|
|
links).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Changed metadata URI from .../meta to .../metadata for
|
|
consistency.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-06-29</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Renamed Primary IP to Access IP.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-06-23</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Many minor updates based on community feedback.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Removed sections on Content Compression, Persistent Connections,
|
|
and Caching — these are operator specific. Added section on
|
|
HTTP.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A Location header is returned when creating servers/images.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added filters to collection of image, servers, and flavors.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added asynchronous faults.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Updates to links and references. Remove serverRef, imageRef, and
|
|
flavorRef and instead embed one entity in another to provide
|
|
links.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added primary IP addresses.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added forbidden fault.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>We now use a single bookmark link for each entity regardless of
|
|
mimetype.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Collections are now sorted by create time.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Previous links are no longer required.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added the ability to create or update multiple metadata items
|
|
simultaneously.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Minor cleanups to server and image state machine.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Update to JSON collection format.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Replace integer IDs with UUIDs.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Removed <literal>affinityID</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-04-25</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Some minor cleanups in preparation for OpenStack Summit
|
|
discussion.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-03-11</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Many minor updates based on community feedback.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Updates to resource linking and references.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Better description of paginated collections.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Metadata supported in servers and images.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Dropped support for shared IP groups.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>IPs organized by network ID, versus showing only public and
|
|
private IPs.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Generalized affinity ID.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2011-02-09</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 Compute is a compute service that provides server capacity in the cloud.
|
|
Compute Servers come in different flavors of memory, cores, disk space, and CPU, and can
|
|
be provisioned in minutes. Interactions with Compute Servers can occur programmatically
|
|
via the OpenStack Compute API.</para>
|
|
<para>We welcome feedback, comments, and bug reports at <link
|
|
xlink:href="http://bugs.launchpad.net/nova">bugs.launchpad.net/nova</link>.</para>
|
|
<section xml:id="Intended_Audience-d1e85">
|
|
<title>Intended audience</title>
|
|
<para>This guide assists software developers who want to develop applications using the
|
|
OpenStack Compute API. To use this information, you should have access to an account
|
|
from an OpenStack Compute provider, and you should also be familiar with the
|
|
following concepts:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>OpenStack Compute service</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ReSTful web services</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>HTTP/1.1</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>JSON and/or XML data serialization formats</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Document_Change_History-d1e118">
|
|
<title>Document change history</title>
|
|
<para>This version of the Developer Guide replaces and obsoletes all previous versions.
|
|
The most recent changes are described in the table below:</para>
|
|
<?rax revhistory?>
|
|
<!-- Table generated in output from revision element in the book element -->
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Additional_Resources-d1e346">
|
|
<title>Additional resources</title>
|
|
<para>You can download the most current version of this document from the OpenStack Docs
|
|
website at <link xlink:href="http://docs.openstack.org">
|
|
http://docs.openstack.org</link>.</para>
|
|
</section>
|
|
</preface>
|
|
<chapter xml:id="General_API_Information-d1e436">
|
|
<title>General API information</title>
|
|
<para>The OpenStack Compute API is defined as a ReSTful HTTP service. The API takes
|
|
advantage of all aspects of the HTTP protocol (methods, URIs, media types, response
|
|
codes, etc.) and providers are free to use existing features of the protocol such as
|
|
caching, persistent connections, and content compression among others. For example,
|
|
providers who employ a caching layer may respond with a 203 when a request is served
|
|
from the cache instead of a 200. Additionally, providers may offer support for
|
|
conditional &GET; requests using ETags, or they may send a redirect in response to a
|
|
&GET; request. Clients should be written to account for these differences.</para>
|
|
<para>Providers can return information identifying requests in HTTP response headers, for
|
|
example, to facilitate communication between the provider and client users.</para>
|
|
<xi:include href="section_concepts.xml"/>
|
|
<section xml:id="Authentication-d1e444">
|
|
<title>Authentication</title>
|
|
<para>Each HTTP request against the OpenStack Compute system requires the inclusion of
|
|
specific authentication credentials. A single deployment may support multiple
|
|
authentication schemes (OAuth, Basic Auth, Token). The authentication scheme used is
|
|
determined by the provider of the OpenStack Compute system. Please contact your
|
|
provider to determine the best way to authenticate against this API.</para>
|
|
<note>
|
|
<para>Some authentication schemes may require that the API operate using SSL over
|
|
HTTP (HTTPS).</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="Request_Response_Types-d1e459">
|
|
<title>Request and response formats</title>
|
|
<para>The OpenStack Compute API supports both JSON and XML data serialization request
|
|
and response formats.</para>
|
|
<section xml:id="request-format">
|
|
<title>Request format</title>
|
|
<para>Use the <code>Content-Type</code> request header to specify the request
|
|
format. This header is required for operations that have a request body.</para>
|
|
<para>The syntax for the <code>Content-Type</code> header is:</para>
|
|
<programlisting>Content-Type: application/<replaceable>FORMAT</replaceable></programlisting>
|
|
<para>Where <replaceable>FORMAT</replaceable> is either <literal>json</literal> or
|
|
<literal>xml</literal>.</para>
|
|
</section>
|
|
<section xml:id="response-format">
|
|
<title>Response format</title>
|
|
<para>Use one of the following methods to specify the response format:</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><code>Accept</code> header</term>
|
|
<listitem>
|
|
<para>The syntax for the <code>Accept</code> header is:</para>
|
|
<programlisting>Accept: application/<replaceable>FORMAT</replaceable></programlisting>
|
|
<para>Where <replaceable>FORMAT</replaceable> is either
|
|
<literal>json</literal> or <literal>xml</literal>. The default
|
|
format is <literal>json</literal>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Query extension</term>
|
|
<listitem>
|
|
<para>Add an <literal>.xml</literal> or <literal>.json</literal>
|
|
extension to the request URI. For example, the
|
|
<literal>.xml</literal> extension in the following list servers
|
|
URI request specifies that the response body is to be returned in
|
|
XML format:</para>
|
|
<literallayout role="monospace">&GET; <replaceable>publicURL</replaceable>/servers.xml</literallayout>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>If you do not specify a response format, JSON is the default.</para>
|
|
<para>If the <code>Accept</code> header and the query extension specify conflicting
|
|
formats, the format specified in the query extension takes precedence. For
|
|
example, if the query extension is <literal>.xml</literal> and the
|
|
<code>Accept</code> header specifies <literal>application/json</literal>,
|
|
the response is returned in XML format.</para>
|
|
</section>
|
|
<section xml:id="request-response-examples">
|
|
<title>Request and response examples</title>
|
|
<para>You can serialize a response in a different format from the request
|
|
format.</para>
|
|
<para><xref linkend="JSON_req"/> and <xref linkend="ImageCreateFullResponse"/> show
|
|
a request body in JSON format and a response body in XML format.<note>
|
|
<para>Though this document shows them, XML support in requests and responses
|
|
has been deprecated for the Compute API v2 (stable) and v3
|
|
(experimental).</para>
|
|
</note></para>
|
|
<example xml:id="JSON_req">
|
|
<title>JSON request with headers</title>
|
|
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers HTTP/1.1
|
|
Host: servers.api.openstack.org
|
|
Content-Type: application/json
|
|
Accept: application/xml
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
|
|
<programlisting language="json"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<para><xref linkend="ImageCreateFullResponse"/> shows the headers and XML response
|
|
returned by the JSON request:</para>
|
|
<example xml:id="ImageCreateFullResponse">
|
|
<title>XML response with headers</title>
|
|
<literallayout role="monospace"><?db-font-size 70%?>HTTP/1.1 202 Accepted
|
|
Date: Mon, 23 Jul 2012 20:24:48 GMT
|
|
Content-Length: 582
|
|
Location: https://servers.api.openstack.org/v2/010101/servers/06dba123-2c7e-4639-bea0-09fbe219b056
|
|
Content-Type: application/xml
|
|
X-Compute-Request-Id: req-ab05045a-452f-4b46-be0d-86494da02a2b
|
|
Server: Jetty(8.0.y.z-SNAPSHOT)</literallayout>
|
|
<programlisting language="xml"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-resp.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<para>The following example shows an alternative method of achieving the same
|
|
result. The following request uses an URI extension of <literal>.xml</literal>
|
|
instead of an <code>Accept</code> header to request an XML response.</para>
|
|
<note>
|
|
<para>The XML response is not shown.</para>
|
|
</note>
|
|
<example xml:id="diff_serialization">
|
|
<title>JSON request with XML query extension for the response</title>
|
|
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers<emphasis role="bold">.xml</emphasis> HTTP/1.1
|
|
Host: servers.api.openstack.org
|
|
Content-Type: application/json
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
|
|
<programlisting language="json"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="LinksReferences">
|
|
<title>Links and references</title>
|
|
<para>Often resources need to refer to other resources. For example, when creating a
|
|
server, you must specify the image from which to build the server. You can specify
|
|
the image by providing an ID or a URL to a remote image. When providing an ID, it is
|
|
assumed that the resource exists in the current OpenStack deployment.</para>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>ID image reference: JSON request</title>
|
|
<programlisting language="json"><xi:include href="samples/server-post-req-short.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>ID image reference: XML request</title>
|
|
<programlisting language="xml"><xi:include href="samples/server-post-req-short.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Full image reference: JSON request</title>
|
|
<programlisting language="json"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Full image reference: XML request</title>
|
|
<programlisting language="xml"><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<para>For convenience, resources contain links to themselves. This allows a client to
|
|
easily obtain rather than construct resource URIs. The following types of link
|
|
relations are associated with resources:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A <code>self</code> link contains a versioned link to the resource. Use
|
|
these links when the link is followed immediately.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A <code>bookmark</code> link provides a permanent link to a resource that
|
|
is appropriate for long term storage.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>An <code>alternate</code> link can contain an alternate representation of
|
|
the resource. For example, an OpenStack Compute image might have an
|
|
alternate representation in the OpenStack Image service.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<note>
|
|
<para>The type attribute provides a hint as to the type of representation to expect
|
|
when following the link.</para>
|
|
</note>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Server with self links: JSON</title>
|
|
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/server-simple.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Server with self links: XML</title>
|
|
<programlisting language="xml"><xi:include href="samples/server-simple.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Server with alternate link: JSON</title>
|
|
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/image-simple.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Image with alternate link: XML</title>
|
|
<programlisting language="xml"><xi:include href="samples/image-simple.xml" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Paginated_Collections-d1e664">
|
|
<title>Paginated collections</title>
|
|
<para>To reduce load on the service, list operations return a maximum number of items at
|
|
a time. The maximum number of items returned is determined by the compute provider.
|
|
To navigate the collection, the <parameter>limit</parameter> and
|
|
<parameter>marker</parameter> parameters can be set in the URI. For
|
|
example:</para>
|
|
<programlisting>?<parameter>limit</parameter>=100&<parameter>marker</parameter>=1234</programlisting>
|
|
<para>The <parameter>marker</parameter> parameter is the ID of the last item in the
|
|
previous list. Items are sorted by create time in descending order. When a create
|
|
time is not available they are sorted by ID. The <parameter>limit</parameter>
|
|
parameter sets the page size. Both parameters are optional. If the client requests a
|
|
<parameter>limit</parameter> beyond that which is supported by the deployment an
|
|
overLimit (<errorcode>413</errorcode>) fault may be thrown. A marker with an invalid
|
|
ID returns a <errorname>badRequest</errorname> (<errorcode>400</errorcode>)
|
|
fault.</para>
|
|
<para>For convenience, collections are required to contain atom <literal>next</literal>
|
|
links. They may optionally also contain <literal>previous</literal> links. The last
|
|
page in the list does not contain a "next" link. The following examples illustrate
|
|
three pages in a collection of images. The first page was retrieved through a &GET;
|
|
to <literal>http://servers.api.openstack.org/v2/1234/images?limit=1</literal>. In
|
|
these examples, the <parameter>limit</parameter> parameter sets the page size to a
|
|
single item. Subsequent links honor the initial page size. Thus, a client can follow
|
|
links to traverse a paginated collection without having to input the
|
|
<parameter>marker</parameter> parameter.</para>
|
|
<example>
|
|
<title>Images collection: XML (first page)</title>
|
|
<programlisting language="xml"><xi:include href="samples/images-page1.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Images collection: JSON (first page)</title>
|
|
<programlisting language="json"><xi:include href="samples/images-page1.json" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Images collection: XML (second page)</title>
|
|
<programlisting language="xml"><xi:include href="samples/images-page2.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Images collection: JSON (second page)</title>
|
|
<programlisting language="json"><xi:include href="samples/images-page2.json" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Images collection: XML (last page)</title>
|
|
<programlisting language="xml"><xi:include href="samples/images-page3.xml" parse="text"/>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Images collection: JSON (last page)</title>
|
|
<programlisting language="json"><xi:include href="samples/images-page3.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>In JSON, members in a paginated collection are stored in a JSON array named after
|
|
the collection. A JSON object may also be used to hold members in cases where using
|
|
an associative array is more practical. Properties about the collection itself,
|
|
including links, are contained in an array with the name of the entity an underscore
|
|
(_) and <code>links</code>. The combination of the objects and arrays that start
|
|
with the name of the collection and an underscore represent the collection in JSON.
|
|
The approach allows for extensibility of paginated collections by allowing them to
|
|
be associated with arbitrary properties. It also allows collections to be embedded
|
|
in other objects as illustrated below. Here, a subset of metadata items are
|
|
presented within the image. Clients must follow the "next" link to retrieve the full
|
|
set of metadata.</para>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Paginated image metadata: XML</title>
|
|
<programlisting language="xml"><xi:include href="samples/image-meta-page1.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Paginated image metadata: JSON</title>
|
|
<programlisting language="json"><xi:include href="samples/image-meta-page1.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="ChangesSince">
|
|
<title>Efficient polling with the <parameter>Changes-Since</parameter> parameter</title>
|
|
<para>The ReST API allows you to poll for the status of certain operations by performing
|
|
a &GET; on various elements. Rather than re-downloading and re-parsing the full
|
|
status at each polling interval, your ReST client may use the
|
|
<parameter>changes-since</parameter> parameter to check for changes since a
|
|
previous request. The <parameter>changes-since</parameter> time is specified as an
|
|
<link xlink:href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601</link>
|
|
dateTime (2011-01-24T17:08Z). The form for the timestamp is CCYY-MM-DDThh:mm:ss. An
|
|
optional time zone may be written in by appending the form ±hh:mm which
|
|
describes the timezone as an offset from UTC. When the timezone is not specified
|
|
(2011-01-24T17:08), the UTC timezone is assumed. If nothing has changed since the
|
|
<parameter>changes-since</parameter> time, an empty list is returned. If data
|
|
has changed, only the items changed since the specified time are returned in the
|
|
response. For example, performing a &GET; against
|
|
https://api.servers.openstack.org/v2/224532/servers?<parameter>changes-since</parameter>=2011-01-24T17:08Z
|
|
would list all servers that have changed since Mon, 24 Jan 2011 17:08:00 UTC.</para>
|
|
<para>To allow clients to keep track of changes, the changes-since filter displays items
|
|
that have been <emphasis>recently</emphasis> deleted. Both images and servers
|
|
contain a <code>DELETED</code> status that indicates that the resource has been
|
|
removed. Implementations are not required to keep track of deleted resources
|
|
indefinitely, so sending a changes since time in the distant past may miss
|
|
deletions.</para>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Limits-d1e846">
|
|
<title>Limits</title>
|
|
<para>Accounts may be pre-configured with a 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. Limits are configured by operators and may differ from
|
|
one deployment of the OpenStack Compute service to another. Please contact your
|
|
provider to determine the limits that apply to your account or see <xref
|
|
linkend="ProgramaticLimits"/>. Your provider may be able to adjust your
|
|
account's limits if they are too low.</para>
|
|
<section xml:id="Rate_Limits-d1e862">
|
|
<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 human-readable limit is intended
|
|
for displaying in graphical user interfaces. The machine-processable form is
|
|
intended to be used directly by client applications.</para>
|
|
<para>The regular expression boundary matcher "^" for the rate limit takes effect
|
|
after the root URI path. For example, the regular expression ^/servers would
|
|
match the bolded portion of the following URI:
|
|
https://servers.api.openstack.org/v2/3542812<emphasis role="bold"
|
|
>/servers</emphasis>.</para>
|
|
<table rules="all">
|
|
<caption>Sample rate limits</caption>
|
|
<thead>
|
|
<tr>
|
|
<td>Verb</td>
|
|
<td>URI</td>
|
|
<td>RegEx</td>
|
|
<td>Default</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>&POST;</td>
|
|
<td>*</td>
|
|
<td>.*</td>
|
|
<td>120/min</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&POST;</td>
|
|
<td>*/servers</td>
|
|
<td>^/servers</td>
|
|
<td>120/min</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&PUT;</td>
|
|
<td>*</td>
|
|
<td>.*</td>
|
|
<td>120/min</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>*changes-since*</td>
|
|
<td>.*changes-since.*</td>
|
|
<td>120/min</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&DELETE;</td>
|
|
<td>*</td>
|
|
<td>.*</td>
|
|
<td>120/min</td>
|
|
</tr>
|
|
<tr>
|
|
<td>&GET;</td>
|
|
<td>*/os-fping*</td>
|
|
<td>^/os-fping</td>
|
|
<td>12/min</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para>Rate limits are applied in order relative to the verb, going from least to
|
|
most specific.</para>
|
|
<para>In the event a request exceeds the thresholds established for your account, a
|
|
<errorcode>413</errorcode> HTTP response is returned with a
|
|
<code>Retry-After</code> header to notify the client when they can attempt
|
|
to try again.</para>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Absolute_Limits-d1e994">
|
|
<title>Absolute limits</title>
|
|
<para>Absolute limits are specified as name/value pairs. The name of the absolute
|
|
limit uniquely identifies the limit within a deployment. Please consult your
|
|
provider for an exhaustive list of absolute value names. An absolute limit value
|
|
is always specified as an integer. The name of the absolute limit determines the
|
|
unit type of the integer value. For example, the name maxServerMeta implies that
|
|
the value is in terms of server metadata items.</para>
|
|
<table rules="all">
|
|
<caption>Sample absolute limits</caption>
|
|
<thead>
|
|
<tr>
|
|
<td>Name</td>
|
|
<td>Value</td>
|
|
<td>Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>maxTotalRAMSize</td>
|
|
<td>51200</td>
|
|
<td>Maximum total amount of RAM (MB)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>maxServerMeta</td>
|
|
<td>5</td>
|
|
<td>Maximum number of metadata items associated with a server</td>
|
|
</tr>
|
|
<tr>
|
|
<td>maxImageMeta</td>
|
|
<td>5</td>
|
|
<td>Maximum number of metadata items associated with an Image</td>
|
|
</tr>
|
|
<tr>
|
|
<td>maxPersonality</td>
|
|
<td>5</td>
|
|
<td>The maximum number of file path/content pairs that can be supplied
|
|
on server build</td>
|
|
</tr>
|
|
<tr>
|
|
<td>maxPersonalitySize</td>
|
|
<td>10240</td>
|
|
<td>The maximum size, in bytes, for each personality file</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="ProgramaticLimits">
|
|
<title>Determine limits programmatically</title>
|
|
<para>Applications can programmatically determine current account limits. For
|
|
information, see <link
|
|
xlink:href="http://developer.openstack.org/api-ref-compute-v2.html#compute_limits"
|
|
><citetitle>Limits</citetitle></link>.</para>
|
|
</section>
|
|
</section>
|
|
<section xml:id="Versions-d1e1193">
|
|
<title>Versions</title>
|
|
<para>The OpenStack Compute API uses both a URI and a MIME type versioning scheme. In
|
|
the URI scheme, the first element of the path contains the target version identifier
|
|
(e.g. https://servers.api.openstack.org/ v1.0/…). The MIME type versioning
|
|
scheme uses HTTP content negotiation where the <code>Accept</code> or
|
|
<code>Content-Type</code> headers contains a MIME type that identifies the
|
|
version (application/vnd.openstack.compute.v2+xml). A version MIME type is always
|
|
linked to a base MIME type (application/xml or application/json). If conflicting
|
|
versions are specified using both an HTTP header and a URI, the URI takes
|
|
precedence.</para>
|
|
<example>
|
|
<title>Request with MIME type versioning</title>
|
|
<literallayout class="monospaced">
|
|
GET /214412/images HTTP/1.1
|
|
Host: servers.api.openstack.org
|
|
Accept: application/vnd.openstack.compute.v2+xml
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
|
</literallayout>
|
|
</example>
|
|
<example>
|
|
<title>Request with URI versioning</title>
|
|
<literallayout class="monospaced">
|
|
GET /v2/214412/images HTTP/1.1
|
|
Host: servers.api.openstack.org
|
|
Accept: application/xml
|
|
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
|
|
</literallayout>
|
|
</example>
|
|
<note>
|
|
<para>The MIME type versioning approach allows for the creating of permanent links,
|
|
because the version scheme is not specified in the URI path:
|
|
https://api.servers.openstack.org/224532/servers/123.</para>
|
|
</note>
|
|
<?hard-pagebreak?>
|
|
<para>If a request is made without a version specified in the URI or via HTTP headers,
|
|
then a multiple-choices response (<returnvalue>300</returnvalue>) follows that
|
|
provides links and MIME types to available versions.</para>
|
|
<example>
|
|
<title>Multiple choices: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/choices.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Multiple choices: JSON response</title>
|
|
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/choices.json" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<para>New features and functionality that do not break API-compatibility are introduced
|
|
in the current version of the API as extensions (see the following section) and the
|
|
URI and MIME types remain unchanged. Features or functionality changes that would
|
|
necessitate a break in API-compatibility require a new version, which results in URI
|
|
and MIME type version being updated accordingly. When new API versions are released,
|
|
older versions are marked as <code>DEPRECATED</code>. Providers should work with
|
|
developers and partners to ensure there is adequate time to migrate to the new
|
|
version before deprecated versions are discontinued.</para>
|
|
<para>Your application can programmatically determine available API versions by
|
|
performing a &GET; on the root URL (i.e. with the version and everything to the
|
|
right of it truncated) returned from the authentication system.</para>
|
|
<para>You can also obtain additional information about a specific version by performing
|
|
a &GET; on the base version URL (such as,
|
|
<literal>https://servers.api.openstack.org/v2/</literal>). Version request URLs
|
|
must always end with a trailing slash (<literal>/</literal>). If you omit the slash,
|
|
the server might respond with a <returnvalue>302</returnvalue> redirection request.
|
|
Format extensions can be placed after the slash (such as,
|
|
<literal>https://servers.api.openstack.org/v2/.xml</literal>).</para>
|
|
<note>
|
|
<para>This special case does not hold true for other API requests. In general,
|
|
requests such as <literal>/servers.xml</literal> and
|
|
<literal>/servers/.xml</literal> are handled equivalently.</para>
|
|
</note>
|
|
<para>For examples of the list versions and get version details requests and responses,
|
|
see <link
|
|
xlink:href="http://developer.openstack.org/api-ref-compute-v2.html#compute_versions"
|
|
><citetitle>API versions</citetitle></link>.</para>
|
|
<para>The detailed version response contains pointers to both a human-readable and a
|
|
machine-processable description of the API service. The machine-processable
|
|
description is written in the Web Application Description Language (WADL).</para>
|
|
<note>
|
|
<para>If a discrepancy exists between the two references, the WADL is authoritative
|
|
as it contains the most accurate and up-to-date description of the API
|
|
service.</para>
|
|
</note>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Extensions-d1e1444">
|
|
<title>Extensions</title>
|
|
<para>The OpenStack Compute API is extensible. Extensions serve two purposes: They allow
|
|
the introduction of new features in the API without requiring a version change and
|
|
they allow the introduction of vendor specific niche functionality. Applications can
|
|
programmatically list available extensions by performing a &GET; on the
|
|
<uri>/extensions</uri> URI. Note that this is a versioned request — that
|
|
is, an extension available in one API version might not be available in
|
|
another.</para>
|
|
<para>Extensions may also be queried individually by their unique alias. This provides
|
|
the simplest method of checking if an extension is available because an unavailable
|
|
extension issues an <errorname>itemNotFound</errorname> (<errorcode>404</errorcode>)
|
|
response.</para>
|
|
<para>Extensions may define new data types, parameters, actions, headers, states, and
|
|
resources. In XML, additional elements and attributes can be defined. These elements
|
|
must be defined in the namespace for the extension. In JSON, the alias must be used.
|
|
The volumes element is defined in the <code>RS-CBS</code> namespace. Extended
|
|
headers are always prefixed with <code>X-</code> followed by the alias and a dash:
|
|
(<code>X-RS-CBS-HEADER1</code>). States and parameters must be prefixed with the
|
|
extension alias followed by a colon. For example, an image might be in the
|
|
<code>RS-PIE:PrepareShare</code> state.</para>
|
|
<important>
|
|
<para>Applications should ignore response data that contains extension elements. An
|
|
extended state should always be treated as an <code>UNKNOWN</code> state if the
|
|
application does not support the extension. Applications should also verify that
|
|
an extension is available before submitting an extended request.</para>
|
|
</important>
|
|
<example xml:id="ServersCBSX">
|
|
<title>Extended server: XML response</title>
|
|
<programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/ext-servers.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example xml:id="ServersCBSJ">
|
|
<title>Extended server: JSON response</title>
|
|
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/ext-servers.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example xml:id="CBSAX">
|
|
<title>Extended action: XML response</title>
|
|
<programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/ext-action.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example xml:id="CBSAJ">
|
|
<title>Extended action: JSON response</title>
|
|
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/ext-action.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Faults-d1e1724">
|
|
<title>Faults</title>
|
|
<section xml:id="Synchronous_Faults-d1e1729">
|
|
<title>Synchronous faults</title>
|
|
<para>When an error occurs at request time, the system also returns additional
|
|
information about the fault in the body of the response.</para>
|
|
<example>
|
|
<title>Fault: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/fault.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Fault: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/fault.json" parse="text"/></programlisting>
|
|
</example>
|
|
<para>The error code is returned in the body of the response for convenience. The
|
|
message section returns a human-readable message that is appropriate for display
|
|
to the end user. The details section is optional and may contain
|
|
information—for example, a stack trace—to assist in tracking down an
|
|
error. The detail section might or might not be appropriate for display to an
|
|
end user.</para>
|
|
<para>The root element of the fault (such as, computeFault) might change depending
|
|
on the type of error. The following is a list of possible elements along with
|
|
their associated error codes.</para>
|
|
<?hard-pagebreak?>
|
|
<table rules="all">
|
|
<caption>Fault elements and error codes</caption>
|
|
<thead>
|
|
<tr>
|
|
<td>Fault element</td>
|
|
<td>Associated error codes</td>
|
|
<td>Expected in all requests?</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>computeFault</td>
|
|
<td>500, 400, other codes possible</td>
|
|
<td align="center">&CHECK;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>notImplemented</td>
|
|
<td>501</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>serverCapacityUnavailable</td>
|
|
<td>503</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>serviceUnavailable</td>
|
|
<td>503</td>
|
|
<td align="center">&CHECK;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>badRequest</td>
|
|
<td>400</td>
|
|
<td align="center">&CHECK;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>unauthorized</td>
|
|
<td>401</td>
|
|
<td align="center">&CHECK;</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>forbidden</td>
|
|
<td>403</td>
|
|
<td align="center">&CHECK;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>resizeNotAllowed</td>
|
|
<td>403</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>itemNotFound</td>
|
|
<td>404</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>badMethod</td>
|
|
<td>405</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>backupOrResizeInProgress</td>
|
|
<td>409</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>buildInProgress</td>
|
|
<td>409</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>conflictingRequest</td>
|
|
<td>409</td>
|
|
<td/>
|
|
</tr>
|
|
<tr>
|
|
<td>overLimit</td>
|
|
<td>413</td>
|
|
<td align="center">&CHECK;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>badMediaType</td>
|
|
<td>415</td>
|
|
<td/>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<example>
|
|
<title>Item Not Found fault: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/notfound.json" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Item Not Found fault: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/notfound.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<para>From an XML schema perspective, all API faults are extensions of the base
|
|
ComputeAPIFault fault type. When working with a system that binds XML to actual
|
|
classes (such as JAXB), you should use <errorname>ComputeAPIFault</errorname> as
|
|
a catch-all if you do not want to distinguish between individual fault
|
|
types.</para>
|
|
<para>The <errorname>OverLimit</errorname> fault is generated when a rate limit
|
|
threshold is exceeded. For convenience, the fault adds a
|
|
<property>retryAfter</property> attribute that contains the content of the
|
|
Retry-After header in XML Schema 1.0 date/time format.</para>
|
|
<example>
|
|
<title>Over Limit fault: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/overlimit.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Over Limit fault: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/overlimit.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="Asynchronous_Faults-d1e2009">
|
|
<title>Asynchronous faults</title>
|
|
<para>An error may occur in the background while a server or image is being built or
|
|
while a server is executing an action. In these cases, the server or image is
|
|
placed in an <code>ERROR</code> state and the fault is embedded in the offending
|
|
server or image. Note that these asynchronous faults follow the same format as
|
|
the synchronous ones. The fault contains an error code, a human readable
|
|
message, and optional details about the error. Additionally, asynchronous faults
|
|
may also contain a created timestamp that specify when the fault
|
|
occurred.</para>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Server in error state: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/server-fault.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Server in error state: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/server-fault.json" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Image in error state: XML response</title>
|
|
<programlisting language="xml"><xi:include href="samples/image-fault.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Image in error state: JSON response</title>
|
|
<programlisting language="json"><xi:include href="samples/image-fault.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<section xml:id="compute_servers">
|
|
<title>Server concepts</title>
|
|
<section xml:id="List_Servers-d1e2078">
|
|
<title>Server status</title>
|
|
<para xml:id="id35836359">You can filter the list of servers by image, flavor, name,
|
|
and status through the respective query parameters.</para>
|
|
<para>Servers contain a status attribute that indicates the current server state.
|
|
You can filter on the server status when you complete a list servers request.
|
|
The server status is returned in the response body. The server status is one of
|
|
the following values:</para>
|
|
<itemizedlist xml:id="server_status">
|
|
<title>Server status values</title>
|
|
<listitem>
|
|
<para><code>ACTIVE</code>. The server is active.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>BUILDING</code>. The server has not finished the original build
|
|
process.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>DELETED</code>. The server is permanently deleted.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>ERROR</code>. The server is in error.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>HARD_REBOOT</code>. The server is hard rebooting. This is
|
|
equivalent to pulling the power plug on a physical server, plugging it
|
|
back in, and rebooting it.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>PASSWORD</code>. The password is being reset on the
|
|
server.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>PAUSED</code>. The server is paused and continues to run in frozen state.
|
|
The state of the server is stored in RAM.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>REBOOT</code>. The server is in a soft reboot state. A reboot
|
|
command was passed to the operating system.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>REBUILD</code>. The server is currently being rebuilt from an
|
|
image.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>RESCUED</code>. The server is in rescue mode. A rescue image
|
|
is running with the original server image attached.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>RESIZED</code>. The server is down while it performs a differential copy of data that changed during its initial copy.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>REVERT_RESIZE</code>. Because a server resize or migration failed, the destination server is
|
|
being cleaned up as the original source server restarts.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>SHUTOFF</code>. The virtual machine (VM) was powered down by the
|
|
user, but not through the OpenStack Compute API. For example, the user
|
|
issued a <code>shutdown -h</code> command from within the server
|
|
instance. If the OpenStack Compute manager detects that the VM was
|
|
powered down, it transitions the server instance to the SHUTOFF status.
|
|
If you use the OpenStack Compute API to restart the instance, the
|
|
instance might be deleted first, depending on the value in the
|
|
<parameter>shutdown_terminate</parameter> database field on the
|
|
Instance model.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>SOFT_DELETED</code>. The server is marked as deleted but the
|
|
disk images are still available to restore.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>STOPPED</code>. The server is powered off and the disk image
|
|
still persists.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>SUSPENDED</code>. The server is suspended either by request or
|
|
necessity. This status appears for only
|
|
XenServer/XCP, KVM, and ESXi hypervisors. Administrative users can suspend an
|
|
instance if it is infrequently used or to perform system maintenance.
|
|
When you suspend an instance, its VM state is stored on disk, all memory
|
|
is written to disk, and the virtual machine is stopped. Suspending an
|
|
instance is similar to placing a device in hibernation; memory and vCPUs
|
|
become available to create other instances.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>UNKNOWN</code>. The state of the server is unknown. Contact your
|
|
cloud provider.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><code>VERIFY_RESIZE</code>. The system awaits confirmation that the
|
|
server is operational after a move or resize.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The compute provisioning algorithm has an anti-affinity property that tries to distribute customer VMs across hosts. Under certain situations, VMs from the same
|
|
customer might be placed on the same host. The <property>hostId</property> property
|
|
represents the host that your server runs on and can be used to determine this
|
|
scenario if it is relevant to your application.</para>
|
|
<note>
|
|
<para>The <property>hostId</property> property is unique <emphasis>per account</emphasis> and
|
|
is not globally unique.</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="CreateServers">
|
|
<title>Server creation</title>
|
|
<informaltable frame="void">
|
|
<tbody>
|
|
<tr>
|
|
<td>Status Transition:</td>
|
|
<td>
|
|
<code>BUILD</code> &ARROW; <code>ACTIVE</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td/>
|
|
<td>
|
|
<code>BUILD</code> &ARROW; <code>ERROR</code> (on error)</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<para>When you create a server, the operation asynchronously provisions a new
|
|
server. The progress of this operation depends on several factors including
|
|
location of the requested image, network I/O, host load, and the selected
|
|
flavor. The progress of the request can be checked by performing a &GET; on
|
|
/servers/<parameter>id</parameter>, which returns a progress attribute (from
|
|
0% to 100% complete). The full URL to the newly created server is returned
|
|
through the <code>Location</code> header and is available as a <code>self</code>
|
|
and <code>bookmark</code> link in the server representation (See <xref
|
|
linkend="LinksReferences"/>). Note that when creating a server, only the
|
|
server ID, its links, and the administrative password are guaranteed to be
|
|
returned in the request. You can retrieve additional attributes by performing
|
|
subsequent &GET; operations on the server.</para>
|
|
</section>
|
|
<section xml:id="Server_Passwords-d1e2510">
|
|
<title>Server passwords</title>
|
|
<para>You can specify a password when you create the server through the optional
|
|
<property>adminPass</property> attribute. The specified password must meet
|
|
the complexity requirements set by your OpenStack Compute provider. The server
|
|
might enter an <code>ERROR</code> state if the complexity requirements are not
|
|
met. In this case, a client can issue a change password action to reset the
|
|
server password.</para>
|
|
<para>If a password is not specified, a randomly generated password is assigned and
|
|
returned in the response object. This password is guaranteed to meet the
|
|
security requirements set by the compute provider. For security reasons, the
|
|
password is not returned in subsequent &GET; calls.</para>
|
|
</section>
|
|
<section xml:id="Server_Metadata-d1e2529">
|
|
<title>Server metadata</title>
|
|
<para>Custom server metadata can also be supplied at launch time. The maximum size
|
|
of the metadata key and value is 255 bytes each. The maximum number of key-value
|
|
pairs that can be supplied per server is determined by the compute provider and
|
|
may be queried via the maxServerMeta absolute limit.</para>
|
|
</section>
|
|
<section xml:id="Server_Networks-d1e2530">
|
|
<title>Server networks</title>
|
|
<para>Networks to which the server connects can also be supplied at launch time. One
|
|
or more networks can be specified. User can also specify a specific port on the
|
|
network or the fixed IP address to assign to the server interface.</para>
|
|
</section>
|
|
<section xml:id="Server_Personality-d1e2543">
|
|
<title>Server personality</title>
|
|
<para>You can customize the personality of a server instance by injecting data into
|
|
its file system. For example, you might want to insert ssh keys, set
|
|
configuration files, or store data that you want to retrieve from inside the
|
|
instance. This feature provides a minimal amount of launch-time personalization.
|
|
If you require significant customization, create a custom image.</para>
|
|
<para>Follow these guidelines when you inject files:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The maximum size of the file path data is 255 bytes.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Encode the file contents as a Base64 string. The maximum size of the
|
|
file contents is determined by the compute provider and may vary based
|
|
on the image that is used to create the server</para>
|
|
<note>
|
|
<para>The maximum limit refers to the number of bytes in the decoded
|
|
data and not the number of characters in the encoded data.</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>You can inject text files only. You cannot inject binary or zip files
|
|
into a new build.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The maximum number of file path/content pairs that you can supply is
|
|
also determined by the compute provider and is defined by the
|
|
maxPersonality absolute limit.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The absolute limit, maxPersonalitySize, is a byte limit that is
|
|
guaranteed to apply to all images in the deployment. Providers can set
|
|
additional per-image personality limits.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>The file injection might not occur until after the server is built and
|
|
booted.</para>
|
|
<para>During file injection, any existing files that match specified files are
|
|
renamed to include the BAK extension appended with a time stamp. For example, if
|
|
the <filename>/etc/passwd</filename> file exists, it is backed up as
|
|
<filename>/etc/passwd.bak.1246036261.5785</filename>.</para>
|
|
<para>After file injection, personality files are accessible by only system
|
|
administrators. For example, on Linux, all files have root and the root group as
|
|
the owner and group owner, respectively, and allow user and group read access
|
|
only ( ).</para>
|
|
</section>
|
|
<section xml:id="Server_Primary_Addresses-d1e2558">
|
|
<title>Server access addresses</title>
|
|
<para>In a hybrid environment, the IP address of a server might not be controlled by
|
|
the underlying implementation. Instead, the access IP address might be part of
|
|
the dedicated hardware; for example, a router/NAT device. In this case, the
|
|
addresses provided by the implementation cannot actually be used to access the
|
|
server (from outside the local LAN). Here, a separate <firstterm>access
|
|
address</firstterm> may be assigned at creation time to provide access to
|
|
the server. This address may not be directly bound to a network interface on the
|
|
server and may not necessarily appear when a server's addresses are queried.
|
|
Nonetheless, clients that must access the server directly are encouraged to do
|
|
so via an access address. In the example below, an IPv4 address is assigned at
|
|
creation time.</para>
|
|
<example>
|
|
<title>Create server with access IP: XML request</title>
|
|
<programlisting language="xml"><xi:include href="samples/server-post-req-pip.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Create server with access IP: JSON request</title>
|
|
<programlisting language="json"><xi:include href="samples/server-post-req-pip.json" parse="text"/></programlisting>
|
|
</example>
|
|
<note>
|
|
<para>Both IPv4 and IPv6 addresses may be used as access addresses and both
|
|
addresses may be assigned simultaneously as illustrated below. Access
|
|
addresses may be updated after a server has been created. See <xref
|
|
linkend="compute_servers"/> for more details.</para>
|
|
</note>
|
|
<example>
|
|
<title>Create server with multiple access IPs: XML request</title>
|
|
<programlisting language="xml"><xi:include href="samples/server-post-req-pip2.xml" parse="text"/></programlisting>
|
|
</example>
|
|
<?hard-pagebreak?>
|
|
<example>
|
|
<title>Create server with multiple access IPs: JSON request</title>
|
|
<programlisting language="json"><xi:include href="samples/server-post-req-pip2.json" parse="text"/></programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="api-operations">
|
|
<title>API operations and extensions</title>
|
|
<para>For information about Compute API operations, see <link
|
|
xlink:href="http://developer.openstack.org/api-ref-compute-v2.html"
|
|
><citetitle>Compute API v2 (CURRENT)</citetitle></link>.</para>
|
|
<para>For information about Compute API extensions, see <link
|
|
xlink:href="http://developer.openstack.org/api-ref-compute-v2-ext.html"
|
|
><citetitle>Compute API v2 extensions (CURRENT)</citetitle></link>.</para>
|
|
</chapter>
|
|
</book>
|