You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltacloud.apache.org by lu...@apache.org on 2011/08/06 01:10:32 UTC
svn commit: r1154412 [3/3] - in /incubator/deltacloud/trunk/site:
content/api.mdown output/api.html
Modified: incubator/deltacloud/trunk/site/output/api.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/api.html?rev=1154412&r1=1154411&r2=1154412&view=diff
==============================================================================
--- incubator/deltacloud/trunk/site/output/api.html (original)
+++ incubator/deltacloud/trunk/site/output/api.html Fri Aug 5 23:10:32 2011
@@ -2,7 +2,7 @@
<html>
<head>
<title>
- Deltacloud - Documentation
+ Deltacloud - Documentation - REST API and Developer Guide
</title>
<meta content='' name='keywords' />
<meta content='' name='description' />
@@ -73,297 +73,1917 @@
<div id='frontpageHeader'></div>
<div id='main'>
<div class='container' id='content-deltacloud'>
- <h1>Deltacloud API</h1>
+ <h1>Apache Deltacloud API</h1>
+
+ <p><a name="toc" /></p>
<p><ul>
<li>
- <a href="#h1">REST</a>
+ <a href="#h1">1. Introduction</a>
+ <ul>
+ <li>
+ <a href="#h1_1">1.1 Collections</a>
+ </li>
+ <li>
+ <a href="#h1_2">1.2 Client Requests</a>
+ </li>
+ <li>
+ <a href="#h1_3">1.3 Authentication</a>
+ </li>
+ <li>
+ <a href="#h1_4">1.4 Server responses</a>
+ </li>
+ <li>
+ <a href="#h1_5">1.5 API conventions</a>
+ </li>
+ <li>
+ <a href="#h1_6">1.6 API stability and evolution</a>
+ </li>
+ <li>
+ <a href="#h1_7">1.7 Online documentation</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h2">2. The API entry point</a>
+ <ul>
+ <li>
+ <a href="#h2_1">2.1 Features</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3">3. Compute Resources</a>
+ <ul>
+ <li>
+ <a href="#h3_1">3.1 Realms</a>
+ <ul>
+ <li>
+ <a href="#h3_1_1">GET /api/realms</a>
+ </li>
+ <li>
+ <a href="#h3_1_2">GET /api/realms/:id</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_2">3.2 Hardware Profiles</a>
+ <ul>
+ <li>
+ <a href="#h3_2_1">GET /api/hardware_profiles</a>
+ </li>
+ <li>
+ <a href="#h3_2_2">GET /api/hardware profiles/:id</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_3">3.3 Images</a>
+ <ul>
+ <li>
+ <a href="#h3_3_1">GET /api/images</a>
+ </li>
+ <li>
+ <a href="#h3_3_2">GET /api/images/:id</a>
+ </li>
+ <li>
+ <a href="#h3_3_3">POST /api/images</a>
+ </li>
+ <li>
+ <a href="#h3_3_4">DELETE /api/images/:id</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_4">3.4 Instance States</a>
+ <ul>
+ <li>
+ <a href="#h3_4_1">GET /api/instance_states</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_5">3.5 Instances</a>
+ <ul>
+ <li>
+ <a href="#h3_5_1">GET /api/instances</a>
+ </li>
+ <li>
+ <a href="#h3_5_2">GET /api/instances/:id</a>
+ </li>
+ <li>
+ <a href="#h3_5_3">POST /api/instances/:id/:action</a>
+ </li>
+ <li>
+ <a href="#h3_5_4">POST /api/instances</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_6">3.6 Keys</a>
+ <ul>
+ <li>
+ <a href="#h3_6_1">GET /api/keys</a>
+ </li>
+ <li>
+ <a href="#h3_6_2">GET /api/keys/:id</a>
+ </li>
+ <li>
+ <a href="#h3_6_3">POST /api/keys</a>
+ </li>
+ <li>
+ <a href="#h3_6_4">DELETE /api/keys/:id</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_7">3.7 Firewalls</a>
+ <ul>
+ <li>
+ <a href="#h3_7_1">GET /api/firewalls</a>
+ </li>
+ <li>
+ <a href="#h3_7_2">GET /api/firewalls/:id</a>
+ </li>
+ <li>
+ <a href="#h3_7_3">POST /api/firewalls</a>
+ </li>
+ <li>
+ <a href="#h3_7_4">DELETE /api/firewalls/:id</a>
+ </li>
+ <li>
+ <a href="#h3_7_5">POST /api/firewalls/:id/rules</a>
+ </li>
+ <li>
+ <a href="#h3_7_6">DELETE /api/firewalls/:id/:rule_id</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_8">3.8 Addresses</a>
+ <ul>
+ <li>
+ <a href="#h3_8_1">GET /api/addresses</a>
+ </li>
+ <li>
+ <a href="#h3_8_2">GET /api/addresses/:id</a>
+ </li>
+ <li>
+ <a href="#h3_8_3">POST /api/addresses</a>
+ </li>
+ <li>
+ <a href="#h3_8_4">DELETE /api/addresses/:id</a>
+ </li>
+ <li>
+ <a href="#h3_8_5">POST /api/addresses/:id/associate</a>
+ </li>
+ <li>
+ <a href="#h3_8_6">POST /api/addresses/:id/disassociate</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h3_9">3.9 Load Balancers</a>
+ <ul>
+ <li>
+ <a href="#h3_9_1">GET /api/load_balancers</a>
+ </li>
+ <li>
+ <a href="#h3_9_2">GET /api/load_balancers/:id</a>
+ </li>
+ <li>
+ <a href="#h3_9_3">POST /api/load_balancers</a>
+ </li>
+ <li>
+ <a href="#h3_9_4">DELETE /api/load_balancers/:id</a>
+ </li>
+ <li>
+ <a href="#h3_9_5">POST /api/load_balancers/:id/register</a>
+ </li>
+ <li>
+ <a href="#h3_9_6">POST /api/load_balancers/:id/unregister</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h4">4. Storage Resources</a>
+ <ul>
+ <li>
+ <a href="#h4_1">4.1 Storage Volumes</a>
+ <ul>
+ <li>
+ <a href="#h4_1_1">GET /api/storage_volumes</a>
+ </li>
+ <li>
+ <a href="#h4_1_2">GET /api/storage_volumes/:id</a>
+ </li>
+ <li>
+ <a href="#h4_1_3">POST /api/storage_volumes</a>
+ </li>
+ <li>
+ <a href="#h4_1_4">DELETE /api/storage_volumes/:id</a>
+ </li>
+ <li>
+ <a href="#h4_1_5">POST /api/storage_volumes/:id/attach</a>
+ </li>
+ <li>
+ <a href="#h4_1_6">POST /api/storage_volumes/:id/detach</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h4_2">4.2 Storage Snapshots</a>
+ <ul>
+ <li>
+ <a href="#h4_2_1">GET /api/storage_snapshots</a>
+ </li>
+ <li>
+ <a href="#h4_2_2">GET /api/storage_snapshots/:id</a>
</li>
<li>
- <a href="#h2">Authentication</a>
+ <a href="#h4_2_3">POST /api/storage_snapshots</a>
</li>
<li>
- <a href="#h3">Primary Entry Point</a>
+ <a href="#h4_2_4">DELETE /api/storage_snapshots/:id</a>
+ </li>
+ </ul>
</li>
<li>
- <a href="#h4">Resources</a>
+ <a href="#h4_3">4.3 Blob Storage</a>
<ul>
<li>
- <a href="#h4_1">Hardware Profiles</a>
+ <a href="#h4_3_1">GET /api/buckets</a>
+ </li>
+ <li>
+ <a href="#h4_3_2">GET /api/buckets/:id</a>
+ </li>
+ <li>
+ <a href="#h4_3_3">POST /api/buckets</a>
+ </li>
+ <li>
+ <a href="#h4_3_4">DELETE /api/buckets/:id</a>
+ </li>
+ <li>
+ <a href="#h4_3_5">GET /api/buckets/:bucket_id/:blob_id</a>
+ </li>
+ <li>
+ <a href="#h4_3_6">GET /api/buckets/:bucket_id/:blob_id/content</a>
+ </li>
+ <li>
+ <a href="#h4_3_7">PUT /api/buckets/:bucket_id/:blob_id</a>
+ </li>
+ <li>
+ <a href="#h4_3_8">POST /api/buckets/:bucket_id</a>
</li>
<li>
- <a href="#h4_2">Realms</a>
+ <a href="#h4_3_9">DELETE /api/buckets/:bucket_id/:blob_id</a>
</li>
<li>
- <a href="#h4_3">Images</a>
+ <a href="#h4_3_10">HEAD /api/buckets/:bucket_id/:blob_id</a>
</li>
<li>
- <a href="#h4_4">Instances</a>
+ <a href="#h4_3_11">POST /api/buckets/:bucket_id/:blob_id</a>
</li>
- </ul></li></ul></p>
+ </ul></li></ul></li></ul></p>
- <p>The Deltacloud API is built as a service-based REST API. You do not
- directly link a Deltacloud library into your program to use it.
- Instead, a client speaks the Deltacloud API over HTTP to a server
- which implements the REST interface.</p>
+ <hr />
- <p>Since cloud providers use their own APIs instead of the Deltacloud
- API, we provide a translation layer that makes it possible to use
- Deltacloud with these providers.</p>
+ <h2 id="h1">1. Introduction</h2>
- <h2 id="h1">REST</h2>
+ <p>Apache Deltacloud is a REST-based (HATEOAS) cloud abstraction API, that enables
+ management of resources in different IaaS clouds using a single API. A series of
+ back-end drivers 'speak' each cloud provider's native API and the Deltacloud Core
+ Framework provides the basis for implementing drivers as needed for other/new IaaS
+ cloud providers. Apache Deltacloud currently supports many back-end cloud providers,
+ as listed in <a href="./drivers.html">Drivers</a>.</p>
- <p>The Deltacloud API is a <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">RESTful API</a>, using HATEOAS architectural
- style. The API requires no client-side URL construction. Access is
- based entirely off a single entry-point resource. This allows other
- implementors to structure their URL space however they like.</p>
+ <p>The Apache Deltacloud project empowers its users in avoiding lockin to any single
+ cloud provider. Deltacloud provides an API abstraction that can be implemented as a
+ wrapper around a large number of clouds, freeing users of cloud from dealing with the
+ particulars of each cloud's API.</p>
- <p>Additionally, the Deltacloud API uses <em>content negotiation</em> to
- determine the format of the returned representation. As of the current
- revision, the only required representation is XML. Clients wishing to
- receive XML representations must specify the HTTP <code>Accept</code> header as
- <code>application/xml</code>.</p>
+ <hr />
- <h2 id="h2">Authentication</h2>
+ <h3 id="h1_1">1.1 Collections</h3>
- <p>The Deltacloud API uses HTTP authentication methods for authenticating
- a given client. There is no explicit <em>login</em> action required. If
- authentication is required, an HTTP status of 401 will be returned to
- challenge for credentials.</p>
+ <p>The following terms represent the abstractions used in the Apache Deltacloud API and
+ are introduced here to aid the reader. Each represents an entity in the 'back-end'
+ provider cloud such as a running virtual server or a server image. It should be
+ noted that not all clouds support all of the following entity collections. Only
+ the appropriate entity collections are exposed for a given back-end driver
+ (e.g. the Microsoft Azure driver currently exposes only the 'Buckets' collection).</p>
- <h2 id="h3">Primary Entry Point</h2>
+ <h5>Realms</h5>
- <p>Any Deltacloud implementor <em>must</em> provide exactly one well-known URL
- as an entry-point. For example, <code>http://fancycloudprovider.com/api</code>.</p>
+ <p>A distinct organizational unit within the back-end cloud such as a datacenter.
+ A realm may but does not necessarily represent the geographical location of the
+ compute resources being accessed.</p>
- <p>The result of this entry-point is a set of entry-points into other
- collections, such as <em>images</em>, <em>instances</em>, <em>hardware profiles</em> and
- <em>realms</em>, among others.</p>
+ <h5>Instances</h5>
- <p>Each collection is defined by a <code><link></code> tag with an <code>href</code> attribute
- which includes the fully-qualified URL to the collection (which <em>may</em>
- exist on different servers) and a <code>rel</code> attribute to denote which
- collection is being specified.</p>
+ <p> A realized virtual server, running in a given back-end cloud. These are instantiated
+ from server Images.</p>
- <pre><code><api driver='ec2' version='1.0'>
 <link href='http://fancycloudprovider.com/api/hardware_profiles' rel='hardware_profiles' />
 <link href='http://fancycloudprovider.com/api/instance_states' rel='instance_states' />
 <link href='http://fancycloudprovider.com/api/realms' rel='realms' />
 <link href='http://fancycloudprovider.com/api/images' rel='images' />
 <link href='http://fancycloudprovider.com/api/instances' rel='instances' />
