openstack-attic/compute-api
Code Issues Proposed changes

Updated title of Compute Dev Guide to add extensions

Browse Source 
bug: #1156827

Change-Id: I8d1bc5cd81346a617c69424e0cee8858b4d80b37
author: Diane Fleming
This commit is contained in:
Diane Fleming
2013-04-27 10:08:43 -05:00
parent 3c1d1e60b1
commit ac34e393fa
11 changed files with 387 additions and 407 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
openstack-compute-api-2/src/os-compute-devguide.xml
View File

@@ -34,8 +34,10 @@
xmlns:html="http://www.w3.org/1999/xhtml" xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" version="5.0" xmlns:db="http://docbook.org/ns/docbook" version="5.0"
xml:id="os-cs-devguide"> xml:id="os-cs-devguide">
<title>OpenStack Compute Developer Guide</title> <title>OpenStack Compute and Extensions Developer Guide</title>
<titleabbrev>OpenStack Compute Dev Guide</titleabbrev> <?rax title.font.size="32px"?>
<titleabbrev>OpenStack Compute and Extensions Dev
Guide</titleabbrev>
<info> <info>
<author> <author>
<personname> <personname>
@@ -43,7 +45,7 @@
<surname/> <surname/>
</personname> </personname>
<affiliation> <affiliation>
<orgname>OpenStack LLC</orgname> <orgname>OpenStack Foundation</orgname>
</affiliation> </affiliation>
</author> </author>
<copyright> <copyright>
@@ -55,8 +57,8 @@
<holder>OpenStack Foundation</holder> <holder>OpenStack Foundation</holder>
</copyright> </copyright>
<releaseinfo>API v2</releaseinfo> <releaseinfo>API v2</releaseinfo>
<productname>OpenStack Compute</productname> <productname>OpenStack Compute and Extensions</productname>
<pubdate>2012-05-30</pubdate> <pubdate/>
<legalnotice role="apache2"> <legalnotice role="apache2">
<annotation> <annotation>
<remark>Copyright details are filled in by the <remark>Copyright details are filled in by the
@@ -70,6 +72,19 @@
(<abbrev>API</abbrev>). </para> (<abbrev>API</abbrev>). </para>
</abstract> </abstract>
<revhistory> <revhistory>
<revision>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<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> <revision>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... --> <!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<date>2013-04-17</date> <date>2013-04-17</date>
@@ -77,8 +92,9 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Added <xref <para>Added <xref
linkend="ext-os-admin-actions" linkend="ext-os-admin-actions"/> to
/> to document the server admin actions extension.</para> document the server admin actions
extension.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@@ -176,8 +192,8 @@
parameters to list operations. </para> parameters to list operations. </para>
</listitem> </listitem>
<listitem> <listitem>
<para> The rebuild action behaves just <para>The rebuild action behaves just like
like create: an imageRef is used and a create: an imageRef is used and a
password may be specified. </para> password may be specified. </para>
</listitem> </listitem>
<listitem> <listitem>
@@ -189,8 +205,8 @@
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> We now use a flavorRef in the <para>We now use a flavorRef in the resize
resize action. </para> action. </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@@ -333,8 +349,8 @@
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> Collections are now sorted by <para>Collections are now sorted by create
create time. </para> time. </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Previous links are no longer <para>Previous links are no longer
@@ -358,9 +374,8 @@
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> Removed affinityID, this will <para>Removed affinityID, this will likely
likely come in as an extension. come in as an extension. </para>
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</revdescription> </revdescription>
@@ -426,8 +441,8 @@
</info> </info>
<chapter xml:id="Overview-d1e71"> <preface xml:id="preface">
<title>Overview</title> <title>Preface</title>
<para>OpenStack Compute is a compute service that provides <para>OpenStack Compute is a compute service that provides
server capacity in the cloud. Compute Servers come in server capacity in the cloud. Compute Servers come in
different flavors of memory, cores, disk space, and CPU, different flavors of memory, cores, disk space, and CPU,
@@ -477,66 +492,8 @@
xlink:href="http://docs.openstack.org"> xlink:href="http://docs.openstack.org">
http://docs.openstack.org</link>. </para> http://docs.openstack.org</link>. </para>
</section> </section>
</chapter> </preface>
<chapter xml:id="Concepts-d1e369">
<?dbhtml stop-chunking?>
<title>Concepts</title>
<para> To use the OpenStack Compute API effectively, you
should understand several key concepts: </para>
<section xml:id="Server-d1e379">
<title>Server</title>
<para> A server is a virtual machine instance in the
compute system. Flavor and image are requisite
elements when creating a server. </para>
</section>
<section xml:id="Flavor-d1e388">
<title>Flavor</title>
<para> A flavor is an available hardware configuration for
a server. Each flavor has a unique combination of disk
space, memory capacity and priority for CPU time.
</para>
</section>
<section xml:id="Image-d1e398">
<title>Image</title>
<para> An image is a collection of files used to create or
rebuild a server. Operators provide a number of
pre-built OS images by default. You may also create
custom images from cloud servers you have launched.
These custom images are useful for backup purposes or
for producing “gold” server images if you plan to
deploy a particular server configuration frequently.
</para>
</section>
<section xml:id="Reboot-d1e407">
<title>Reboot</title>
<para> The reboot function allows for either a soft or
hard reboot of a server. With a soft reboot, the
operating system is signaled to restart, which allows
for a graceful shutdown of all processes. A hard
reboot is the equivalent of power cycling the server.
The virtualization platform should ensure that the
reboot action has completed successfully even in cases
in which the underlying domain/vm is paused or
halted/stopped. </para>
</section>
<section xml:id="Rebuild-d1e416">
<title>Rebuild</title>
<para> The rebuild function removes all data on the server
and replaces it with the specified image. Server ID
and IP addresses remain the same. </para>
</section>
<section xml:id="Resize-d1e425">
<title>Resize</title>
<para> The resize function converts an existing server to
a different flavor, in essence, scaling the server up
or down. The original server is saved for a period of
time to allow rollback if there is a problem. All
resizes should be tested and explicitly confirmed, at
which time the original server is removed. All resizes
are automatically confirmed after 24 hours if they are
not confirmed or reverted. </para>
</section>
</chapter>
<chapter xml:id="General_API_Information-d1e436"> <chapter xml:id="General_API_Information-d1e436">
<title>General API Information</title> <title>General API Information</title>
<para>The OpenStack Compute API is defined as a ReSTful HTTP <para>The OpenStack Compute API is defined as a ReSTful HTTP
@@ -551,9 +508,10 @@
&GET; requests using ETags, or they may send a redirect in &GET; requests using ETags, or they may send a redirect in
response to a &GET; request. Clients should be written to response to a &GET; request. Clients should be written to
account for these differences. </para> account for these differences. </para>
<para> Providers may return information identifying requests <para>Providers can return information identifying requests in
in HTTP response headers, for example, to facilitate HTTP response headers, for example, to facilitate
communication between the provider and client users. </para> communication between the provider and client users. </para>
<xi:include href="section_concepts.xml"/>
<section xml:id="Authentication-d1e444"> <section xml:id="Authentication-d1e444">
<title>Authentication</title> <title>Authentication</title>
<para>Each HTTP request against the OpenStack Compute <para>Each HTTP request against the OpenStack Compute
@@ -565,27 +523,25 @@
system. Please contact your provider to determine the system. Please contact your provider to determine the
best way to authenticate against this API. </para> best way to authenticate against this API. </para>
<note> <note>
<para> Some authentication schemes may require that <para>Some authentication schemes may require that the
the API operate using SSL over HTTP (HTTPS). API operate using SSL over HTTP (HTTPS). </para>
</para>
</note> </note>
</section> </section>
<section xml:id="Request_Response_Types-d1e459"> <section xml:id="Request_Response_Types-d1e459">
<title>Request/Response Types</title> <title>Request/Response Types</title>
<para> The OpenStack Compute API supports both the JSON <para>The OpenStack Compute API supports both the JSON and
and XML data serialization formats. The request format XML data serialization formats. The request format is
is specified using the <code>Content-Type</code> specified using the <code>Content-Type</code> header
header and is required for operations that have a and is required for operations that have a request
request body. The response format can be specified in body. The response format can be specified in requests
requests using either the <code>Accept</code> header using either the <code>Accept</code> header or adding
or adding an .xml or .json extension to the request an .xml or .json extension to the request URI. Note
URI. Note that it is possible for a response to be that it is possible for a response to be serialized
serialized using a format different from the request using a format different from the request (see example
(see example below). If no response format is below). If no response format is specified, JSON is
specified, JSON is the default. If conflicting formats the default. If conflicting formats are specified
are specified using both an <code>Accept</code> header using both an <code>Accept</code> header and a query
and a query extension, the query extension takes extension, the query extension takes precedence. </para>
precedence. </para>
<table rules="all"> <table rules="all">
<caption>JSON and XML Response Formats</caption> <caption>JSON and XML Response Formats</caption>
<thead> <thead>
@@ -748,10 +704,10 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
(<errorcode>413</errorcode>) fault may be thrown. (<errorcode>413</errorcode>) fault may be thrown.
A marker with an invalid ID will return a badRequest A marker with an invalid ID will return a badRequest
(<errorcode>400</errorcode>) fault. </para> (<errorcode>400</errorcode>) fault. </para>
<para> For convenience, collections are required to <para>For convenience, collections are required to contain
contain atom "next" links. They may optionally also atom "next" links. They may optionally also contain
contain "previous" links. The last page in the list "previous" links. The last page in the list will not
will not contain a "next" link. The following examples contain a "next" link. The following examples
illustrate three pages in a collection of images. The illustrate three pages in a collection of images. The
first page was retrieved via a &GET; to first page was retrieved via a &GET; to
http://servers.api.openstack.org/v2/1234/images?limit=1. http://servers.api.openstack.org/v2/1234/images?limit=1.
@@ -764,9 +720,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Images Collection, First Page: XML</title> <title>Images Collection, First Page: XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/images-page1.xml" parse="text"/></programlisting>
<xi:include href="samples/images-page1.xml" parse="text"/>
</programlisting>
</example> </example>
<example> <example>
<title>Images Collection, First Page: JSON</title> <title>Images Collection, First Page: JSON</title>
@@ -775,9 +729,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Images Collection, Second Page: XML</title> <title>Images Collection, Second Page: XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/images-page2.xml" parse="text"/></programlisting>
<xi:include href="samples/images-page2.xml" parse="text"/>
</programlisting>
</example> </example>
<example> <example>
<title>Images Collection, Second Page: JSON</title> <title>Images Collection, Second Page: JSON</title>
@@ -939,8 +891,8 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
</tr> </tr>
</tbody> </tbody>
</table> </table>
<para> Rate limits are applied in order relative to <para>Rate limits are applied in order relative to the
the verb, going from least to most specific. For verb, going from least to most specific. For
example, although the threshold for &POST; to example, although the threshold for &POST; to
*/servers is 50 per day, one cannot &POST; to */servers is 50 per day, one cannot &POST; to
*/servers more than 10 times within a single */servers more than 10 times within a single
@@ -1093,9 +1045,9 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
</literallayout> </literallayout>
</example> </example>
<note> <note>
<para> The MIME type versioning approach allows for <para>The MIME type versioning approach allows for the
the creating of permanent links, because the creating of permanent links, because the version
version scheme is not specified in the URI path: scheme is not specified in the URI path:
https://api.servers.openstack.org/224532/servers/123. https://api.servers.openstack.org/224532/servers/123.
</para> </para>
</note> </note>
@@ -1106,9 +1058,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
providing links and MIME types to available versions. </para> providing links and MIME types to available versions. </para>
<example> <example>
<title>Multiple Choices Response: XML</title> <title>Multiple Choices Response: XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/choices.xml" parse="text"/></programlisting>
<xi:include href="samples/choices.xml" parse="text"/>
</programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
@@ -1159,16 +1109,12 @@ Host: servers.api.openstack.org
body.</para> body.</para>
<example> <example>
<title>Versions List Response: XML</title> <title>Versions List Response: XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/versions.xml" parse="text"/></programlisting>
<xi:include href="samples/versions.xml" parse="text"/>
</programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Versions List Response: Atom</title> <title>Versions List Response: Atom</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/versions-atom.xml" parse="text"/></programlisting>
<xi:include href="samples/versions-atom.xml" parse="text"/>
</programlisting>
</example> </example>
<example> <example>
<title>Versions List Response: JSON</title> <title>Versions List Response: JSON</title>
@@ -1177,7 +1123,7 @@ Host: servers.api.openstack.org
<?hard-pagebreak?> <?hard-pagebreak?>
<para>You can also obtain additional information about a <para>You can also obtain additional information about a
specific version by performing a &GET; on the base specific version by performing a &GET; on the base
version URL (e.g. version URL (such as,
https://servers.api.openstack.org/v2/). Version https://servers.api.openstack.org/v2/). Version
request URLs should always end with a trailing slash request URLs should always end with a trailing slash
(/). If the slash is omitted, the server may respond (/). If the slash is omitted, the server may respond
@@ -1213,16 +1159,12 @@ Host: servers.api.openstack.org/v2/
body</para> body</para>
<example> <example>
<title>Version Details Response: XML</title> <title>Version Details Response: XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/version.xml" parse="text"/></programlisting>
<xi:include href="samples/version.xml" parse="text"/>
</programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Version Details Response: Atom</title> <title>Version Details Response: Atom</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/version-atom.xml" parse="text"/></programlisting>
<xi:include href="samples/version-atom.xml" parse="text"/>
</programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
@@ -1284,18 +1226,16 @@ Host: servers.api.openstack.org/v2/
(<errorcode>400</errorcode>), badMethod (<errorcode>400</errorcode>), badMethod
(<errorcode>405</errorcode>), overLimit (<errorcode>405</errorcode>), overLimit
(<errorcode>413</errorcode>) </simpara> (<errorcode>413</errorcode>) </simpara>
<para> This operation does not require a request body. <para>This operation does not require a request body. Each
Each extension is identified by two unique extension is identified by two unique identifiers, a
identifiers, a <property>namespace</property> and an <property>namespace</property> and an
<property>alias</property>. Additionally an <property>alias</property>. Additionally an
extension contains documentation links in various extension contains documentation links in various
formats. </para> formats. </para>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Extensions Response: XML</title> <title>Extensions Response: XML</title>
<programlisting language="xml"><?db-font-size 90%?> <programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/extensions.xml" parse="text"/></programlisting>
<xi:include href="samples/extensions.xml" parse="text"/>
</programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
@@ -1303,9 +1243,9 @@ Host: servers.api.openstack.org/v2/
<programlisting language="json"><?db-font-size 90%?><xi:include href="samples/extensions.json" parse="text"/></programlisting> <programlisting language="json"><?db-font-size 90%?><xi:include href="samples/extensions.json" parse="text"/></programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<para> Extensions may also be queried individually by <para>Extensions may also be queried individually by their
their unique alias. This provides the simplest method unique alias. This provides the simplest method of
of checking if an extension is available as an checking if an extension is available as an
unavailable extension will issue an itemNotFound unavailable extension will issue an itemNotFound
(<errorcode>404</errorcode>) response. </para> (<errorcode>404</errorcode>) response. </para>
<informaltable rules="all"> <informaltable rules="all">
@@ -1343,9 +1283,7 @@ Host: servers.api.openstack.org/v2/
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Extension Response: xml</title> <title>Extension Response: xml</title>
<programlisting language="xml"><?db-font-size 90%?> <programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/extension.xml" parse="text"/></programlisting>
<xi:include href="samples/extension.xml" parse="text"/>
</programlisting>
</example> </example>
<example> <example>
<title>Extension Response: JSON</title> <title>Extension Response: JSON</title>
@@ -1383,9 +1321,7 @@ Host: servers.api.openstack.org/v2/
</important> </important>
<example xml:id="ServersCBSX"> <example xml:id="ServersCBSX">
<title>Extended Server Response: XML</title> <title>Extended Server Response: XML</title>
<programlisting language="xml"><?db-font-size 90%?> <programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/ext-servers.xml" parse="text"/></programlisting>
<xi:include href="samples/ext-servers.xml" parse="text"/>
</programlisting>
</example> </example>
<example xml:id="ServersCBSJ"> <example xml:id="ServersCBSJ">
<title>Extended Server Response: JSON</title> <title>Extended Server Response: JSON</title>
@@ -1393,9 +1329,7 @@ Host: servers.api.openstack.org/v2/
</example> </example>
<example xml:id="CBSAX"> <example xml:id="CBSAX">
<title>Extended Action: XML</title> <title>Extended Action: XML</title>
<programlisting language="xml"><?db-font-size 90%?> <programlisting language="xml"><?db-font-size 90%?><xi:include href="samples/ext-action.xml" parse="text"/></programlisting>
<xi:include href="samples/ext-action.xml" parse="text"/>
</programlisting>
</example> </example>
<example xml:id="CBSAJ"> <example xml:id="CBSAJ">
<title>Extended Action: JSON</title> <title>Extended Action: JSON</title>
@@ -1407,11 +1341,11 @@ Host: servers.api.openstack.org/v2/
<title>Faults</title> <title>Faults</title>
<section xml:id="Synchronous_Faults-d1e1729"> <section xml:id="Synchronous_Faults-d1e1729">
<title>Synchronous Faults</title> <title>Synchronous Faults</title>
<para> When an error occurs at request time, the <para>When an error occurs at request time, the system
system will return an HTTP error response code will return an HTTP error response code denoting
denoting the type of error. The system will also the type of error. The system will also return
return additional information about the fault in additional information about the fault in the body
the body of the response. </para> of the response. </para>
<example> <example>
<title>Fault Response: XML</title> <title>Fault Response: XML</title>
<programlisting language="xml"><xi:include href="samples/fault.xml" parse="text"/></programlisting> <programlisting language="xml"><xi:include href="samples/fault.xml" parse="text"/></programlisting>
@@ -2197,16 +2131,12 @@ Host: servers.api.openstack.org/v2/
<example> <example>
<title>Creating a Server with a Access IP: <title>Creating a Server with a Access IP:
XML</title> XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/server-post-req-pip.xml" parse="text"/></programlisting>
<xi:include href="samples/server-post-req-pip.xml" parse="text"/>
</programlisting>
</example> </example>
<example> <example>
<title>Creating a Server with a Access IP: <title>Creating a Server with a Access IP:
JSON</title> JSON</title>
<programlisting language="json"> <programlisting language="json"><xi:include href="samples/server-post-req-pip.json" parse="text"/></programlisting>
<xi:include href="samples/server-post-req-pip.json" parse="text"/>
</programlisting>
</example> </example>
<para>Note that both IPv4 and IPv6 addresses may <para>Note that both IPv4 and IPv6 addresses may
be used as access addresses and both addresses be used as access addresses and both addresses
@@ -2217,17 +2147,13 @@ Host: servers.api.openstack.org/v2/
<example> <example>
<title>Creating a Server with Multiple Access <title>Creating a Server with Multiple Access
IPs: XML</title> IPs: XML</title>
<programlisting language="xml"> <programlisting language="xml"><xi:include href="samples/server-post-req-pip2.xml" parse="text"/></programlisting>
<xi:include href="samples/server-post-req-pip2.xml" parse="text"/>
</programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<example> <example>
<title>Creating a Server with Multiple Access <title>Creating a Server with Multiple Access
IPs: JSON</title> IPs: JSON</title>
<programlisting language="json"> <programlisting language="json"><xi:include href="samples/server-post-req-pip2.json" parse="text"/></programlisting>
<xi:include href="samples/server-post-req-pip2.json" parse="text"/>
</programlisting>
</example> </example>
</section> </section>
</section> </section>

7
openstack-compute-api-2/src/samples/choices.xml
View File

@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<choices xmlns="http://docs.openstack.org/common/api/v1.0" <choices xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"> xmlns:atom="http://www.w3.org/2005/Atom">
<version id="v1.0" status="DEPRECATED"> <version id="v1.0" status="DEPRECATED">
@@ -11,7 +10,8 @@
</media-types> </media-types>
<atom:link rel="self" <atom:link rel="self"
href="http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/> href="http://servers.api.openstack.org/v1.0/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
/>
</version> </version>
<version id="v2" status="CURRENT"> <version id="v2" status="CURRENT">
@@ -23,6 +23,7 @@
</media-types> </media-types>
<atom:link rel="self" <atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/> href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
/>
</version> </version>
</choices> </choices>

38
openstack-compute-api-2/src/samples/ext-servers.xml
View File

@@ -1,29 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<servers xmlns="http://docs.openstack.org/compute/api/v1.1" <servers xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom"> xmlns:atom="http://www.w3.org/2005/Atom">
<server id="52415800-8b69-11e0-9b19-734f6af67565" <server id="52415800-8b69-11e0-9b19-734f6af67565" tenant_id="1234"
tenant_id="1234" user_id="5678" user_id="5678" name="sample-server" status="BUILD"
name="sample-server" status="BUILD"
progress="60" hostId="e4d909c290d0fb1ca068ffaddf22cbd0" progress="60" hostId="e4d909c290d0fb1ca068ffaddf22cbd0"
updated="2010-10-10T12:00:00Z" updated="2010-10-10T12:00:00Z" created="2010-08-10T12:00:00Z"
created="2010-08-10T12:00:00Z" accessIPv4="67.23.10.132" accessIPv6="::babe:67.23.10.132">
accessIPv4="67.23.10.132"
accessIPv6="::babe:67.23.10.132">
<image id="52415800-8b69-11e0-9b19-734f6f006e54"> <image id="52415800-8b69-11e0-9b19-734f6f006e54">
<atom:link <atom:link rel="self"
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/> href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
<atom:link <atom:link rel="bookmark"
rel="bookmark" href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/> />
</image> </image>
<flavor id="52415800-8b69-11e0-9b19-734f216543fd"> <flavor id="52415800-8b69-11e0-9b19-734f216543fd">
<atom:link <atom:link rel="self"
rel="self"
href="http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/> href="http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
<atom:link <atom:link rel="bookmark"
rel="bookmark" href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/> />
</flavor> </flavor>
<metadata> <metadata>
<meta key="Server Label">Web Head 1</meta> <meta key="Server Label">Web Head 1</meta>
@@ -41,18 +36,17 @@
<ip version="6" addr="::babe:10.176.42.16"/> <ip version="6" addr="::babe:10.176.42.16"/>
</network> </network>
</addresses> </addresses>
<atom:link <atom:link rel="self"
rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/> href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
<atom:link <atom:link rel="bookmark"
rel="bookmark"
href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/> href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
<volumes <volumes
xmlns="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0"> xmlns="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0">
<volume name="OS" <volume name="OS"
href="https://cbs.api.rackspacecloud.com/12934/volumes/19"/> href="https://cbs.api.rackspacecloud.com/12934/volumes/19"/>
<volume name="Work" <volume name="Work"
href="https://cbs.api.rackspacecloud.com/12934/volumes/23"/> href="https://cbs.api.rackspacecloud.com/12934/volumes/23"
/>
</volumes> </volumes>
</server> </server>
</servers> </servers>

26
openstack-compute-api-2/src/samples/extension.xml
View File

@@ -1,24 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="http://docs.openstack.org/common/api/v1.0"
<extension
xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom"
name="Public Image Extension" name="Public Image Extension"
namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0" namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0"
alias="RS-PIE" alias="RS-PIE" updated="2011-01-22T13:25:27-06:00">
updated="2011-01-22T13:25:27-06:00"> <description> Adds the capability to share an image with other
users. </description>
<description> <atom:link rel="describedby" type="application/pdf"
Adds the capability to share an image with other users.
</description>
<atom:link
rel="describedby"
type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/> href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
<atom:link href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
rel="describedby" />
type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"/>
</extension> </extension>

42
openstack-compute-api-2/src/samples/extensions.xml
View File

@@ -1,43 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<extensions xmlns="http://docs.openstack.org/common/api/v1.0" <extensions xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"> xmlns:atom="http://www.w3.org/2005/Atom">
<extension name="Public Image Extension"
<extension
name="Public Image Extension"
namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0" namespace="http://docs.rackspacecloud.com/servers/api/ext/pie/v1.0"
alias="RAX-PIE" alias="RAX-PIE" updated="2011-01-22T13:25:27-06:00">
updated="2011-01-22T13:25:27-06:00"> <description> Adds the capability to share an image with other
users. </description>
<description> <atom:link rel="describedby" type="application/pdf"
Adds the capability to share an
image with other users.
</description>
<atom:link rel="describedby"
type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/> href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie-20111111.pdf"/>
<atom:link rel="describedby" <atom:link rel="describedby"
type="application/vnd.sun.wadl+xml" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"/> href="http://docs.rackspacecloud.com/servers/api/ext/cs-pie.wadl"
/>
</extension> </extension>
<extension name="Cloud Block Storage"
<extension
name="Cloud Block Storage"
namespace="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0" namespace="http://docs.rackspacecloud.com/servers/api/ext/cbs/v1.0"
alias="RAX-CBS" alias="RAX-CBS" updated="2011-01-12T11:22:33-06:00">
updated="2011-01-12T11:22:33-06:00" <description> Allows mounting cloud block storage volumes.</description>
> <atom:link rel="describedby" type="application/pdf"
<description>
Allows mounting cloud block
storage volumes.
</description>
<atom:link rel="describedby"
type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs-20111201.pdf"/> href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs-20111201.pdf"/>
<atom:link rel="describedby" <atom:link rel="describedby"
type="application/vnd.sun.wadl+xml" type="application/vnd.sun.wadl+xml"
href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs.wadl"/> href="http://docs.rackspacecloud.com/servers/api/ext/cs-cbs.wadl"
/>
</extension> </extension>
</extensions> </extensions>

15
openstack-compute-api-2/src/samples/images-page1.xml
View File

@@ -1,13 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<images xmlns="http://docs.openstack.org/compute/api/v1.1" <images xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom"> xmlns:atom="http://www.w3.org/2005/Atom">
<image id="52415800-8b69-11e0-9b19-734f6f006e54" <image id="52415800-8b69-11e0-9b19-734f6f006e54" name="CentOS 5.2">
name="CentOS 5.2"> <atom:link rel="self"
<atom:link href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
rel="self" />
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
</image> </image>
<atom:link <atom:link rel="next"
rel="next" href="http://servers.api.openstack.org/v2/1234/images?limit=1&amp;marker=52415800-8b69-11e0-9b19-734f6f006e54"
href="http://servers.api.openstack.org/v2/1234/images?limit=1&amp;marker=52415800-8b69-11e0-9b19-734f6f006e54"/> />
</images> </images>

10
openstack-compute-api-2/src/samples/server-post-req-short.json
View File

@@ -9,7 +9,15 @@
"personality": [ "personality": [
{ {
"path": "/etc/banner.txt", "path": "/etc/banner.txt",
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA==" "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
} }
] ]
} }

