528 lines
24 KiB
XML
528 lines
24 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
|
|
<!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
|
|
<!ENTITY ENDPOINT-US "https://identity.api.rackspacecloud.com/v1.1/">
|
|
<!ENTITY ENDPOINT-UK "https://lon.identity.api.rackspacecloud.com/v1.1/">
|
|
<!ENTITY ENDPOINT-US-20 "https://identity.api.rackspacecloud.com/v2.0/">
|
|
<!ENTITY ENDPOINT-UK-20 "https://lon.identity.api.rackspacecloud.com/v2.0/">
|
|
|
|
<!-- changing product name; define entity for product name rather than maintaining in text -->
|
|
<!ENTITY Checkmate "Orchestration">
|
|
<!ENTITY Deployment "Orchestration">
|
|
<!ENTITY DeploymentG "orchestration">
|
|
|
|
]>
|
|
<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" xml:id="orchestration-api-v1-reference"
|
|
version="5.0">
|
|
<title>OpenStack Orchestration API v1 Reference</title>
|
|
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<affiliation>
|
|
<orgname>OpenStack LLC</orgname>
|
|
</affiliation>
|
|
</author>
|
|
<copyright>
|
|
<year>2012</year>
|
|
<year>2013</year>
|
|
<holder>OpenStack LLC</holder>
|
|
</copyright>
|
|
<releaseinfo>API v1</releaseinfo>
|
|
<productname>OpenStack Orchestration</productname>
|
|
<pubdate>2013-10-03</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 Orchestration Application Programming
|
|
Interface (<abbrev>API</abbrev>). </para>
|
|
</abstract>
|
|
|
|
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<date>2013-10-03</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Initial review.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
</revhistory>
|
|
</info>
|
|
|
|
|
|
|
|
<chapter xml:id="overview">
|
|
<title>Overview</title>
|
|
<para> OpenStack &Deployment; is a service to deploy and
|
|
manage multiple composite cloud applications on OpenStack
|
|
clouds. Interactions with OpenStack &Deployment; occur
|
|
programmatically via the OpenStack &Deployment; API as
|
|
described in this document.</para>
|
|
<remark security="writeronly">Reviewer: Can you provide me
|
|
with a high-level Orchestration architecture diagram that
|
|
I can add to this section?</remark>
|
|
<para>We welcome feedback, comments, and bug reports at <link
|
|
xlink:href="https://bugs.launchpad.net/heat"
|
|
>https://bugs.launchpad.net/heat</link>.</para>
|
|
<section xml:id="Intended_Audience-d1e122">
|
|
<title>Intended Audience</title>
|
|
<para> This Reference is intended to assist support teams,
|
|
DevOps Engineers, and software developers who want to
|
|
manage cloud applications with non-trivial
|
|
architectures that leverage multiple OpenStack
|
|
services.</para>
|
|
<para>To use the information provided here, you should
|
|
first have a general understanding of the &Deployment;
|
|
service. You should also be familiar with: </para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Other OpenStack services applicable to your
|
|
cloud application architecture (Nova, Cinder,
|
|
Neutron, and so forth)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>RESTful web services</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>JSON and/or YAML data serialization
|
|
formats</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Document_Change_History-d1e166">
|
|
<title>Document Change History</title>
|
|
<para>This version of the Reference replaces and obsoletes
|
|
all previous versions. The most recent changes are
|
|
described in the table below:</para>
|
|
<?rax revhistory?>
|
|
</section>
|
|
<section xml:id="Additional_Resources-d1e532">
|
|
<title>Additional Resources</title>
|
|
<para>You can find information for developing templates in
|
|
the <citetitle>Heat Orchestration Template (HOT)
|
|
Specification</citetitle> at <link
|
|
xlink:href="http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec"
|
|
>http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec</link>. </para>
|
|
<para>You can find example templates at <link
|
|
xlink:href="https://github.com/heat-ci/heat-prod-templates/tree/master/example"
|
|
>https://github.com/heat-ci/heat-prod-templates/tree/master/example</link>. </para>
|
|
<para>For information about OpenStack services, refer to
|
|
<link xlink:href="http://www.rackspace.com/cloud/"
|
|
>http://docs.openstack.org</link>.</para>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="Concepts-d1e565">
|
|
<title>Concepts</title>
|
|
<?dbhtml stop-chunking?>
|
|
<para> To use &Deployment; effectively, you should understand
|
|
several key concepts: </para>
|
|
<section xml:id="Stack-d1e573">
|
|
<title>Stack</title>
|
|
<para>A stack is a group of resources (servers, load
|
|
balancers, databases, and so forth) combined to
|
|
fulfill a useful purpose. A stack is a set of
|
|
resources that can be deployed. A stack contains a
|
|
template and generates resources to run the
|
|
application framework or component specified.</para>
|
|
</section>
|
|
<section xml:id="Resource-d1e607">
|
|
<title>Resource</title>
|
|
<para>A resource is a template artifact that represents
|
|
some component of your desired architecture (a Nova
|
|
server, a group of scaled servers, a Cinder volume,
|
|
some configuration management system, and so
|
|
forth).</para>
|
|
</section>
|
|
<section xml:id="Blueprint-d1e588">
|
|
<title>Template</title>
|
|
<para>An &Deployment; template is a portable file, written
|
|
in a user-readable language, that describes how a set
|
|
of resources should be assembled and what software
|
|
should be installed in order to produce a working
|
|
deployment. The template specifies what resources
|
|
should be used, what attributes can be set, and other
|
|
parameters that are critical to the successful,
|
|
repeatable automation of a specific application
|
|
deployment.</para>
|
|
</section>
|
|
</chapter>
|
|
<chapter xml:id="General_API_Information-d1e843">
|
|
<title>General API Information</title>
|
|
<para> The &Deployment; API is implemented using a RESTful web
|
|
service interface. Like other OpenStack services, the
|
|
&Deployment; Service shares a common token-based
|
|
authentication system that allows seamless access between
|
|
products and services. </para>
|
|
<section xml:id="Authentication-d1e647">
|
|
<title>Authentication</title>
|
|
<para> The &Deployment; Service supports standard Keystone
|
|
authentication. For more information, refer to the
|
|
<citetitle>OpenStack Identity Service API v2.0
|
|
Reference</citetitle>. Please contact your
|
|
provider for additional details on how to authenticate
|
|
against this API.</para>
|
|
</section>
|
|
<section xml:id="Contract_Version-d1e825">
|
|
<title>Contract Version</title>
|
|
<para> The contract version denotes the data model and
|
|
behavior that the API supports. The current contract
|
|
version is v1. The requested contract version is
|
|
included in all request URLs. Different contract
|
|
versions of the API may be available at any given time
|
|
and are not guaranteed to be compatible with one
|
|
another. </para>
|
|
<example>
|
|
<title>Example Request URL (contract version in
|
|
<emphasis role="strong"
|
|
>bold</emphasis>)</title>
|
|
<programlisting>https://openstack.example.com/<emphasis role="strong">v1</emphasis>/1234</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>This document pertains to contract version
|
|
1.</para>
|
|
</note>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Request_Response_Types-d1e903">
|
|
<title>Request/Response Types</title>
|
|
<para> The &Deployment; API supports both the JSON and
|
|
YAML data serialization formats. The request format is
|
|
specified using the <code>Content-Type</code> header
|
|
and is <emphasis>required</emphasis> 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 a
|
|
<code>.yaml</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>
|
|
<table rules="all">
|
|
<caption>Response Formats</caption>
|
|
<?dbfo keep-together="always"?>
|
|
<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>YAML</td>
|
|
<td>application/yaml</td>
|
|
<td>.yaml</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<remark security="writeronly">Reviewer: need new examples
|
|
below: one for "Request with Headers: JSON" and one
|
|
for "Request with Headers: YAML".</remark>
|
|
<para security="writeronly">In the request example below,
|
|
notice that <parameter>Content-Type</parameter> is set
|
|
to <parameter>application/json</parameter>, but
|
|
<parameter>application/yaml</parameter> is
|
|
requested via the <parameter>Accept</parameter>
|
|
header:</para>
|
|
<para security="writeronly"
|
|
><?rax-fo keep-with-next?>Therefore a YAML response
|
|
format is returned:</para>
|
|
</section>
|
|
<section xml:id="datetimeformat">
|
|
<title>Date/Time Format</title>
|
|
<para> The &Deployment; Service uses an ISO-8601 compliant
|
|
date format for the display and consumption of
|
|
date/time values. </para>
|
|
<para>The system timezone is in UTC. MySQL converts
|
|
TIMESTAMP values from the current time zone to UTC for
|
|
storage, and back from UTC to the current time zone
|
|
for retrieval. This does not occur for other types,
|
|
such as DATETIME. </para>
|
|
<example>
|
|
<title>&Deployment; Service Date/Time Format</title>
|
|
<programlisting>yyyy-MM-dd'T'HH:mm:ssZ</programlisting>
|
|
<para>See the table below for a description of the
|
|
date/time format codes.</para>
|
|
<para>May 19th, 2011 at 8:07:08 AM, GMT-5 would have
|
|
the following format:</para>
|
|
<programlisting>2011-05-19T08:07:08-05:00</programlisting>
|
|
</example>
|
|
<table rules="all">
|
|
<caption>Explanation of 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>Z</td>
|
|
<td>RFC-822 timezone</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<section xml:id="DB_faults">
|
|
<title>Faults</title>
|
|
<para> The &Deployment; Service returns the following
|
|
error codes: </para>
|
|
<informaltable rules="all">
|
|
<thead>
|
|
<tr align="center">
|
|
|
|
<td colspan="1">Error Code</td>
|
|
<td colspan="3">Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
|
|
<td colspan="1">400 Bad Request</td>
|
|
<td colspan="3">Invalid parameter values,
|
|
un-parsable data, or missing required
|
|
values.</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td colspan="1">404 Not Found</td>
|
|
<td colspan="3">The stack or resource cannot
|
|
be found.</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td colspan="1">409 Conflict</td>
|
|
<td colspan="3">Invalid action is requested
|
|
for the current stack status; more than
|
|
one object exists for the specified
|
|
non-unique identifier.</td>
|
|
</tr>
|
|
<tr>
|
|
|
|
<td colspan="1">500 Internal Server Error</td>
|
|
<td colspan="3">Reverting the previously
|
|
failed action encountered an error, an
|
|
operation failed on one or more resources,
|
|
an unexpected error occurred.</td>
|
|
</tr>
|
|
</tbody>
|
|
</informaltable>
|
|
<remark security="writeronly">Reviewer: Need new
|
|
orchestration examples to replace the fault response
|
|
examples below.</remark>
|
|
<para security="writeronly">The following two <code>instanceFault</code>
|
|
examples show errors when the server has erred or
|
|
cannot perform the requested operation:</para>
|
|
<para security="writeronly"> 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 security="writeronly">The fault's root element (for example,
|
|
<code>instanceFault</code>) may change depending
|
|
on the type of error. </para>
|
|
<para security="writeronly"><?rax-fo keep-with-next?>The following two
|
|
<code>badRequest</code> examples show errors when
|
|
the volume size is invalid:</para>
|
|
<para security="writeronly"> The next two examples show
|
|
<code>itemNotFound</code> errors:</para>
|
|
</section>
|
|
<section xml:id="stack_status_dle264">
|
|
<title>Stack Status</title>
|
|
<para><?rax-fo keep-with-next?>Stacks and resources have a
|
|
state and a status as described in the lists that
|
|
follow:</para>
|
|
<para>State:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>INIT – (Resources only) The resource
|
|
has not been provisioned.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>CREATE – The stack/resource is
|
|
new.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>UPDATE – The stack/resource is
|
|
changed.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>DELETE – The stack/resource is
|
|
deleted.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ROLLBACK – A previously failed change
|
|
is being reverted.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SUSPEND – (Stacks only) The stack is
|
|
suspended.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>RESUME – (Stacks only) The stack is
|
|
resumed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>Status:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>IN-PROGRESS – The operation is in
|
|
progress.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>COMPLETE – The operation is
|
|
compete.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>FAILED – The operation failed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>So, if you create a new stack and something goes
|
|
wrong, your stack would be CREATE FAILED. One or more
|
|
resources of that stack may be in the following
|
|
states:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>INIT COMPLETE</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>CREATE FAILED</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>CREATE COMPLETE</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter xml:id="API_Operations_dle7023">
|
|
<title>API Operations</title>
|
|
<para>This section describes the Orchestration API
|
|
operations.</para>
|
|
<remark security="writeronly">Reviewer: please give me a list
|
|
of section titles to use for dividing up the API calls
|
|
into related sections.</remark>
|
|
<remark security="writeronly">Reviewer: please give me the Error Response Codes for
|
|
each of the API calls.</remark>
|
|
<wadl:resources
|
|
href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl"
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
|
|
</chapter>
|
|
<glossary>
|
|
<title>Glossary</title>
|
|
<glossentry xml:id="resource-d1e019">
|
|
<glossterm>resource</glossterm>
|
|
<glossdef>
|
|
<para>A resource is a template artifact that
|
|
represents some component of your desired
|
|
architecture (a Nova server, a group of scaled
|
|
servers, a Cinder volume, some configuration
|
|
management system, and so forth).</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry xml:id="stack-d1e017">
|
|
<glossterm>stack</glossterm>
|
|
<glossdef>
|
|
<para>A stack is a group of resources (servers, load
|
|
balancers, databases, and so forth) combined to
|
|
fulfill a useful purpose. A stack is a set of
|
|
resources that can be deployed. A stack contains a
|
|
template and generates resources to run the
|
|
application framework or component
|
|
specified.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
<glossentry xml:id="template-d1e016">
|
|
<glossterm>template</glossterm>
|
|
<glossdef>
|
|
<para>An &Deployment; template is a portable file,
|
|
written in a user-readable language, that
|
|
describes how a set of resources should be
|
|
assembled and what software should be installed in
|
|
order to produce a working deployment. The
|
|
template specifies what resources should be used,
|
|
what attributes can be set, and other parameters
|
|
that are critical to the successful, repeatable
|
|
automation of a specific application
|
|
deployment.</para>
|
|
</glossdef>
|
|
</glossentry>
|
|
</glossary>
|
|
</book>
|