</api>
</code></pre>
+ <h5>Images</h5>
- <h2 id="h4">Resources</h2>
+ <p>These are templates (virtual machine images) from which Instances are created.
+ Each Image defines the root partition and initial storage for the Instance operating system.</p>
- <p>From the primary entry-point, a client may follow the URL provided for
- a collection to retrieve the resources within that collection. The
- collection representation will include the full representations of the
- items within it, along with links to retrieve each item individually.</p>
+ <h5>Instance States</h5>
- <p><img src="styles/basic-relationships.png" alt="Basic relationships" /></p>
+ <p>These represent the Instance lifecycle; at any time an Instance will be in one of
+ <em>start, pending, running, stopped, shutting_down, finished</em>.</p>
- <h3 id="h4_1">Hardware Profiles</h3>
+ <h5>Keys</h5>
- <p>Within a cloud provider a <em>hardware profile</em> represents a
- configuration of resources upon which a machine may be deployed. A
- hardware profile defines aspects such as local disk storage, available
- RAM, and architecture. A future revision of the Deltacloud API will
- include more aspects, including number and speed of CPUs available.
- Each provider is free to define as many (or as few) hardware profiles
- as desired.</p>
+ <p>These represent credentials used to access a running Instance. These can be of type
+ <em>key</em> (e.g., an <em>RSA</em> key), or of type <em>password</em> (i.e., with <em>username</em> and
+ <em>password</em> attributes).</p>
- <pre><code><hardware_profiles>
 <hardware_profile href='http://fancycloudprovider.com/api/hardware_profiles/m1-small' id='m1-small'>
 <property kind='fixed' name='storage' unit='GB' value='160' />
 <property kind='fixed' name='architecture' unit='label' value='i386' />
 <property kind='fixed' name='cpu' unit='count' value='1' />
 <property kind='fixed' name='memory' unit='MB' value='1740.8' />
 </hardware_profile>