10
openstack-compute-api-2/src/samples/server-post-req.json
View File

@@ -8,7 +8,15 @@
"name": "new-server-test", "name": "new-server-test",
"personality": [ "personality": [
{ {
"contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA==", "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
b25zLiINCg0KLVJpY2hhcmQgQmFjaA==",
"path": "/etc/banner.txt" "path": "/etc/banner.txt"
} }
] ]

20
openstack-compute-api-2/src/samples/version.xml
View File

@@ -1,23 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<version xmlns="http://docs.openstack.org/common/api/v1.0" <version xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom" xmlns:atom="http://www.w3.org/2005/Atom" id="v2" status="CURRENT"
id="v2" status="CURRENT" updated="2011-01-21T11:33:21-06:00"> updated="2011-01-21T11:33:21-06:00">
<media-types> <media-types>
<media-type base="application/xml" <media-type base="application/xml"
type="application/vnd.openstack.compute.v2+xml"/> type="application/vnd.openstack.compute.v2+xml"/>
<media-type base="application/json" <media-type base="application/json"
type="application/vnd.openstack.compute.v2+json"/> type="application/vnd.openstack.compute.v2+json"/>
</media-types> </media-types>
<atom:link rel="self" href="http://servers.api.openstack.org/v2/"/>
<atom:link rel="self" <atom:link rel="describedby" type="application/pdf"
href="http://servers.api.openstack.org/v2/"/>
<atom:link rel="describedby"
type="application/pdf"
href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"/> href="http://docs.rackspacecloud.com/servers/api/v2/cs-devguide-20110125.pdf"/>
<atom:link rel="describedby" type="application/vnd.sun.wadl+xml"
<atom:link rel="describedby" href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl"
type="application/vnd.sun.wadl+xml" />
href="http://docs.rackspacecloud.com/servers/api/v2/application.wadl" />
</version> </version>