</code></pre>
+ <h5>Storage_Volume</h5>
- <p>Each <code><hardware_profile></code> block shall contain an <code>href</code> attribute providing a
- URL to manipulate a specific profile, along with property elements for each
- attribute of the hardware.</p>
+ <p>This is a virtual storage device that can be attached to an Instance and mounted
+ by the OS therein.</p>
- <ul>
- <li><strong><code>id</code></strong> is a unique identifier for the profile</li>
- <li><strong><code>property</code></strong> describes each of the hardware aspects</li>
- </ul>
+ <h5>Storage_Snapshot</h5>
+ <p>These are copies, snapshots of a Storage_Volume at a specified point in time.</p>
- <p>Properties have the following attributes:</p>
+ <h5>Bucket</h5>
- <ul>
- <li><strong><code>name</code></strong> the type of the property: <em>e.g.</em> <code>memory</code> or <code>storage</code></li>
- <li><strong><code>unit</code></strong> the units in which the value is specified: <code>MB</code>, <code>GB</code>, <code>count</code> or <code>label</code></li>
- <li><strong><code>value</code></strong> the actual value of the property. It depends on the specified unit: <code>1024</code>, <code>2</code> on <code>x86_64</code></li>
- <li><strong><code>kind</code></strong> describes the values to chose from.
+ <p>A container for data blobs. The organisational unit of a generic <em>key</em> ==> <em>value</em>
+ based data store (such as Rackspace CloudFiles or Amazon S3). Individual data
+ items, <em>Blobs</em>, are exposed as a subcollection under a bucket.</p>
- <ul>
- <li><strong><code>fixed</code></strong> only the value specified in the property is available</li>
- <li><strong><code>enum</code></strong> a list of available values is provided</li>
- <li><strong><code>range</code></strong> available values are described by a numeric range</li>
- </ul>
- </li>
- </ul>
+ <h5>Blob</h5>
+ <p>A generic binary data item that exists with a specified bucket (an `object' in
+ Amazon S3 and Rackspace CloudFiles).</p>
- <p>When the <code>kind</code> is either an <code>enum</code> or a <code>range</code>, there must be two additional elements specified. One
- that specifies the allowed values and the second with a way of picking a value.</p>
+ <h5>Address</h5>
- <p>In the non-fixed case, the <code>value</code> property attribute specifies the default value.</p>
+ <p>Represents an IP addresses. Depending on the back-end cloud provider addresses
+ can be 'public' in which case they represent a unique, globally routable IP
+ address, or 'private' in which case they represent an address routable only
+ within a private network.</p>
- <pre><code> <hardware_profile href='http://fancycloudprovider.com/api/hardware_profiles/m1-xlarge' id='m1-xlarge'>
 <property kind='enum' name='storage' unit='GB' value='1024'>
 <param href='http://fancycloudprovider.com/api/instances' method='post' name='hwp_storage' operation='create' />
 <enum>
 <entry value='1024' />
 <entry value='2048' />
 <entry value='4096' />
 </enum>
 </property>
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='cpu' unit='count' value='4' />
 <property kind='range' name='memory' unit='MB' value='12288'>
 <param href='http://fancycloudprovider.com/api/instances' method='post' name='hwp_memory' operation='create' />
 <range first='12288' last='32768' />&#
x000A; </property>
 </hardware_profile>
</hardware_profiles>
</code></pre>
+ <h5>Load Balancer</h5>
- <p>At this time, hardware profile resources are immutable and read-only. In a
- future revision they may be mutable.</p>
+ <p>Allows distribution of ingress network traffic received by a specified IP address
+ to a number of instances.</p>
- <h3 id="h4_2">Realms</h3>
+ <h5>Firewalls</h5>
- <p>Within a cloud provider a <em>realm</em> represents a boundary containing
- resources. The exact definition of a realm is left to the cloud
- provider. In some cases, a realm may represent different datacenters,
- different continents, or different pools of resources within a single
- datacenter. A cloud provider may insist that resources must all exist
- within a single realm in order to cooperate. For instance, storage
- volumes may only be allowed to be mounted to instances within the same
- realm.</p>
+ <p>Represent sets of rules that govern the accessibility of a running instance over
+ the public Internet</p>
- <pre><code><realms>
 <realm href="http://fancycloudprovider.com/api/realms/us" id='us'>
 <name>United States</name>
 <state>AVAILABLE</state>
 <limit/>
 </realm>
 <realm href="http://fancycloudprovider.com/api/realms/eu" id='eu'>
 <name>Europe</name>
 <state>AVAILABLE</state>
 <limit/>
 </realm>
</realms>
</code></pre>
+ <br />
- <p>Each <code><realm></code> block shall contain an <code>href</code> attribute providing a URL
- to manipulate a specific realm, along with elements for each attribute
- of a realm.</p>
- <ul>
- <li><strong><code>id</code></strong> A unique identifier for the realm</li>
- <li><strong><code>name</code></strong> A short label</li>
- <li><strong><code>state</code></strong> Indicator of the current state of a realm
+ <p><a href="#toc">Contents</a></p>
- <ul>
- <li>AVAILABLE</li>
- <li>UNAVAILABLE</li>
- </ul>
- </li>
- <li><strong><code>limit</code></strong> Limits applicable for the <em>current requester</em></li>
- </ul>
+ <br />
- <h3 id="h4_3">Images</h3>
+ <hr />
- <p>An <em>image</em> is a platonic form of a machine. Images are not directly
- executable, but are a template for creating actual instances of
- machines.</p>
+ <h3 id="h1_2">1.2 Client Requests</h3>
- <p>The instances collection will return a set of all images available to
- the current user.</p>
+ <p>In keeping with REST, clients make requests through HTTP, with the usual
+ meanings assigned to the standard HTTP verbs GET, POST, PUT, and DELETE.</p>
- <pre><code><images>
 <image href="http://fancycloudprovider.com/api/images/img1" id='img1'>
 <owner_id>fedoraproject</owner_id>
 <name>Fedora 10</name>
 <description>Fedora 10</description>
 <architecture>x86_64</architecture>
 </image>
 <image href="http://fancycloudprovider.com/api/images/img2" id='img2'>
 <owner_id>fedoraproject</owner_id>
 <name>Fedora 10</name>
 <description>Fedora 10</description>
 <architecture>i386</architecture>
 </image>
 <image href="http://fancycloudprovider.com/api/images/img3" id='img3'>
 <owner_id>ted</owner_id>
 <name>JBoss</name>
 <description>JBoss</description>
 <architecture>i386</architecture>&#x
000A; </image>
</images>
</code></pre>
+ <p>Beyond the generally accepted REST design principles, Apache Deltacloud
+ follows the guidelines discussed in the Fedora Project <a href="http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide" title="Fedora Cloud APIs REST Style Guide">Cloud APIs Rest Style Guide</a>.</p>
- <p>Each <code><image></code> block <em>shall</em> contain an <code>href</code> attribute providing a
- URL to manipulate a specific image, along with elements for each
- attribute of an image. Each element, including those for optional
- attributes must be present. Optional attributes may be specified as a
- element with empty content.</p>
+ <p>The URL space of the API is structured into collections of resources
+ (entities, objects). The top level entities used in the Deltacloud API are:
+ Realms, Images, Instance States, Instances, Keys, Storage Volume,
+ Storage Snapshots, Blob Storage.</p>
- <p>These attributes include</p>
+ <br />
- <ul>
- <li><strong><code>id</code></strong> A unique identifier for the image</li>
- <li><strong><code>owner_id</code></strong> An opaque identifier which indicates the owner of an image</li>
- <li><strong><code>name</code></strong> An <em>optional</em> short label describing the image</li>
- <li><strong><code>description</code></strong> An <em>optional</em> description describing the image more fully</li>
- <li><strong><code>architecture</code></strong> A description of the machine architecture of the image
- which may contain values such as:
- <ul>
- <li><code>i386</code></li>
- <li><code>x86_64</code></li>
- </ul>
- </li>
- </ul>
+ <p><a href="#toc">Contents</a></p>
+ <br />
- <p>At this time, image resources are immutable and read-only. In a future revision
- they will be mutable.</p>
- <h3 id="h4_4">Instances</h3>
+ <hr />
- <p>An <em>instance</em> is a concrete machine realized from an <em>image</em>. The
- images collection may be obtained by following the link from the
- primary entry-point.</p>
+ <h3 id="h1_3">1.3 Authentication</h3>
- <pre><code><instances>
 <instance href="http://fancycloudprovider.com/api/instances/inst1" id='inst1'>
 <owner_id>larry</owner_id>
 <name>Production JBoss Instance</name>
 <image href="http://fancycloudprovider.com/api/images/img3"/>
 <hardware_profile href="http://fancycloudprovider.com/api/hardware_profiles/m1-small"/>
 <realm href="http://fancycloudprovider.com/api/realms/us"/>

 <state>RUNNING</state>
 <actions>
 <link rel="reboot" href="http://fancycloudprovider.com/api/instances/inst1/reboot"/>
 <link rel="stop" href="http://fancycloudprovider.com/api/instances/inst1/stop"/>
 </actions>
 <public_addresses>
 <address>inst1.larry.fancycloudprovider.com</address>
 </public_addresses>

 &
lt;private_addresses>
 <address>inst1.larry.internal</address>
 </private_addresses>
 </instance>
</instances>
</code></pre>
+ <p>The Deltacloud API server is stateless, and does not keep any information
+ about the current client. In particular, it does not store the credentials for
+ the backend cloud it is talking to. Instead, it uses HTTP basic authentication,
+ and clients have to send the username/password for the backend cloud on every request.</p>
- <p>Each <code><instance></code> block shall contain an href attribute providing a
- URL to manipulate a specific instance, along with elements for each
- attribute of an instance. Each element, including those for optional
- attributes must be present. Optional attributes may be specified as a
- element with empty content.</p>
+ <p>The specifics of what needs to be sent varies from cloud to cloud; some
+ cloud providers employ a username and password for API access, whilst
+ others use special-purpose API keys. A list of the credentials that a given
+ cloud provider expects for API access is <a href="documentation.html">available here</a></p>
- <p>Simple attributes include</p>
+ <br />
- <ul>
- <li><strong><code>id</code></strong> A unique identifier for the instance</li>
- <li><strong><code>owner_id</code></strong> An opaque identifier which indicates the owner of an instance</li>
- <li><strong><code>name</code></strong> An <em>optional</em> short label describing the instance</li>
- <li><strong><code>image</code></strong> Provides a link to the platonic image from which the instance is based</li>
- <li><strong><code>hardware_profile</code></strong> Provides a link to the hardware profile in use by the instance</li>
- <li><strong><code>realm</code></strong> Provides a link to the realm where the instance is deployed</li>
- <li><strong><code>state</code></strong> Indicator of the instance's current state
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h1_4">1.4 Server responses</h3>
+
+ <p>The server can respond to client requests in a variety of formats. The
+ appropriate response format is determined by HTTP content negotiation.
+ The primary format is XML, which is the basis for this document. Output is
+ also available as JSON and, mostly for testing, as HTML. Clients can also
+ explicitly request a specific response format by including the
+ 'format=' request parameter (e.g., http://deltacloudserver.foo/api?format=xml
+ or http://deltacloudserver.foo/api?format=json).</p>
+
+ <p>In general and especially for the html inteface, list operations such as
+ <code>GET /api/realms</code> will only provide a list of the objects of this resource type
+ with only brief details; full details can be retrieved by making a request
+ <code>GET /api/realms/:id</code> to the URL of the individual realm.</p>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h1_5">1.5 API conventions</h3>
+
+ <p>Any XML element that represents an object, such as an instance has an
+ href and a id attribute. The href provides the URL at which object-specific
+ actions can be performed (e.g., a GET to the URL will give details
+ of the object). The id provides an identifier of the object and this is unique
+ within its collection (i.e., unique id for each Instance, Image, Realm etc).</p>
+
+ <p>Generally, objects also have a human-readable name; the name is provided in a
+ <code><name/></code> child element of the objectâs container tag.</p>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h1_6">1.6 API stability and evolution</h3>
+
+ <p>Future changes to the API will be made in a manner that allows old clients
+ to work against newer versions of the the API server.</p>
+
+ <p>The stability guarantees given by the Apache Deltacloud API imply that the
+ following changes may happen in newer versions of the API:</p>
<ul>
- <li><code>PENDING</code></li>
- <li><code>STOPPED</code></li>
- <li><code>RUNNING</code></li>
- </ul>
- </li>
+ <li>adding new collections, or supporting new operations on existing collections</li>
+ <li>adding optional parameters to existing operations</li>
+ <li>adding additional attributes and elements to the XML/JSON responses</li>
</ul>
- <p>Multiple-valued attributes include</p>
+ <p>On the other hand, these changes would violate API stability and will therefore
+ not be made:</p>
<ul>
- <li><strong><code>public_addresses</code></strong> Publicly routable IP addresses or names for the instance</li>
- <li><strong><code>private_addresses</code></strong> Private network IP addresses or names for the instance</li>
+ <li>removing an operation on a collection</li>
+ <li>making an optional parameter for an operation mandatory</li>
+ <li>removing attributes or elements from XML responses</li>
</ul>
- <p>In addition to the abovementioned attributes, each <code><instance></code> may contain an
- <code><actions></code> block specifying valid actions for the instance, along with the URL
- which may be used to perform the action. Each action is specified by a <code><link></code>
- with an <code>href</code> attribute providing the URL, and a <code>rel</code> attribute providing
- a key to determine what the action will do.</p>
+ <br />
- <p>Representative actions include</p>
- <ul>
- <li><code>reboot</code></li>
- <li><code>start</code></li>
- <li><code>stop</code></li>
- </ul>
+ <p><a href="#toc">Contents</a></p>
+ <br />
- <p>Not all actions may be valid at all times for all instances. To invoke
- an action, a client must perform an HTTP <code>POST</code> to the URL indicated.</p>
- <h4>Creating a new Instance</h4>
+ <hr />
- <p>Per usual REST architectural style, new instances are created by
- issuing an HTTP <code>POST</code> to the instances collection as defined through
- the primary entry-point URL. Data should be sent in
- <code>application/x-www-form-urlencoded</code> format.</p>
+ <h3 id="h1_7">1.7 Online documentation</h3>
- <p>To create a new instance, only one parameter is required</p>
+ <p>Automatically generated documentation can be accessed on every server running
+ the Deltacloud Core API service through the URL <code>http://localhost:3001/api/docs/</code>.
+ The documentation is both available in HTML and XML, though the XML format is not
+ part of this specification, and may change in an incompatible way.</p>
- <ul>
- <li><strong><code>image_id</code></strong> The identifier (not URL) of the image from which to base the instance</li>
- </ul>
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+ <br />
- <p>Optional parameters may also be provided</p>
+
+ <hr />
+
+ <h2 id="h2">2. The API entry point</h2>
+
+ <p>Any part of the official API can be reached through the main entry point,
+ by default http://localhost:3001/api. The entry point list the resources
+ the server knows about for the current cloud provider; for the Amazon EC2 driver for example, these are:</p>
<ul>
- <li><strong><code>realm_id</code></strong> The realm in which to launch the instance</li>
- <li><strong><code>hwp_name</code></strong> The hardware profile upon which to launch the instance</li>
- <li><strong><code>name</code></strong> A short label to identify the instance</li>
+ <li>Instances</li>
+ <li>Instance states</li>
+ <li>Images</li>
+ <li>Realms</li>
+ <li>Hardware profiles</li>
+ <li>Keys</li>
+ <li>Buckets</li>
+ <li>Storage volumes</li>
+ <li>Storage snapshots</li>
+ <li>Load Balancers</li>
+ <li>Addresses</li>
+ <li>Firewalls</li>
</ul>
- <p>If <code>realm_id</code> or <code>hwp_name</code> are not specified, the provider <em>must</em>
- select reasonable defaults. The architecture of the selected harware profile
- <em>must</em> match the architecture of the specified image.</p>
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1439

<api driver='ec2' version='0.3.0'>
 <link href='http://localhost:3001/api/instance_states' rel='instance_states'>
 </link>
 <link href='http://localhost:3001/api/drivers' rel='drivers'>
 </link>
 <link href='http://localhost:3001/api/addresses' rel='addresses'>
 </link>
 <link href='http://localhost:3001/api/hardware_profiles' rel='hardware_profiles'>
 </link>
 <link href='http://localhost:3001/api/firewalls' rel='firewalls'>
 </link>
 <link href='http://localhost:3001/api/storage_volumes' rel='storage_volumes'>
 </link>
 <link href='http://localhost:3001/api/images' rel='images'>
 <feature name='owner_id'>
 </feature>
 </link>�
0A; <link href='http://localhost:3001/api/realms' rel='realms'>
 </link>
 <link href='http://localhost:3001/api/buckets' rel='buckets'>
 <feature name='bucket_location'>
 </feature>
 </link>
 <link href='http://localhost:3001/api/instances' rel='instances'>
 <feature name='user_data'>
 </feature>
 <feature name='authentication_key'>
 </feature>
 <feature name='firewalls'>
 </feature>
 <feature name='instance_count'>
 </feature>
 <feature name='attach_snapshot'>
 </feature>
 </link>
 <link href='http://localhost:3001/api/storage_snapshots' rel='storage_snapshots'>
 </link>
 <link href='http://localhost:3001/api/keys' rel='keys'>
 </link>
 <link h
ref='http://localhost:3001/api/load_balancers' rel='load_balancers'>
 </link>
</api>
</code></pre>
+
+ <p>Specific implementations for the Apache Deltacloud API may not support all resource
+ types defined by this API. For example, a Deltacloud instance pointing at a storage-only
+ service will not expose compute resources like instances and hardware profiles.</p>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h2_1">2.1 Features</h3>
+
+ <p>The Apache Deltacloud API defines the standard behavior and semantics
+ for each of the resource types as a baseline for any API implementation; it
+ is often desirable to enhance standard API behavior with specific features.
+ The API also defines all the features that can be supported by an API
+ implementation - each of them has a fixed, predefined meaning. As an
+ example, the feature user-name indicates that a user-specified name can be
+ assigned to an instance when it is created. Features are advertised in the
+ top-level entry point as illustrated below:</p>
+
+ <pre><code><api driver='mock' version='0.3.0'>
 ...
 <link href='http://localhost:3001/api/instances' rel='instances'>
 <feature name='hardware_profiles'></feature>
 <feature name='user_name'></feature>
 <feature name='authentication_key'></feature>
 </link>
 ...
</api>
</code></pre>
+
+ <p>The following describes the features available to each collection in
+ the Deltacloud API together with a brief description:</p>
+
+ <pre><code>Feature Collection Operation Description
------- ---------- --------- -----------
owner_id Images GET /api/images Allows filtering of the
 image list by owner_id
-- -- -- --
user_name Instances POST /api/instances Accept a user-defined name
 on instance creation
-- -- -- --
user_data Instances POST /api/instances Provide user-defined data
 that is accessible by the
 running instance
-- -- --
--
user_iso Instances POST /api/instances Provide a base64 encoded
 gzipped ISO file accessible
 as CD-ROM drive by the
 running instnace
-- -- -- --
user_files Instances POST /api/instances Accept files that will be
 placed into the launched
 instance
-- -- -- --
firewalls Instances POST /api/instances Put the instance into one
 or more firewalls on launch
-- --
-- --
authentication_key Instances POST /api/instances Provide the authentication
 key to be used for
 accessing the instance
-- -- -- --
authentication_password Instances POST /api/instances Provide the password to be
 used to access the running
 instance
-- -- -- --
instance_count Instances POST /api/instances Specify the number of
 instances to launch in
 one operation
-- --
-- --
attach_snapshot Instances POST /api/instances Attach a storage_snapshot
 to an instance as a
 storage_volume
-- -- -- --
sandboxing Instances POST /api/instances Launch a instance from
 a sandbox image
 (Gogrid specific)
-- -- -- --
bucket_location Buckets POST /api/buckets Specify a location that
 the bucket should be
 created in (e.g.

specific cloud-provider
 datacenter)
</code></pre>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h2 id="h3">3. Compute Resources</h2>
+
+ <p>The compute resources are <strong><em>instances, instance states, images, realms, hardware profiles,
+ firewalls, load balancers, addresses</em></strong> and <strong><em>keys</em></strong>.</p>
+
+ <h3 id="h3_1">3.1 Realms</h3>
+
+ <p>A <strong><em>realm</em></strong> represents a boundary containing resources, such as a data
+ center. The exact definition of a <strong><em>realm</em></strong> is left to the cloud provider.
+ In some cases, a <strong><em>realm</em></strong> may represent different datacenters, different continents,
+ or different pools of resources within a single datacenter. A cloud provider may
+ insist that resources must all exist within a single <strong><em>realm</em></strong> in order to cooperate.
+ For instance, storage volumes may only be allowed to be mounted to instances within
+ the same <strong><em>realm</em></strong>. Generally speaking, going from one <strong><em>realm</em></strong> to another within the same
+ cloud may change many aspects of the cloud, such as SLAâs, pricing terms, etc.</p>
+
+ <h4 id="h3_1_1"><code>GET /api/realms</code></h4>
+
+ <p>List all realms. Can be filtered by adding a request parameter <strong><em>architecture</em></strong>
+ to the realms that support a specific <strong><em>architecture</em></strong> such as <strong><em>i386</em></strong>. The example
+ below shows the retrieval of all <strong><em>realms</em></strong> for the AWS EC2 driver, which correspond
+ to EC2 "availability zones":</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/realms?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 639
<?xml version='1.0' encoding='utf-8' ?>
<realms>
 <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'>
 <name>us-east-1a</name>
 <state>available</state>
 </realm>
 <realm href='http://localhost:3001/api/realms/us-east-1b' id='us-east-1b'>
 <name>us-east-1b</name>
 <state>available</state>
 </realm>
 <realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'>
 <name>us-east-1c</name>
 <state>available</state>
 </realm>
 <realm href='http://localhost:3001/api/realms/us-east-1d' id='us-east-1d'>
 <name>us-east-1d</name>
 <state>available</state>�
00A; </realm>
</realms>
</code></pre>
+
+ <h4 id="h3_1_2"><code>GET /api/realms/:id</code></h4>
+
+ <p>Provide the details of a <strong><em>realm</em></strong>. Currently, these are a <strong><em>name</em></strong>, a <strong><em>state</em></strong> and a
+ <em><strong>limit</strong> applicable to the current requester. The </em><strong>name</strong><em> is an arbitrary label
+ with no specific meaning in the API. The </em><strong>state</strong><em> can be either </em><strong>AVAILABLE</strong><em>
+ or </em><strong>UNAVAILABLE</strong><em>. The example below shows the </em><strong>realm</strong><em> for the Rackspace driver.
+ Since Rackspace does not currently have a notion of </em><strong>realms</strong><em> the Deltacloud
+ Rackspace driver provides a single </em><strong>realm</strong>* called 'US', signifying that all
+ compute resources for that cloud provider are hosted in the United States:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/realms/us?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 182

<?xml version='1.0' encoding='utf-8' ?>
<realm href='http://localhost:3001/api/realms/us' id='us'>
 <name>United States</name>
 <state>AVAILABLE</state>
 <limit></limit>
</realm>
</code></pre>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h3_2">3.2 Hardware Profiles</h3>
+
+ <p>A <strong><em>hardware profile</em></strong> describes the sizing of a virtual machine in a cloud and
+ prescribes details such as how many virtual CPUs, how much memory or
+ how much local storage an instance might have. The attributes of a <strong><em>hardware profile</em></strong>
+ consist of a human-readable <strong><em>name</em></strong> and a list of <strong><em><property /></em></strong> elements.
+ Each property defines possible values along a sizing dimension.</p>
+
+ <p>Since clouds differ sharply in how virtual machine sizing is represented
+ and influenced, hardware profiles provide a generic mechanism to express sizing
+ constraints. For each dimension (amount of memory etc.), the hardware
+ profile can express one of the following:</p>
+
+ <ol>
+ <li>Size is <strong>fixed</strong> in this dimension, e.g. instances all have 2GB of memory, <em>or</em></li>
+ <li>Size can be varied freely within some <strong>range</strong>, e.g. instances can have
+ from 1GB to 4GB of memory, <em>or</em></li>
+ <li>Size can be chosen from a predefined set of values, an <strong>enumeration</strong>,
+ e.g., instances can have 512 MB, 1 GB or 4GB of memory.</li>
+ </ol>
+
+
+ <p>When creating a new <strong><em>instance</em></strong>, a client must specify the <strong><em>hardware profile</em></strong>
+ on which the <strong><em>instance</em></strong> is based.</p>
+
+ <p>In addition to the sizing constraints, a hardware profile may also indicate the
+ parameters (if any) that can be specified by a client in <strong><em>instance</em></strong> operations.
+ These user-defined, variable dimensions are denoted by a <em><param></em> XML tag within
+ the given property. For instance, the following extract shows the <em>memory</em> dimension
+ for a hardware profile that can be specified in the HTTP POST <em>create</em> operation of the
+ <strong><em>instances</em></strong> collection (i.e., creating a new instance). The given parameter must be
+ specified using the name <em>hwp_memory</em>, its default value is <em>10240</em> but the client may
+ specify a value in the range <em>7680</em> upto <em>15360</em>:</p>
+
+ <pre><code>...
<property kind='range' name='memory' unit='MB' value='10240'>
 <param href='http://localhost:3003/api/instances' method='post' name='hwp_memory' operation='create' />
 <range first='7680.0' last='15360' />
</property>
...
</code></pre>
+
+ <h4 id="h3_2_1"><code>GET /api/hardware_profiles</code></h4>
+
+ <p>Produce a list if all <strong><em>hardware profiles</em></strong> availaible with this cloud. The example
+ below lists the hardware profiles available in the Amazon EC2 cloud. As EC2 provides
+ a set of pre-defined <strong><em>hardware profiles</em></strong>, the properties of each dimension
+ (memory,cpu etc) are of type <em>fixed</em>:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/hardware_profiles?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 3896
<?xml version='1.0' encoding='utf-8' ?>
<hardware_profiles>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/t1.micro' id='t1.micro'>
 <name>t1.micro</name>
 <property kind='fixed' name='cpu' unit='count' value='1' />
 <property kind='fixed' name='memory' unit='MB' value='645.12' />
 <property kind='fixed' name='architecture' unit='label' value='i386' />
 <property kind='fixed' name='storage' unit='GB' value='160' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.small' id='m1.small'>
 <name>m1.small</name>
 <property kind='fixed' name='cpu' unit='count' value='1' />
 <property kind='fixed' name='memory' unit='
MB' value='1740.8' />
 <property kind='fixed' name='architecture' unit='label' value='i386' />
 <property kind='fixed' name='storage' unit='GB' value='160' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.large' id='m1.large'>
 <name>m1.large</name>
 <property kind='fixed' name='cpu' unit='count' value='4' />
 <property kind='fixed' name='memory' unit='MB' value='7680.0' />
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='storage' unit='GB' value='850' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.xlarge' id='m1.xlarge'>
 <name>m1.xlarge</name>
 <property kind='fixed' name='cpu' unit='count' value='8' />

<property kind='fixed' name='memory' unit='MB' value='15360' />
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='storage' unit='GB' value='1690' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'>
 <name>c1.medium</name>
 <property kind='fixed' name='cpu' unit='count' value='5' />
 <property kind='fixed' name='memory' unit='MB' value='1740.8' />
 <property kind='fixed' name='architecture' unit='label' value='i386' />
 <property kind='fixed' name='storage' unit='GB' value='350' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.xlarge' id='c1.xlarge'>
 <name>c1.xlarge</name>
 <property kind='fixed
' name='cpu' unit='count' value='20' />
 <property kind='fixed' name='memory' unit='MB' value='7168' />
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='storage' unit='GB' value='1690' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m2.xlarge' id='m2.xlarge'>
 <name>m2.xlarge</name>
 <property kind='fixed' name='cpu' unit='count' value='6.5' />
 <property kind='fixed' name='memory' unit='MB' value='17510.4' />
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='storage' unit='GB' value='420' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m2.2xlarge' id='m2.2xlarge'>
 <name>
m2.2xlarge</name>
 <property kind='fixed' name='cpu' unit='count' value='13' />
 <property kind='fixed' name='memory' unit='MB' value='35020.8' />
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='storage' unit='GB' value='850' />
 </hardware_profile>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m2.4xlarge' id='m2.4xlarge'>
 <name>m2.4xlarge</name>
 <property kind='fixed' name='cpu' unit='count' value='26' />
 <property kind='fixed' name='memory' unit='MB' value='70041.6' />
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
 <property kind='fixed' name='storage' unit='GB' value='1690' />
 </hardware_profile>
</hardware_profiles>
</code></pre>
+
+ <h4 id="h3_2_2"><code>GET /api/hardware profiles/:id</code></h4>
+
+ <p>This call retrieves the details of a specific <strong><em>hardware profile</em></strong>.
+ The example below shows a request for the <em>m1-large</em> profile of the Deltacloud <em>mock</em> driver.
+ This <strong><em>hardware profile</em></strong> demonstrates the three different types of parameters (i.e.,
+ <em>fixed</em>, <em>range</em>, <em>enum</em>). The example shows that <strong><em>instances</em></strong> launched with this
+ <strong><em>hardware profile</em></strong> will have exactly <em>2</em> virtual CPUs, memory in the range <em>7.5</em> to
+ <em>15GB</em> and local storage that can either be 850MB or 1GB. The default value for
+ each dimension is indicated by the value attribute on the property element:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/hardware_profiles/m1-large?format=xml HTTP/1.1
Authorization: Basic bW9ja3VzZXI6bW9ja3Bhc3N3b3Jk
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3003
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 808

<?xml version='1.0' encoding='utf-8' ?>
<hardware_profile href='http://localhost:3003/api/hardware_profiles/m1-large' id='m1-large'>
 <name>m1-large</name>
 <property kind='fixed' name='cpu' unit='count' value='2' />
 <property kind='range' name='memory' unit='MB' value='10240'>
 <param href='http://localhost:3003/api/instances' method='post' name='hwp_memory' operation='create' />
 <range first='7680.0' last='15360' />
 </property>
 <property kind='enum' name='storage' unit='GB' value='850'>
 <param href='http://localhost:3003/api/instances' method='post' name='hwp_storage' operation='create' />
 <enum>
 <entry value='850' />
 <entry value='1024' />
 </enum&
gt;
 </property>
 <property kind='fixed' name='architecture' unit='label' value='x86_64' />
</hardware_profile>
</code></pre>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h3_3">3.3 Images</h3>
+
+ <p><strong><em>Images</em></strong> are used to launch <strong><em>instances</em></strong>. Each <strong><em>image</em></strong> represents
+ a virtual machine image in the back-end cloud, containing the root
+ partition and initial storage for an instance operating system.</p>
+
+ <p>An <strong><em>image</em></strong> has human-readable <em>name</em> and <em>description</em>, an <em>owner_id</em>
+ that identifies the user account to which the <strong><em>image</em></strong> belongs, as well as
+ an <em>architecture</em> and a <em>state</em>. The <em>architecture</em> attribute refers to whether the
+ <strong><em>image</em></strong> will create an <strong><em>instance</em></strong> with <em>32</em> or <em>64</em> bit processor; the values
+ that the Deltacloud server returns for this attribute are thus <em>i386</em> and <em>x86_64</em> respectively.
+ The <em>state</em> attribute is as reported by the cloud provider and so will vary between back-end clouds.
+ For example AWS EC2 <strong><em>image</em></strong> state can be one of <em>AVAILABLE</em>, <em>PENDING</em> or <em>FAILED</em>
+ whereas Rackspace Cloudservers <strong><em>image</em></strong> state can be one of <em>UNKNOWN</em>, <em>PREPARING</em>,
+ <em>ACTIVE</em>, <em>QUEUED</em> or <em>FAILED</em>. Finally, each <strong><em>image</em></strong> also contains an <actions>
+ attribute that specifies the URI to which a client may issue a <strong>HTTP POST</strong> for creation of
+ an <strong><em>instance</em></strong> from the given <strong><em>image</em></strong>.</p>
+
+ <h4 id="h3_3_1"><code>GET /api/images</code></h4>
+
+ <p>Return a list of all <strong><em>images</em></strong> available in the back-end cloud. By default this call will
+ return <strong>all</strong> images that are available to the given user account. Optionally a client
+ may restrict the list of <strong><em>images</em></strong> returned by specifying the <strong>owner_id</strong> or <strong>architecture</strong>
+ parameters in the request (<strong>architecture</strong> is one of <em>x86_64</em> for 64-bit processors or <em>i386</em>
+ for 32-bit processors). The example below restricts the image list to <strong>64-bit</strong> architecture images
+ belonging to <strong>owner_id 023801271342</strong>:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/images?owner_id=023801271342&architecture=x86_64&format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1971

<?xml version='1.0' encoding='utf-8' ?>
<images>
 <image href='http://localhost:3001/api/images/ami-eea35787' id='ami-eea35787'>
 <name>sles-10-sp3-v1.00.x86_64</name>
 <owner_id>013907871322</owner_id>
 <description>SUSE Linux Enterprise Server 10 Service Pack 3 for x86_64 (v1.00)</description>
 <architecture>x86_64</architecture>
 <state></state>
 <actions>
 <link href='http://localhost:3001/api/instances;image_id=ami-eea35787' method='post' rel='create_instance' />
 </actions>
 </image>
 <image href='http://localhost:3001/api/images/ami-6e649707' id='ami-6e649707'>
 <name>sles-11-sp1-hvm-v1.00.x86_64</name>
 &l
t;owner_id>013907871322</owner_id>
 <description>SUSE Linux Enterprise Server 11 Service Pack 1 for HVM x86_64 (v1.00)</description>
 <architecture>x86_64</architecture>
 <state></state>
 <actions>
 <link href='http://localhost:3001/api/instances;image_id=ami-6e649707' method='post' rel='create_instance' />
 </actions>
 </image>
 <image href='http://localhost:3001/api/images/ami-e4a7558d' id='ami-e4a7558d'>
 <name>sles-11-sp1-hvm-v1.01.x86_64</name>
 <owner_id>013907871322</owner_id>
 <description>SUSE Linux Enterprise Server 11 Service Pack 1 for HVM x86_64 (v1.01)</description>
 <architecture>x86_64</architecture>
 <state></state>
 <actions>
 <link href='http://localhost:3001/api/inst
ances;image_id=ami-e4a7558d' method='post' rel='create_instance' />
 </actions>
 </image>
 <image href='http://localhost:3001/api/images/ami-e4a3578d' id='ami-e4a3578d'>
 <name>sles-11-sp1-v1.00.x86_64</name>
 <owner_id>013907871322</owner_id>
 <description>SUSE Linux Enterprise Server 11 Service Pack 1 for x86_64 (v1.00)</description>
 <architecture>x86_64</architecture>
 <state></state>
 <actions>
 <link href='http://localhost:3001/api/instances;image_id=ami-e4a3578d' method='post' rel='create_instance' />
 </actions>
 </image>
</images>
</code></pre>
+
+ <h4 id="h3_3_2"><code>GET /api/images/:id</code></h4>
+
+ <p>Retrieve the description of a specific <strong><em>image</em></strong>.</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/images/14?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 433

<?xml version='1.0' encoding='utf-8' ?>
<image href='http://localhost:3002/api/images/14' id='14'>
 <name>Red Hat Enterprise Linux 5.4</name>
 <owner_id>jsmith</owner_id>
 <description>Red Hat Enterprise Linux 5.4</description>
 <architecture>x86_64</architecture>
 <state>ACTIVE</state>
 <actions>
 <link href='http://localhost:3002/api/instances;image_id=14' method='post' rel='create_instance' />
 </actions>
</image>
</code></pre>
+
+ <h4 id="h3_3_3"><code>POST /api/images</code></h4>
+
+ <p>Create a new <strong><em>image</em></strong> from an existing, running <strong><em>instance</em></strong>. This operation is not
+ available in all cloud providers and for some cloud providers this operation is not
+ possible for all <strong><em>instances</em></strong>. For example, in the Amazon EC2 cloud, a custom
+ <strong><em>image</em></strong> can be created from EBS backed <strong><em>instances</em></strong> but not from <strong><em>root-store</em></strong>
+ instances. The Deltacloud API provides a mechanism with which clients can determine whether
+ a given <strong><em>instance</em></strong> may be saved as a custom <strong><em>image</em></strong>. For those cases where
+ <strong><em>instance</em></strong> 'snapshot' is possible, the <strong><em>instance</em></strong> XML <actions> list will
+ contain a <strong>create_image</strong> action that defines the URI for a client to use in creating
+ the new image. For example:</p>
+
+ <pre><code>...
<actions>
 <link href='http://localhost:3002/api/instances/20109341/reboot' method='post' rel='reboot' />
 <link href='http://localhost:3002/api/instances/20109341/stop' method='post' rel='stop' />
 <link href='http://localhost:3002/api/instances/20109341/run;id=20109341' method='post' rel='run' />
 <link href='http://localhost:3002/api/images;instance_id=20109341' method='post' rel='create_image' />
</actions>
...
</code></pre>
+
+ <p>To create a new <strong><em>image</em></strong> the client must specify the <em>instance_id</em> of the running instance.
+ Optionally, the client may also provide a <em>name</em> and a <em>description</em>. The parameters are
+ specified as multipart/form-data fields in the client POST. The Deltacloud server will
+ respond to a successful operation with <strong>HTTP 201 Created</strong> and provide details of the
+ newly created <strong><em>image</em></strong>:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>POST /api/images?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
Content-Length: 404
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------ba9acb193034

------------------------------ba9acb193034
Content-Disposition: form-data; name="instance_id"

20109341
------------------------------ba9acb193034
Content-Disposition: form-data; name="name"

customisedserver
------------------------------ba9acb193034
Content-Disposition: form-data; name="description"

jsmith customised web server July 21 2011
------------------------------ba9acb193034--
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 201 Created
Content-Type: application/xml
Content-Length: 427

<?xml version='1.0' encoding='utf-8' ?>
<image href='http://localhost:3002/api/images/12346145' id='12346145'>
 <name>customisedserver</name>
 <owner_id>mandreou</owner_id>
 <description>customisedserver</description>
 <architecture>x86_64</architecture>
 <state>QUEUED</state>
 <actions>
 <link href='http://localhost:3002/api/instances;image_id=12346145' method='post' rel='create_instance' />
 </actions>
</image>
</code></pre>
+
+ <h4 id="h3_3_4"><code>DELETE /api/images/:id</code></h4>
+
+ <p>Deletes the specified <strong><em>image</em></strong> from the back-end cloud. The Deltacloud server
+ will return a <strong>HTTP 204 No Content</strong> after a succesful operation:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>DELETE /api/images/12346145?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 204 No Content
</code></pre>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h3_4">3.4 Instance States</h3>
+
+ <p>Each cloud defines a slightly different lifecycle model for <strong><em>instances</em></strong>. In some
+ clouds, <strong><em>instances</em></strong> start running immediately after creation, in others, they
+ enter a pending state and they need to be explicitly started to become
+ running.</p>
+
+ <p>These differences between clouds are modelled by expressing the lifecycle
+ of an instance as a finite state machine and capturing this in a <strong><em>instance states</em></strong>
+ entity. The start state of the automaton is start and its final state is
+ finished. The API defines the following states for an <strong><em>instance</em></strong>:</p>
+
+ <h5>Instance states and their meanings:</h5>
+
+ <pre><code>State Meaning
----- -------
start Instances are in this state before they are created
--
pending Creation of the instance has been requested and is in progress
--
running The instance is running
--
shutting-down A shutdown has been requested for the instance and is in progress
--
stopped The instance is stopped
--
finished All resources for this instance have now been freed
</code></pre>
+
+ <p>The actions (state transitions) possible for an <strong><em>instance</em></strong> are as shown below.
+ The precise actions that can be performed on a specific <strong><em>instance</em></strong> are
+ expressed as part of the details for that <strong><em>instance</em></strong>.</p>
+
+ <h5>Instance actions and their meanings:</h5>
+
+ <pre><code>Action Meaning
------ -------
start Start the instance
--
stop Stop (and for some providers, Shutdown) the instance
--
reboot Reboot the instance
--
destroy Stop the instance and completely destroy it
</code></pre>
+
+ <h4 id="h3_4_1"><code>GET /api/instance_states</code></h4>
+
+ <p>This call retrieves the <strong><em>instance_states</em></strong> entity for a back-end cloud. The <strong><em>instance_states</em></strong>
+ entity defines the transitions possible between the various states of an <strong><em>instance</em></strong>,
+ and these are back-end cloud specific. In effect <strong><em>instance_states</em></strong> defines the finite state
+ machine for <strong><em>instances</em></strong> from the given cloud.</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/instance_states?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 583

<states>
 <state name='start'>
 <transition action='create' to='pending'></transition>
 </state>
 <state name='pending'>
 <transition auto='true' to='running'></transition>
 </state>
 <state name='running'>
 <transition action='reboot' to='running'></transition>
 <transition action='stop' to='shutting_down'></transition>
 </state>
 <state name='shutting_down'>
 <transition auto='true' to='stopped'></transition>
 </state>
 <state name='stopped'>
 <transition auto='true' to='finish'></transition>
 </state>
 <state name='finish'>
 </state>
</states>�
00A;</code></pre>
+
+ <br />
+
+
+ <p><a href="#toc">Contents</a></p>
+
+ <br />
+
+
+ <hr />
+
+ <h3 id="h3_5">3.5 Instances</h3>
+
+ <p>An <strong><em>instance</em></strong> represents the focus of all cloud compute activity: a running
+ virtual machine. An <strong><em>instance</em></strong> is created from an <strong><em>image</em></strong>, with a specified
+ <strong><em>hardware profile</em></strong> and in a given <strong><em>realm</em></strong>. Each <strong><em>instance</em></strong> can have a
+ number of other attributes, not all of which are exposed for all back-end cloud
+ providers. The full list of possible <strong><em>instance</em></strong> attributes is:</p>
+
+ <pre><code>Attribute Meaning
--------- -------
owner_id The id of the cloud provider account that launched the instance
--
image_id The id of the image from which the instance was launched
--
name A human readable name for the instance given at launch time
--
realm_id Realm into which the instance was launced
--
state Current state of the instance (e.g., 'running')
--
actions Actions that a client may effect on the instance, based on current state.
--
public_addresses The globally routable IP address of the instance
--
private_addresses The private IP address of the instance, routable within its private network
--
instance_profile The specific values of memory, cpu, storage
--
launch_time Timestamp at which the instance w
as launched
--
keyname Name of authentication Key, if this method is used for authentication (e.g., EC2)
--
username The username for authentication when connecting to the instance
--
password The password used together with username above.
--
firewalls The firewalls that this instance was launched into (EC2 specific)
--
</code></pre>
+
+ <h4 id="h3_5_1"><code>GET /api/instances</code></h4>
+
+ <p>Produce a listing of all current <strong><em>Instances</em></strong> in the given cloud (belonging to
+ the specified account). The example shown below displays <strong><em>instances</em></strong> in the Amazon EC2 cloud:</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/instances?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
</code></pre>
+
+ <p><code>Client response:</code></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 2790
<?xml version='1.0' encoding='utf-8' ?>
<instances>
 <instance href='http://localhost:3001/api/instances/i-1fbc627e' id='i-1fbc627e'>
 <name>ami-f51aff9c</name>
 <owner_id>393485797142</owner_id>
 <image href='http://localhost:3001/api/images/ami-f51aff9c' id='ami-f51aff9c'></image>
 <realm href='http://localhost:3001/api/realms/us-east-1c' id='us-east-1c'></realm>
 <state>RUNNING</state>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/c1.medium' id='c1.medium'>
 </hardware_profile>
 <actions>
 <link href='http://localhost:3001/api/instances/i-1fbc627e/reboot' method='post' rel='reboot' />
 <link href='http://localhost:3001/api/i
nstances/i-1fbc627e/stop' method='post' rel='stop' />
 <link href='http://localhost:3001/api/instances/i-1fbc627e/run;id=i-1fbc627e' method='post' rel='run' />
 </actions>
 <launch_time>2011-07-22T11:29:48.000Z</launch_time>
 <public_addresses><address>ec2-50-16-183-107.compute-1.amazonaws.com</address></public_addresses>
 <private_addresses><address>domU-12-31-39-0F-79-D4.compute-1.internal</address></private_addresses>
 <firewalls>
 <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall>
 </firewalls>
 <authentication type='key'>
 <login>
 <keyname>eftah</keyname>
 </login>
 </authentication>
 </instance>
 <instance href='http://localhost:3001/api
/instances/i-f3ba6492' id='i-f3ba6492'>
 <name>ami-2b5fba42</name>
 <owner_id>393485797142</owner_id>
 <image href='http://localhost:3001/api/images/ami-2b5fba42' id='ami-2b5fba42'></image>
 <realm href='http://localhost:3001/api/realms/us-east-1d' id='us-east-1d'></realm>
 <state>RUNNING</state>
 <hardware_profile href='http://localhost:3001/api/hardware_profiles/m1.small' id='m1.small'>
 </hardware_profile>
 <actions>
 <link href='http://localhost:3001/api/instances/i-f3ba6492/reboot' method='post' rel='reboot' />
 <link href='http://localhost:3001/api/instances/i-f3ba6492/stop' method='post' rel='stop' />
 <link href='http://localhost:3001/api/instances/i-f3ba6492/run;id=i-f3ba6492' method='post' rel='run' />
 </actions>
 <launch_ti
me>2011-07-22T11:32:25.000Z</launch_time>
 <public_addresses><address>ec2-184-73-78-87.compute-1.amazonaws.com</address></public_addresses>
 <private_addresses><address>ip-10-196-89-221.ec2.internal</address></private_addresses>
 <firewalls>
 <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall>
 <firewall href='http://localhost:3001/api/firewalls/test' id='test'></firewall>
 </firewalls>
 <authentication type='key'>
 <login>
 <keyname>eftah</keyname>
 </login>
 </authentication>
 </instance>
</instances>
</code></pre>
+
+ <h4 id="h3_5_2"><code>GET /api/instances/:id</code></h4>
+
+ <p>Get the details for a specific <strong><em>Instance</em></strong>. The example shown below is for an <strong><em>instance</em></strong>
+ launched in the Rackspace Cloudservers cloud. As can be seen, the authentication type used is
+ <strong>password</strong> but the <em>username</em> and <em>password</em> attributes are blank. This is because Rackspace
+ only reports these values once, during instance creation and not for subsequent requests.
+ An example of the response from <strong><em>instance</em></strong> creation can be found under the
+ <a href="#create_instance">POST /api/instances</a> subsection below, showing how the<em>username</em>/<em>password</em>
+ fields are populated.</p>
+
+ <p><code>Example request:</code></p>
+
+ <pre><code>GET /api/instances/20112212?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3002
Accept: */*
</code></pre>
+
+ <p><code>Server response:</code>
+ <a name="get_instance"> .</a></p>
+
+ <pre><code>HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1167
<?xml version='1.0' encoding='utf-8' ?>
<instance href='http://localhost:3002/api/instances/20112212' id='20112212'>
 <name>myserver</name>
 <owner_id>mandreou</owner_id>
 <image href='http://localhost:3002/api/images/53' id='53'></image>
 <realm href='http://localhost:3002/api/realms/us' id='us'></realm>
 <state>RUNNING</state>
 <hardware_profile href='http://localhost:3002/api/hardware_profiles/1' id='1'>
 </hardware_profile>
 <actions>
 <link href='http://localhost:3002/api/instances/20112212/reboot' method='post' rel='reboot' />
 <link href='http://localhost:3002/api/instances/20112212/stop' method='post' rel='stop' />
 <link href='http://localhost:3002/api/instan
ces/20112212/run;id=20112212' method='post' rel='run' />
 <link href='http://localhost:3002/api/images;instance_id=20112212' method='post' rel='create_image' />
 </actions>
 <public_addresses><address>50.57.116.72</address></public_addresses>
 <private_addresses><address>10.182.143.64</address></private_addresses>
 <authentication type='password'>
 <login>
 <username>root</username>
 <password></password>
 </login>
 </authentication>
</instance>
</code></pre>
+
+ <h4 id="h3_5_3"><code>POST /api/instances/:id/:action</code></h4>
+
+ <p>The valid actions for an <strong><em>instance</em></strong> are specified by the <strong><em>instance_states</em></strong> entity.
+ The set of permissible actions that a client may effect on an <strong><em>instance</em></strong> at a given time
+ depends on the current <strong><em>instance state</em></strong>. These are as reported by the <actions> attribute
+ in the Deltacloud server response to a <a href="#get_instance">GET /api/instances/:id</a> call. The first
+ example shown below is to <strong>reboot</strong> a currently running instance, followed by a <strong>stop</strong>.</p>
+
+ <p>Note that after invoking the <strong>stop</strong> operation, the <strong><em>instance</em></strong> state may be reported as <strong>RUNNING</strong>
+ in the Deltacloud server response. This is because it may take some time for the <strong><em>instance</em></strong> state
+ to change in the backend cloud provider (and this will vary between providers). Subsequent requests
+ for either the list of <strong><em>instances</em></strong> or a specific <strong><em>instance</em></strong> will confirm that the action was
+ effected correctly.</p>
+
+ <p>The Deltacloud server also allows a special 'run-on-instance' action for some cloud provider
+ <strong><em>instances</em></strong>.This enables a client to perform a command on a running <strong><em>instance</em></strong> over
+ <strong>SSH</strong> and the Deltacloud server will return the output of that command to the client.
+ Where available, this is reported as the <strong>run</strong> action in the list of <strong><em>instance</em></strong>
+ actions. The command to be executed on the running <strong><em>instance</em></strong> is specified by the
+ <strong>cmd</strong> parameter, whilst authentication is specified either by the <strong>private_key</strong> parameter
+ for cloud providers that expect key based authentication for connecting to <strong><em>instances</em></strong>
+ or the <strong>password</strong> parameter for those cloud providers that use a <strong>username/password</strong> for
+ authentication. The last examples shown below illustrate the 'run-on-instance' feature for
+ an Amazon EC2 <strong><em>instance</em></strong> and a Rackspace Cloudservers <strong><em>instance</em></strong>. The two examples
[... 976 lines stripped ...]