4
openstack-compute-api-2/src/samples/versions.xml
View File

@@ -1,18 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<versions xmlns="http://docs.openstack.org/common/api/v1.0" <versions xmlns="http://docs.openstack.org/common/api/v1.0"
xmlns:atom="http://www.w3.org/2005/Atom"> xmlns:atom="http://www.w3.org/2005/Atom">
<version id="v1.0" status="DEPRECATED" <version id="v1.0" status="DEPRECATED"
updated="2009-10-09T11:30:00Z"> updated="2009-10-09T11:30:00Z">
<atom:link rel="self" <atom:link rel="self"
href="http://servers.api.openstack.org/v1.0/"/> href="http://servers.api.openstack.org/v1.0/"/>
</version> </version>
<version id="v2" status="CURRENT" <version id="v2" status="CURRENT"
updated="2010-12-12T18:30:02.25Z"> updated="2010-12-12T18:30:02.25Z">
<atom:link rel="self" <atom:link rel="self"
href="http://servers.api.openstack.org/v2/"/> href="http://servers.api.openstack.org/v2/"/>
</version> </version>
</versions> </versions>

80
openstack-compute-api-2/src/section_concepts.xml Normal file
View File

@@ -0,0 +1,80 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- 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>'>
]>
<section 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="concepts">
<?dbhtml stop-chunking?>
<title>Concepts</title>
<para>To use the OpenStack Compute API effectively, you should
understand several key concepts: </para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Server</emphasis></para>
<para>A virtual machine (VM) instance in the compute
system. Flavor and image are requisite elements when
creating a server. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Flavor</emphasis></para>
<para>An available hardware configuration for a server.
Each flavor has a unique combination of disk space,
memory capacity and priority for CPU time. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Image</emphasis></para>
<para>A collection of files used to create or rebuild a
server. Operators provide a number of pre-built OS
images by default. You may also create custom images
from cloud servers you have launched. These custom
images are useful for backup purposes or for producing
“gold” server images if you plan to deploy a
particular server configuration frequently. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Reboot</emphasis></para>
<para>Use this function to perform either a soft or hard
reboot of a server. With a soft reboot, the operating
system is signaled to restart, which allows for a
graceful shutdown of all processes. A hard reboot is
the equivalent of power cycling the server. The
virtualization platform should ensure that the reboot
action has completed successfully even in cases in
which the underlying domain/VM is paused or
halted/stopped. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Rebuild</emphasis></para>
<para>Use this function to remove all data on the server and
replaces it with the specified image. Server ID and IP
addresses remain the same. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Resize</emphasis></para>
<para>Use this function to convert an existing server to a
different flavor, in essence, scaling the server up or
down. The original server is saved for a period of
time to allow rollback if there is a problem. All
resizes should be tested and explicitly confirmed, at
which time the original server is removed. All resizes
are automatically confirmed after 24 hours if you do not
confirm or revert them. </para>
</listitem>
</itemizedlist>
</section>