You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltacloud.apache.org by ma...@apache.org on 2012/06/25 17:05:57 UTC
svn commit: r1353588 [8/23] - in /deltacloud/trunk/site: ./ content/
content/Scripts/ content/assets/ content/assets/css/ content/assets/img/
content/assets/img/documentation_files/ content/assets/js/
content/assets/less/ content/css/ content/css/bluep...
Added: deltacloud/trunk/site/content/install-deltacloud.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/install-deltacloud.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/install-deltacloud.md (added)
+++ deltacloud/trunk/site/content/install-deltacloud.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,139 @@
+---
+site_name: Deltacloud API
+title: Install Deltacloud
+---
+<br/>
+<h3> Installation dependencies</h3>
+<p>First of all, you have to install several dependecies. The Deltacloud server relies on a number of external rubygems and other libraries. The following packages are neccessary for running the Deltacloud server. The installation of dependencies slightly differs from distribution to distribution. You will need:</p>
+
+<ul>
+ <li>
+ ruby and ruby-devel,
+ </li>
+ <li>
+ gem (RubyGems),
+ </li>
+ <li>
+ gcc-c++
+ </li>
+ <li>
+ libxml2 and libxml2-devel,
+ </li>
+ <li>
+ libxslt and libxslt-devel,
+ </li>
+ <li>
+ rake.
+ </li>
+</ul>
+
+<br/>
+
+<h3>Fedora and Red Hat Enterprise Linux</h3>
+
+<h4>Ruby and Ruby-devel</h4>
+<p>Check if you already have a <a href="http://www.ruby-lang.org/en/downloads/">Ruby installation</a> by typing the following command. You should see something that looks like:</p>
+
+<pre>
+$ ruby -v
+ruby 1.8.7 (2010-08-16 patchlevel 302) [i686-linux]
+</pre>
+
+<p>Deltacloud requires at least Ruby 1.8.7. You need to install also the development headers (ruby-devel) because Deltacloud relies on some rubygems with C extensions. According to your package manager use commands: </p>
+
+<pre>
+$ sudo yum install ruby
+$ sudo yum install ruby-devel
+</pre>
+
+<h4>RubyGems</h4>
+<p>Deltacloud relies on a number of <a href="http://docs.rubygems.org/read/chapter/3">RubyGems</a>. You can check if you already have gem executable (similarly to ruby) by typing <code>$ gem -v</code>. Otherwise use your package manager for the installation: </p>
+
+<pre>
+$ sudo yum install rubygems
+</pre>
+
+<h4>GCC-C++, Libxml2, Libxml2-devel, Libxslt, Libxslt-devel</h4>
+<p>These libraries are required to build RubyGems that have C extensions. Use commands:</p>
+
+<pre>
+$ sudo yum install gcc-c++
+$ sudo yum install libxml libxml2-devel
+$ sudo yum install libxslt libxslt-devel
+</pre>
+
+<h4>Rake</h4>
+<p><a href="http://rake.rubyforge.org/">Rake</a> is Ruby's Make and is itself a ruby gem. Once you have RubyGems installed you can get rake with:</p>
+
+<pre>$ sudo gem install rake</pre>
+
+<br/>
+
+<h3>Debian and Ubuntu</h3>
+
+<h4>Ruby and RubyGems</h4>
+The following instructions focus on installing Ruby 1.9 (Deltacloud requires at least ruby 1.8.7.). Install ruby and rubygem by typing:
+
+<pre>$ sudo apt-get install ruby1.9.1-full</pre>
+
+Use the following command to check, whether the installation was successful. You should see a similar response:
+
+<pre>
+$ ruby -v
+ruby 1.9.2p290 (2011-07-09 revision 32553) [i686-linux]
+</pre>
+
+You can check the installation of Rubygems the same way:
+
+<pre>
+$ gem -v
+1.3.7
+</pre>
+
+<h4>G++, Libxml2, Libxml2-dev, Libxslt, Libxslt-dev</h4>
+<p>These libraries are required to build RubyGems that have C extensions. Use commands:</p>
+
+<pre>
+$ sudo apt-get install g++
+$ sudo apt-get install libxml libxml2-dev
+$ sudo apt-get install libxslt libxslt-dev
+</pre>
+
+<h4 id="gem-list">Gem dependecies</h4>
+<p>Debian and Ubuntu distributions also require to install following gem dependencies:
+<pre>
+gem install thin sinatra rack-accept rest-client sinatra-content-for nokogiri
+</pre>
+Once these gems are installed, go to the directory (normally <strong>/var/lib/gems/1.9.1/gems</strong>), where gems are located and check that you have following gems listed. You may see more gems than you directly installed, because RubyGems install gem dependecies automaticly.
+</p>
+
+<br/>
+
+<div class="row">
+ <div class="span1"></div>
+ <div class="span10 offset1">
+ <blockquote>Aws-2.5.6, builder-3.0.0, bundler-1.1.3, daemons-1.1.8, eventmachine-0.12.10, haml-3.1.4, http_connection-1.4.1, json-1.6.6, mime-types-1.18, net-ssh-2.3.0, nokogiri-1.5.2, rack-1.4.1, rake-0.9.2.2, rack-accept-0.4.4, rack-protection-1.2.0, rest-client-1.6.7, sinatra-1.3.2, sinatra-content-for-0.1, thin-1.3.1, tilt-1.3.3, uuidtools-2.1.2, xml-simple-1.1.1
+ </blockquote>
+ </div>
+</div>
+
+<p>
+You may have trouble with the installation, if the Makefile is missing. Then, you need to install make:
+</p>
+
+<pre>
+$ sudo apt-get install make
+</pre>
+
+<br/>
+
+<h3>Installation of Deltacloud itself</h3>
+<p>Once you've setup all the dependencies listed above, installing Deltacloud is as easy. Type:</p>
+
+<pre>$ sudo gem install deltacloud-core</pre>
+
+<p><strong>And thats it!</strong> The gem install command will automatically fetch and install all other gems that the Deltacloud server needs. As an alternative you can get the latest releases of Deltacloud from the <a href="http://www.apache.org/dist/deltacloud/">Apache website</a>.</p>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/run-deltacloud-server.html">Run Deltacloud</a>
+
+<br/>
Added: deltacloud/trunk/site/content/instance-states.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/instance-states.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/instance-states.md (added)
+++ deltacloud/trunk/site/content/instance-states.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,159 @@
+---
+site_name: Deltacloud API
+title: Instance states
+---
+<br/>
+
+<div class="row">
+ <div class="span9">
+
+<h3 id="instance-states">Instance states</h3>
+
+<p>
+Each cloud defines a slightly different lifecycle model for instances. In some clouds, instances start running immediately after creation, in others, they enter a pending state and you need to start them explicitly.
+</p>
+
+<p>
+Differences between clouds are modelled by expressing the lifecycle of an instance as a finite state machine and capturing it in an instance states entity.The API defines the following states for an instance:</p>
+
+<table class="table table-condensed table-striped">
+ <thead>
+ <tr>
+ <th>State</th>
+ <th>Meaning</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>start</td>
+ <td>an instance state before creation of an instance</td>
+ </tr>
+ <tr>
+ <td>pending</td>
+ <td>creation of an instance is in progress</td>
+ </tr>
+ <tr>
+ <td>running</td>
+ <td>an instance is running</td>
+ </tr>
+ <tr>
+ <td>shutting-down</td>
+ <td>an instance is stopped</td>
+ </tr>
+ <tr>
+ <td>stopped</td>
+ <td>an instance is stopped</td>
+ </tr>
+ <tr>
+ <td>finished</td>
+ <td>all resources for an instance have now been freed</td>
+ </tr>
+ </tbody>
+</table>
+
+ </div>
+ <div class="span3">
+
+<ul class="nav nav-list well">
+ <li class="nav-header">
+ REST API
+ </li>
+ <li><a href="/rest-api.html">Introduction</a></li>
+ <li><a href="/api-entry-point.html">API entry point</a></li>
+ <li><a href="/compute-resources.html">Compute resources</a></li>
+ <ul class="nav nav-list">
+ <li><a href="/compute-resources.html">Realms</a></li>
+ <li><a href="/hardware-profiles.html">Hardware profiles</a></li>
+ <li><a href="/images.html">Images</a></li>
+ <li class="active"><a href="#instance-states">Instance states</a></li>
+ <li><a href="/instances.html">Instances</a></li>
+ <li><a href="/keys.html">Keys</a></li>
+ <li><a href="/firewalls.html">Firewalls</a></li>
+ <li><a href="/addresses.html">Addresses</a></li>
+ <li><a href="/load-balancers.html">Load balancers</a></li>
+ </ul>
+ <li><a href="/storage-resources.html">Storage resources</a></li>
+</ul>
+
+ </div>
+</div>
+
+<p>
+The details of a particular instance describes also the actions (state transitions) which can be performed on the instance. If the state transition is marked as <strong>auto</strong>, the transition from one state to another is done automatically. The possible instance actions are:
+</p>
+
+
+<table class="table table-condensed table-striped">
+ <thead>
+ <tr>
+ <th>Action</th>
+ <th>Meaning</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>start</td>
+ <td>starts the instance</td>
+ </tr>
+ <tr>
+ <td>stop</td>
+ <td>stops (and for some providers shutdown) the instance</td>
+ </tr>
+ <tr>
+ <td>reboot</td>
+ <td>reboots the instance</td>
+ </tr>
+ <tr>
+ <td>destroy</td>
+ <td>stops the instance and completely destroys it</td>
+ </tr>
+ </tbody>
+</table>
+
+
+<h4>Get an instance states entity</h4>
+
+To retrieve the instance states entity for a back-end cloud use call <strong>GET /api/instance_states</strong>. The instance states entity defines possible transitions between various states of an instance, specific for each back-end cloud. As a result, instance states defines the finite state machine for instances from the given cloud.
+
+<p>Example request:</p>
+
+<pre>
+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: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+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>
+</pre>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/instances.html">Instances <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a>
+
+<br/>
Added: deltacloud/trunk/site/content/instances.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/instances.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/instances.md (added)
+++ deltacloud/trunk/site/content/instances.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,633 @@
+---
+site_name: Deltacloud API
+title: Instances
+---
+
+<br/>
+
+<div class="row">
+ <div class="span9">
+
+<h3 id="instances">Instances</h3>
+
+<p>
+An instance represents the core of all cloud compute activity: a running virtual machine. An instance is created from an image, with a specified hardware profile and in a given realm. Each instance can have a number of other attributes, not all of which are exposed for all back-end cloud providers. The full list of possible instance attributes is:
+</p>
+
+<table class="table table-condensed table-striped">
+ <thead>
+ <tr>
+ <th>Attribute</th>
+ <th>Meaning</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>owner_id</td>
+ <td>the id of the cloud provider account that launched the instance</td>
+ </tr>
+ <tr>
+ <td>image_id</td>
+ <td>the id of the image from which the instance was launched</td>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>a human readable name for the instance given at launch time</td>
+ </tr>
+ <tr>
+ <td>realm_id</td>
+ <td>realm into which the instance was launched</td>
+ </tr>
+ <tr>
+ <td>state</td>
+ <td>current state of the instance (e.g. 'running')</td>
+ </tr>
+ <tr>
+ <td>actions</td>
+ <td>actions that a client may effect on the instance, based on current state</td>
+ </tr>
+ <tr>
+ <td>public_addresses</td>
+ <td>the globally routable IP address of the instance</td>
+ </tr>
+ <tr>
+ <td>private_addresses</td>
+ <td>the private IP address of the instance, routable within its private network</td>
+ </tr>
+ <tr>
+ <td>instance_profile</td>
+ <td>the specific values of memory, cpu, storage</td>
+ </tr>
+ <tr>
+ <td>launch_time</td>
+ <td>timestamp at which the instance was launched</td>
+ </tr>
+ <tr>
+ <td>keyname</td>
+ <td>name of authentication key, if this method is used for authentication (e.g. EC2)</td>
+ </tr>
+ <tr>
+ <td>username</td>
+ <td>the username for authentication when connecting to the instance</td>
+ </tr>
+ <tr id="instance">
+ <td>password</td>
+ <td>the password used together with username above</td>
+ </tr>
+ <tr>
+ <td>firewalls</td>
+ <td>the firewalls that this instance was launched into (EC2 specific)</td>
+ </tr>
+ </tbody>
+</table>
+
+ </div>
+ <div class="span3">
+
+<ul class="nav nav-list well">
+ <li class="nav-header">
+ REST API
+ </li>
+ <li><a href="/rest-api.html">Introduction</a></li>
+ <li><a href="/api-entry-point.html">API entry point</a></li>
+ <li><a href="/compute-resources.html">Compute resources</a></li>
+ <ul class="nav nav-list">
+ <li><a href="/compute-resources.html">Realms</a></li>
+ <li><a href="/hardware-profiles.html">Hardware profiles</a></li>
+ <li><a href="/images.html">Images</a></li>
+ <li><a href="/instance-states.html">Instance states</a></li>
+ <li class="active"><a href="#instances">Instances</a></li>
+ <li><a href="/keys.html">Keys</a></li>
+ <li><a href="/firewalls.html">Firewalls</a></li>
+ <li><a href="/addresses.html">Addresses</a></li>
+ <li><a href="/load-balancers.html">Load balancers</a></li>
+ </ul>
+ <li><a href="/storage-resources.html">Storage resources</a></li>
+</ul>
+
+ </div>
+</div>
+
+<ul class="nav nav-pills">
+ <li id="instance1" class="active"><a href="#tab1" data-toggle="tab">Get a list of all instances</a></li>
+ <li id="instance2"><a href="#tab2" data-toggle="tab">Get the details of an instance</a></li>
+ <li id="instance3"><a href="#tab3" data-toggle="tab">Launch an action</a></li>
+ <li id="instance4"><a href="#tab4" data-toggle="tab">Create an instance</a></li>
+</ul>
+
+<hr>
+
+<div class="tab-content">
+ <div class="tab-pane active" id="tab1">
+
+ <h4 id="list">Get a list of all current instances</h4>
+
+ <p>
+ To produce a list of all current instances in the given cloud (belonging to the specified account) use call <strong>GET /api/instances</strong>. The example below displays instances in the Amazon EC2 cloud.
+ </p>
+
+ <p>
+ Example request:
+ </p>
+
+<pre>
+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: */*
+</pre>
+
+ <p>Client response:</p>
+
+<pre>
+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/instances/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_time>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>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab2">
+
+ <h4 id="get-instance">Get the details of an instance</h4>
+
+ <p>
+ To get the details of a specific instance use call <strong>GET /api/instances/:id</strong>. The example below shows an instance launched in the Rackspace Cloudservers cloud. As you can see, the type of authentication is <strong>password</strong> but the username and password attributes are blank. The reason why these attributes are blank is that Rackspace only reports these values once, during instance creation and not for subsequent requests. To find an example of the response from an instance go to the <strong><em>Create an instance</em></strong> section.
+ </p>
+
+ <p>Example request:</p>
+
+<pre>
+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: */*
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+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/instances/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>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab3">
+
+ <h4 id="actions">Launch an action on an instance</h4>
+
+ <p>
+ To launch an action on an instance use call <strong>POST /api/instances/:id/:action</strong>. The valid actions for an instance are specified by the instance states entity. The set of permissible actions that a client may perform on an instance at a given time depends on the current instance state. These are reported by the <code><actions></code> attribute in the Deltacloud server response to the <strong>GET /api/instances/:id</strong> call (<strong><em>Get the details of an instance</em></strong> section). The first example below shows a <strong>reboot</strong> action on a currently running instance, followed by a <strong>stop</strong> action.
+ </p>
+
+ <p>
+ After invoking the stop operation, the instance state may still be reported as <strong>RUNNING</strong> in the Deltacloud server response. It is because it may take some time for the instance state to change in the back-end cloud provider (and this will vary between providers). You can assure yourself that the action was performed correctly by requesting a list of instances or a by requesting a specific instance.
+ </p>
+
+ <p>
+ The Deltacloud server also allows a special 'run-on-instance' action for some cloud provider instances.This enables a client to perform a command on a running instance over <strong>SSH</strong>. The Deltacloud server will return the output of that command to the client. This is reported as the <strong>run</strong> action in the list of instance actions, if it is available. The <strong>cmd</strong> parameter specifies the command, which is executed on a running instance.The <strong>private_key</strong> parameter specifies the authentication for cloud providers that expect key based authentication for connecting to instances . For those cloud providers that use <strong>username/password</strong> for authentication, the <strong>password</strong> parameter specifies the authentication. Examples below illustrate the run-on-instance feature for an Amazon EC2 instance and a Rackspace Cloudservers instance. The examples differ in how authentication is performed (private RSA Key fo
r EC2 and username/password for Rackspace).
+ </p>
+
+ <p>Example request (<strong>reboot</strong>):</p>
+
+<pre>
+POST /api/instances/i-f3ba6492/reboot?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Content-Length: 1322
+
+<?xml version='1.0' encoding='utf-8' ?>
+<instance href='http://localhost:3001/api/instances/i-f3ba6492' id='i-f3ba6492'>
+ <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-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_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>
+</pre>
+
+ <p>Example request (<strong>stop</strong>):</p>
+
+<pre>
+POST /api/instances/20112212/stop?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3002
+Accept: */*
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+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>STOPPED</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/instances/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>
+</pre>
+
+ <p>
+ Example request (<strong>run-on-instance Amazon EC2</strong>):
+ </p>
+
+<div class="alert alert-error">
+ <a class="close" data-dismiss="alert" href="#">Ã</a>
+ <strong>Note:</strong>
+ <p>
+ Run-on-instance requests to EC2 instances will fail with <strong>502 Bad Gateway - Execution Expired</strong> if the firewall in which the instance was launched does not grant SSH access (tcp, port 22) to the requesting client's IP address. This access may be given using the <a href="/firewalls.html">firewalls</a> collection.</p>
+</div>
+
+<pre>
+POST /api/instances/i-afde73ce/run?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Content-Length: 1927
+Content-Type: multipart/form-data; boundary=----------------------------332ed6691ab8
+
+------------------------------332ed6691ab8
+Content-Disposition: form-data; name="cmd"
+
+uname -a; ls -l
+------------------------------332ed6691ab8
+Content-Disposition: form-data; name="private_key"
+
+-----BEGIN RSA PRIVATE KEY-----.BTTEpATBAAKDAQEA4t3R/PgUo3KDDuX4
+vZZpZuXFkAA/5X2lFRY2/xsQqbPz9utPOsUoPf9Aajy+.vGRJrO2KAJ9U/JTNDzr
+3NPbG3aHYPSnwsSxkFSG4Q6ukqYlxT9TPF/+wvdxfAtp3nYw3ZGuSX/DOtToWtQ8
+F/+GvHTHKDQSB+TeEs1Sa/PFwxpspB+RqHbqOTWPsFOHL+9sZGTqd6D4B.R6DBNh
+9Dabu9BVZrl5BTOKlbAgrKnzsGKvaBST/D2.AB/HB9/GOT36OoBmEr1y9gFwu4Xf
+aKw+AXVf9y9TKxVD3TE5uB.oDZG8s4gr2e691xHG9YGzBBBbNzfFh94b3Td5JBGS
+zRDTKYBfOgv+Zu5N+WyeaZ0ab50DwK9BXYB5hsRu5zbAqObbTZkwN9qwBOZHzATX
+wVTZU+eTz.39OZPqu4fQwrBN13lDbUoZxlqT9g2+haQBB9sTDzQEZ08QKBgQDJyw
+lBBZqQKBgQDz5E2rL59lNS5pBxDO9r6B9rXtBBTZ5tZUWNFRvyNsxY5nJT03.KDw
+qo2VP5WDZeOhRWEUY96./pWN3hNFDkT44vDpeXQUh3rBHyD5DWvWxAze9Ds+UTO/
+esuLwP5vXhfoYp6gV9XG.BEBzSVq8kZ2kZtlbWHTR/SGepTkDgYEA9zwHTDhtKR2
+KS8/BSFZQ884ZqFkbwT9fTW6s0rgUSBDTUDgYEA9W5HXTOEPGFDnqBhKPLN.xD9D
+vZZpZuXFkAA/5X2lFRY2/xsQqbPz9utPOsUoPf9Aajy+.vGRJrO2KAJ9U/JTNDzr
+lBBZqQKBgQDz5E2rL59lNS5pBxDO9r6B9rXtBBTZ5tZUWNFRvyNsxY5nJT03.KDw
+F/+GvHTHKDQSB+TeEs1Sa/PFwxpspB+RqHbqOTWPsFOHL+9sZGTqd6D4B.R6DBNh
+wVTZU+eTz.39OZPqu4fQwrBN13lDbUoZxlqT9g2+haQBB9sTDzQEZ08QKBgQDJyw
+lBBZqQKBgQDz5E2rL59lNS5pBxDO9r6B9rXtBBTZ5tZUWNFRvyNsxY5nJT03.KDw
+DAAeVWKU1OyDXfN4v6Zn1nNrhSkdrd+XV0nTLExsfg==.-----END RSA PRIVAT
+E KEY-----
+------------------------------332ed6691ab8--
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Date: Mon, 25 Jul 2011 12:56:02 GMT
+Content-Length: 497
+
+<instance href='http://localhost:3001/api/instances/i-afde73ce' id='i-afde73ce'>
+ <public_address>
+ ec2-50-19-59-126.compute-1.amazonaws.com
+ </public_address>
+ <command>
+ uname -a; ls -l
+ </command>
+ <output>Linux domU-12-31-39-0F-E1-78 2.6.21.7-2.fc8xen #1 SMP Fri Feb 15 12:39:36 EST 2008 i686 i686 i386 GNU/Linux
+ total 140
+ -rw-r--r-- 1 root root 137263 Mar 26 2008 ec2-ami-tools-1.3-19974.noarch.rpm
+ -rw-r--r-- 1 root root 0 Mar 26 2008 firstlogin
+ </output>
+</instance>
+</pre>
+
+ <p>Example request (<strong>run-on-instance Rackspace Cloudservers</strong>):</p>
+
+<pre>
+POST /api/instances/20117112/run?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3002
+Accept: */*
+Content-Length: 275
+Expect: 100-continue
+Content-Type: multipart/form-data; boundary=----------------------------9b05ece66f4d
+------------------------------9b05ece66f4d
+Content-Disposition: form-data; name="cmd"
+
+uname -a; ifconfig; pwd
+------------------------------9b05ece66f4d
+Content-Disposition: form-data; name="password"
+
+myserverqB2Uwk21I
+------------------------------9b05ece66f4d--
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Date: Mon, 25 Jul 2011 13:02:15 GMT
+Content-Length: 1781
+
+<instance href='http://localhost:3002/api/instances/20117112' id='20117112'>
+ <public_address>
+ 50.57.117.249
+ </public_address>
+ <command>
+ uname -a; ifconfig; pwd
+ </command>
+ <output>Linux myserver 2.6.35.4-rscloud #8 SMP Mon Sep 20 15:54:33 UTC 2010 x86_64 x86_64 x86_64 GNU/Linux
+ eth0 Link encap:Ethernet HWaddr 40:40:B1:7A:52:7E
+ inet addr:50.57.117.249 Bcast:50.57.117.255 Mask:255.255.255.0
+ inet6 addr: fe80::4240:b1ff:fe7a:527e/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:54 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:62 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:5880 (5.7 KiB) TX bytes:6331 (6.1 KiB)
+ Interrupt:24
+
+ eth1 Link encap:Ethernet HWaddr 40:40:8E:4B:52:23
+ inet addr:10.182.131.159 Bcast:10.182.159.255 Mask:255.255.224.0
+ inet6 addr: fe80::4240:8eff:fe4b:5223/64 Scope:Link
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:3 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:12 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:188 (188.0 b) TX bytes:720 (720.0 b)
+ Interrupt:25
+
+ lo Link encap:Local Loopback
+ inet addr:127.0.0.1 Mask:255.0.0.0
+ inet6 addr: ::1/128 Scope:Host
+ UP LOOPBACK RUNNING MTU:16436 Metric:1
+ RX packets:0 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:0
+ RX bytes:0 (0.0 b) TX bytes:0 (0.0 b)
+
+ /root</output>
+</instance>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab4">
+
+ <h4 id="post">Create a new instance</h4>
+
+ <p>
+ To create a new instance use call <strong>POST /api/instances</strong>. At least, clients must specify the image from which the virtual machine instance is created. Optionally, a client may also specify a hardware profile and a realm (with default values used otherwise). Clients can also provide a name for the new instance though this is not supported by all back-end cloud providers. You can check whether a given feature is available in the response to the Deltacloud server API entry point. The details of the new instance are returned in response to this operation.
+ </p>
+
+ <p>
+ To create an instance in the Amazon EC2 cloud a client can also specify the name of the used EC2 keypair as well as the firewalls (EC2 security groups) that the instance should be launched into. The EC2 keypair is specified with the parameter keyname while firewalls are specified sequentially as firewalls1 ... firewalls2 ... etc.
+ </p>
+
+ <p>
+ See the example below. The values for public and private addresses are blank in the server response, because they have not yet been assigned by the cloud provider. Subsequent requests for the instance details will provide these values.
+ </p>
+
+ <p>
+ As with other POST operations in the Deltacloud API, clients may specify parameters as multipart/form-data or as x-www-url-form-urlencoded content type, as you can see in examples below.
+ </p>
+
+ <p>Client request (<strong>AWS EC2</strong>):</p>
+
+<pre>
+POST /api/instances?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+Content-Length: 107
+Content-Type: application/x-www-form-urlencoded
+
+keyname=eftah&image_id=ami-f51aff9c&realm_id=us-east-1c&hwp_id=c1.medium&
+firewalls1=default&firewalls2=test
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+HTTP/1.1 201 Created
+Content-Type: application/xml
+Content-Length: 1183
+
+<?xml version='1.0' encoding='utf-8' ?>
+<instance href='http://localhost:3001/api/instances/i-cbb861aa' id='i-cbb861aa'>
+ <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>PENDING</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-cbb861aa/stop' method='post' rel='stop' />
+ <link href='http://localhost:3001/api/instances/i-cbb861aa/run;id=i-cbb861aa' method='post' rel='run' />
+ </actions>
+ <launch_time>2011-07-22T16:09:45.000Z</launch_time>
+ <public_addresses></public_addresses>
+ <private_addresses></private_addresses>
+ <firewalls>
+ <firewall href='http://localhost:3001/api/firewalls/test' id='test'></firewall>
+ <firewall href='http://localhost:3001/api/firewalls/default' id='default'></firewall>
+ </firewalls>
+ <authentication type='key'>
+ <login>
+ <keyname>eftah</keyname>
+ </login>
+ </authentication>
+</instance>
+</pre>
+
+ <p>
+ In the following example you can see that the client provides the optional name parameter and that the created instance uses <strong>password</strong> type of authentication. Furthermore, the client uses a content-type of application/x-www-form-urlencoded. The username and password are returned with the details of the new instance:
+ </p>
+
+ <p>Example request: (<strong>Rackspace Cloudservers</strong>)</p>
+
+<pre>
+POST /api/instances?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3002
+Accept: */*
+Content-Length: 34
+Content-Type: application/x-www-form-urlencoded
+
+image_id=53&hwp_id=1&name=myserver
+</pre>
+
+ <p>Server response:</p>
+
+<pre>
+HTTP/1.1 201 Created
+Content-Type: application/xml
+Content-Length: 883
+
+<?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>PENDING</state>
+ <hardware_profile href='http://localhost:3002/api/hardware_profiles/1' id='1'>
+ </hardware_profile>
+ <actions>
+ <link href='http://localhost:3002/api/instances/20112212/run;id=20112212' method='post' rel='run' />
+ </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>myserver4OvKh7Ak3</password>
+ </login>
+ </authentication>
+</instance>
+</pre>
+
+<div class="alert alert-error">
+ <a class="close" data-dismiss="alert" href="#">Ã</a>
+ <h4 class="alert-heading">Note:</h4>
+ <p>
+ The Deltacloud does not report potential errors, if you are creating an instance in <strong>vSphere</strong>. When you launch an instance, Deltacloud does not wait until the task is finished. Instead of that, Deltacloud creates a YAML representation of the instance in vSphere datastore. The YAML instance is in a 'PENDING' state until the 'real' instance is created. If the real instance fails to create, the YAML representation is removed. However, Deltacloud does not send you any error message.
+ </p>
+</div>
+
+ </div>
+</div>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/keys.html">Keys <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a>
+
+<br/>
+
+
Added: deltacloud/trunk/site/content/join-deltacloud.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/join-deltacloud.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/join-deltacloud.md (added)
+++ deltacloud/trunk/site/content/join-deltacloud.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1 @@
+
Added: deltacloud/trunk/site/content/keys.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/keys.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/keys.md (added)
+++ deltacloud/trunk/site/content/keys.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,259 @@
+---
+site_name: Deltacloud API
+title: Keys
+---
+
+<br/>
+
+<div class="row">
+ <div class="span9">
+
+<h3 id="keys">Keys</h3>
+
+<p>
+A key captures the credentials required to access an Instance. The Deltacloud API supports two main types of keys:
+</p>
+
+<ul>
+ <li>the <strong>password</strong> with username and password attributes</li>
+ <li>the <strong>key</strong> with fingerprint and pem (private key) attributes (public/private keypair)</li>
+</ul>
+
+<p>
+The key type is determined by the back-end cloud provider.
+</p>
+
+<p>
+Some cloud providers require the specification of the credentials used for connecting to an instance as a parameter for instance creation. For example, the Amazon EC2 cloud uses <strong>key</strong> type of keys; the identifier of the key used with a given instance is supplied within the keyname parameter to the <strong>POST /api/instances</strong> call (see the <a href="/instances.html#instance">Create an instance</a> section).
+</p>
+
+<p>
+Other cloud providers report the instance credentials in response to instance creation and make them available for subsequent retrieval. For example, the Gogrid Cloud uses the <strong>password</strong> type of keys.
+</p>
+
+<p>
+The Rackspace cloud also reports credentials during instance creation though it does not provide a mechanism with which to retrieve those passwords thereafter).
+</p>
+
+ </div>
+ <div class="span3">
+
+<ul class="nav nav-list well">
+ <li class="nav-header">
+ REST API
+ </li>
+ <li><a href="/rest-api.html">Introduction</a></li>
+ <li><a href="/api-entry-point.html">API entry point</a></li>
+ <li><a href="/compute-resources.html">Compute resources</a></li>
+ <ul class="nav nav-list">
+ <li><a href="/compute-resources.html">Realms</a></li>
+ <li><a href="/hardware-profiles.html">Hardware profiles</a></li>
+ <li><a href="/images.html">Images</a></li>
+ <li><a href="/instance-states.html">Instance states</a></li>
+ <li><a href="/instances.html">Instances</a></li>
+ <li class="active"><a href="#keys">Keys</a></li>
+ <li><a href="/firewalls.html">Firewalls</a></li>
+ <li><a href="/addresses.html">Addresses</a></li>
+ <li><a href="/load-balancers.html">Load balancers</a></li>
+ </ul>
+ <li><a href="/storage-resources.html">Storage resources</a></li>
+</ul>
+
+ </div>
+</div>
+
+<ul class="nav nav-pills">
+ <li class="active"><a href="#tab1" data-toggle="tab">Get a list of all keys</a></li>
+ <li><a href="#tab2" data-toggle="tab">Get the description of a key</a></li>
+ <li><a href="#tab3" data-toggle="tab">Create/delete a key</a></li>
+</ul>
+
+<hr>
+
+<div class="tab-content">
+ <div class="tab-pane active" id="tab1">
+
+<h4 id="get">Get a list of all keys</h4>
+
+<p>
+To get a list of all available keys use call <strong>GET /api/keys</strong>. The example below shows keys from the Amazon EC2 cloud (<strong>key</strong> type). The XML response does not contain the private key attribute. It is because EC2 only provides the private key once, when the key is created (see the <strong><em>Create/delete a key
+</em></strong> section).
+</p>
+
+<p>Example request:</p>
+
+<pre>
+GET /api/keys?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Date: Tue, 26 Jul 2011 08:09:26 GMT
+Content-Length: 733
+
+<?xml version='1.0' encoding='utf-8' ?>
+<keys>
+ <key href='http://localhost:3001/api/keys/deltacloud_jsmith' id='deltacloud_jsmith' type='key'>
+ <actions>
+ <link href='http://localhost:3001/api/keys/deltacloud_jsmith' method='delete' rel='destroy' />
+ </actions>
+ <fingerprint>38:93:81:11:83:c2:c7:27:e8:79:17:e2:08:c9:13:99:73:90:8e:cc</fingerprint>
+ <state>AVAILABLE</state>
+ </key>
+ <key href='http://localhost:3001/api/keys/the_key' id='the_key' type='key'>
+ <actions>
+ <link href='http://localhost:3001/api/keys/the_key' method='delete' rel='destroy' />
+ </actions>
+ <fingerprint>39:d3:9b:bb:93:92:97:27:e9:7d:b7:e2:09:9d:b3:dd:73:d0:9e:99</fingerprint>
+ <state>AVAILABLE</state>
+ </key>
+</keys>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab2">
+
+<h4>Get the description of a key</h4>
+
+<p>
+To get the XML description for a specific key use call <strong>GET /api/keys/:id</strong>. The example below shows a <strong>password</strong> type of key from the Gogrid cloud:
+</p>
+
+<p>Example request:</p>
+
+<pre>
+GET /api/keys/72398?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.21.2 (x86_64-apple-darwin10.3.1)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Date: Tue, 26 Jul 2011 11:13:25 GMT
+Content-Length: 269
+
+<?xml version='1.0' encoding='utf-8' ?>
+<key href='http://localhost:3001/api/keys/72398' id='72398' type='password'>
+ <actions>
+ </actions>
+ <username><![CDATA[26648]]></username>
+ <password><![CDATA[3woc7UWdJsJEcm8@]]></password>
+ <state></state>
+</key>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab3">
+
+<h4 id="create">Create a new key</h4>
+
+<p>
+To create a new key use call <strong>POST /api/keys</strong>. Some back-end cloud providers allow a client to create new credentials for accessing instances. The parameters (key attributes) required by this function will depend on the back-end cloud provider and are specified in the relevant driver. At present, only the Amazon EC2 cloud implements a key creation method. The method requires to specify the key name as a parameter.
+</p>
+
+<p>
+Note that the private key attribute of a newly created key is reported only once, in response to the create operation (see the example below). The client should save the private key for following use with instance authentication. In all subsequent calls, the Deltacloud server response displays only the fingerprint attribute, as illustrated in the <em><strong>Get a list of all keys</strong></em> section.
+</p>
+
+<p>
+As with other HTTP POST calls in the Deltacloud REST API, client requests may specify the required parameters as multipart/form-data, or using the application/x-www-form-urlencoded content type.
+</p>
+
+<p>Example request:</p>
+
+<pre>
+POST /api/keys?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+Content-Length: 19
+Content-Type: application/x-www-form-urlencoded
+
+name=jsmith_new_key
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 201 Created
+Content-Type: application/xml
+Date: Tue, 26 Jul 2011 10:58:58 GMT
+Content-Length: 2062
+
+<?xml version='1.0' encoding='utf-8' ?>
+<key href='http://localhost:3001/api/keys/jsmith_new_key' id='jsmith_new_key' type='key'>
+ <actions>
+ <link href='http://localhost:3001/api/keys/jsmith_new_key' method='delete' rel='destroy' />
+ </actions>
+ <fingerprint>c6:80:5c:0a:b8:66:0d:58:5a:bf:0f:c2:5d:35:d3:c7:49:f3:5a:5f</fingerprint>
+ <pem>
+ <![CDATA[-----BEGIN RSA PRIVATE KEY-----
+ MIIEpgIBAAKCAQEAsPIzLQEpoLkxd0WESPEWQ4AMn9e0T6jHIMl/a2GUx2TA2Q10n6i5h4VAXXrK
+ m9fNnPJhw1uRbuL7Oz57QSftGUfz05EaLOsvIEq3OXA0HqnFPF7Dd4yvy07KfgNHe2c26NqIqxgw
+ GCy6tfd/9iKQIlFCG8I/M6fgEG/vw30GP5EywYLS0J7lYfNHJAVAznjX0LoOWvT0zYajZ7gWJ30/
+ sQ/IFaKxC3BpT6K2aQP+RgAimALHinFuoT4+07SsrQXEezLemAG/gdbw3+7DL9BGq0CCoY1RxeC7
+ qNh9BJwHtq9QPYg/RKruiYak/TSoB71/VP67lJv0WEkCRJKEFpz5SQIDAQABAoIBAQChVyZcmdvI
+ JjS5aVSWYeWIBMD+GmPZ4q428iPR2LcdHHxPLVqyndkVfeXTlrwZX6umuMd1pw+zyRmEypL+NRaW
+ 36mutnbkkEl3K0loASw07V3fjxSx9EDyo1Q1lG3gUpuZtHG7eCGaWWahtxwhZSCBehBKWVLhmefP
+ dRFs8Zn56LhfxByS/HcmHYddq1ggynFgg1DszYKTiJ0k5Zd/w4gh3GXH02S50cNFumJh9tbZNeDz
+ yqa6a12N21loZ/VRRL7lEjpf3K2n0DCQ5pp0I9/FiwuwHMWr6qPSsQt9N/XclNiVg7fz+btNsqVY
+ US1kBkvazoaANmF3VOXT9bmiFnuBAoGBAOkURD2uBe9UUl7xvWON7yS+tBcs1KyYDsTEhsS5dLdk
+ n73/5vyEVzozdywTR7lQWVQhWWwkK/FJd9Xo/VV5bGXl+MK/JxIQHrEhLzO1OeYEBiw2eKhigyDb
+ lm7pk/DuBNqgnA9YVnSvRYjpnvgBeb89CHvdhqn52GcbB2ShXurRAoGBAMJYyqNyl8CiIqesigts
+ tlRk0UmS/LS6I58f7nbcrkgO3ZDsYhXhj9aKSJx56bpWTwoFdl7nTSUwkFgq2ts3g7EPQbYD/5G6
+ kwpq0tvC23zZTfYvjExNVORh9PJBCrBl1tC/5nqYSrHC7H3Ys/SW3DF+0LPTdOtx5FwL5Utr3lT5
+ AoGBAM3Y8EvpHaS5O+ZOaY07FTHGmxa8qTelM6XkS4ICqGovnEUZdM8fskncmit6+6VWqQ38RhWT
+ /Jsk34k0NEkA7BMyf/i/CaqSQgj93co1C+VxOGJj2TwdhOHIDZv2/omSLQdJQYrr4a87/JVmftdZ
+ tkSHiq6afwwvdEfbPzRIsKOBAoGBAK5EjEAP6z+So1yS/J3N95ipZnmA0hUErBhtu5jdvXFj0w22
+ ySUxw5bvHLkjIJA0AF/OEhx7b9OfPm+wzdqwZugH9DZQU4TLNjqrGzRv//xtptjQPg/Vb//yToBE
+ Dl+qkftReEwJ70CCtykJfiQeeofvXRlCzZ6p28kl6Y+9w/mRAoGBANI8AGB1iUDMQDiEfTAuH7jB
+ nZTZUsfAaysoku3gyVmtcu1Zo7T02b8YW3ypuNu664KO7eNik9q68yKa7oDuLVrVj6Sh2DInoeW9
+ vbjp2KcyMVEPHzWh86LV9IY5oHjQxlK/PMhQWMEeysi6j2qFqrx2rqRhG6kZUcFHFoHQpmv2
+ -----END RSA PRIVATE KEY-----]]>
+ </pem>
+ <state>AVAILABLE</state>
+</key>
+</pre>
+
+<h4>Delete a key</h4>
+
+<p>
+To delete a key, specified by its <strong>:id</strong> attribute, use call <strong>DELETE /api/keys/:id</strong>. As well as the create operation, this feature is currently only available in the Amazon EC2 driver.
+</p>
+
+<p>Example request:</p>
+
+<pre>
+DELETE /api/keys/jsmith_new_key?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 204 No Content
+Date: Tue, 26 Jul 2011 10:18:38 GMT
+</pre>
+
+ </div>
+</div>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/firewalls.html">Firewalls <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a>
+
+<br/>
Added: deltacloud/trunk/site/content/libdeltacloud.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/libdeltacloud.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/libdeltacloud.md (added)
+++ deltacloud/trunk/site/content/libdeltacloud.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,4 @@
+---
+site_name: Deltacloud API
+title: Libdeltacloud
+---
Added: deltacloud/trunk/site/content/load-balancers.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/load-balancers.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/load-balancers.md (added)
+++ deltacloud/trunk/site/content/load-balancers.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,333 @@
+---
+site_name: Deltacloud API
+title: Load balancers
+---
+
+<br/>
+
+<div class="row">
+ <div class="span9">
+
+<h3 id="load">Load balancers</h3>
+
+<p>
+Load balancers allow distribution of ingress network traffic received by a specified IP address to a number of running instances. For example, a number of instances that are fulfilling the role of web servers can be attached to a single load balancer. It allows you to handle a large number of requests without influence on website performance.
+</p>
+
+<p>
+This collection is not supported by all back-end cloud providers and at present, it is implemented for the Gogrid and Amazon EC2 cloud drivers. A load balancer is launched into a specific realm. Only instances within this specific realm may be attached to the balancer. Each load balancer has
+</p>
+
+<ul>
+ <li>a <strong>list of instances</strong>;</li>
+ <li>a <strong>public address</strong> representing the IP address that the balancer will respond on to client requests;</li>
+ <li>a <strong>created_at</strong> timestamp; and</li>
+ <li>a list of <strong>listeners</strong>.</li>
+</ul>
+
+<p>
+Each <strong>listener</strong> has a <strong>protocol</strong> (e.g. TCP), a <strong>load balancer port</strong> and an <strong>instance port</strong>. The load balancer represents the port on which the balancer accepts connections. The instance port represents the port on which network traffic is forwarded to instances in the <strong>instance list</strong>.
+</p>
+
+ </div>
+ <div class="span3">
+
+<ul class="nav nav-list well">
+ <li class="nav-header">
+ REST API
+ </li>
+ <li><a href="/rest-api.html">Introduction</a></li>
+ <li><a href="/api-entry-point.html">API entry point</a></li>
+ <li><a href="/compute-resources.html">Compute resources</a></li>
+ <ul class="nav nav-list">
+ <li><a href="/realms.html">Realms</a></li>
+ <li><a href="/hardware-profiles.html">Hardware profiles</a></li>
+ <li><a href="/images.html">Images</a></li>
+ <li><a href="/instance-states.html">Instance states</a></li>
+ <li><a href="/instances.html">Instances</a></li>
+ <li><a href="/keys.html">Keys</a></li>
+ <li><a href="/firewalls.html">Firewalls</a></li>
+ <li><a href="/addresses.html">Addresses</a></li>
+ <li class="active"><a href="#load">Load balancers</a></li>
+ </ul>
+ <li><a href="/storage-resources.html">Storage resources</a></li>
+</ul>
+
+ </div>
+</div>
+
+<br/>
+
+<ul class="nav nav-pills">
+ <li class="active"><a href="#tab1" data-toggle="tab">Get the details of all load balancers</a></li>
+ <li><a href="#tab2" data-toggle="tab">Get the details for a load balancer</a></li>
+ <li><a href="#tab3" data-toggle="tab">Create/delete a load balancer</a></li>
+ <li><a href="#tab4" data-toggle="tab">Register/unregister an instance</a></li>
+</ul>
+
+<hr>
+
+<div class="tab-content">
+ <div class="tab-pane active" id="tab1">
+
+
+<h4>Get the details of all load balancers</h4>
+
+<p>
+To retrieve details of all load balancers use call <strong>GET /api/load_balancers</strong>.
+</p>
+
+<p>
+Example request:
+</p>
+
+<pre>
+GET /api/load_balancers?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Date: Thu, 28 Jul 2011 13:37:19 GMT
+Content-Length: 1844
+
+<?xml version='1.0' encoding='utf-8' ?>
+<load_balancers>
+ <load_balancer href='http://localhost:3001/api/load_balancers/webtraffic-balancer' id='webtraffic-balancer'>
+ <actions>
+ <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer' method='delete' rel='destroy' />
+ <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer/register' method='post' rel='register' />
+ </actions>
+ <public_addresses>
+ <address>webtraffic-balancer-1306196965.us-east-1.elb.amazonaws.com</address>
+ </public_addresses>
+ <created_at>Thu Jul 28 13:29:52 UTC 2011</created_at>
+ <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm>
+ <listeners>
+ <listener protocol='HTTP'>
+ <load_balancer_port>80</load_balancer_port>
+ <instance_port>3001</instance_port>
+ </listener>
+ </listeners>
+ <instances>
+ </instances>
+ </load_balancer>
+ <load_balancer href='http://localhost:3001/api/load_balancers/secure-site-balancer' id='secure-site-balancer'>
+ <actions>
+ <link href='http://localhost:3001/api/load_balancers/secure-site-balancer' method='delete' rel='destroy' />
+ <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/register' method='post' rel='register' />
+ </actions>
+ <public_addresses>
+ <address>secure-site-balancer-1347100846.us-east-1.elb.amazonaws.com</address>
+ </public_addresses>
+ <created_at>Thu Jul 28 13:36:29 UTC 2011</created_at>
+ <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm>
+ <listeners>
+ <listener protocol='HTTP'>
+ <load_balancer_port>443</load_balancer_port>
+ <instance_port>443</instance_port>
+ </listener>
+ </listeners>
+ <instances>
+ </instances>
+ </load_balancer>
+</load_balancers>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab2">
+
+<h4>Get the details for a load balancer</h4>
+
+<p>To retrieve details for a specific load balancer use call <strong>GET /api/load_balancers/:id</strong>.</p>
+
+<p>Example request:</p>
+
+<pre>
+GET /api/load_balancers/secure-site-balancer?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 200 OK
+Content-Type: application/xml
+Date: Thu, 28 Jul 2011 18:11:49 GMT
+Content-Length: 1361
+
+<?xml version='1.0' encoding='utf-8' ?>
+<load_balancer href='http://localhost:3001/api/load_balancers/secure-site-balancer' id='secure-site-balancer'>
+ <actions>
+ <link href='http://localhost:3001/api/load_balancers/secure-site-balancer' method='delete' rel='destroy' />
+ <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/register' method='post' rel='register' />
+ </actions>
+ <public_addresses>
+ <address>secure-site-balancer-1347100846.us-east-1.elb.amazonaws.com</address>
+ </public_addresses>
+ <created_at>Thu Jul 28 13:36:29 UTC 2011</created_at>
+ <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm>
+ <listeners>
+ <listener protocol='HTTP'>
+ <load_balancer_port>443</load_balancer_port>
+ <instance_port>443</instance_port>
+ </listener>
+ </listeners>
+ <instances>
+ <instance href='http://localhost:3001/api/instances/i-4f06b52e' id='i-4f06b52e'>
+ <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/unregister?instance_id=i-4f06b52e' rel='unregister' />
+ </instance>
+ <instance href='http://localhost:3001/api/instances/i-d706b5b6' id='i-d706b5b6'>
+ <link href='http://localhost:3001/api/load_balancers/secure-site-balancer/unregister?instance_id=i-d706b5b6' rel='unregister' />
+ </instance>
+ </instances>
+</load_balancer>
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab3">
+
+<h4>Create a load balancer</h4>
+
+<p>
+To create a new load balancer use call <strong>POST /api/load_balancers</strong>. Clients must provide the load balancer <strong>name</strong>, the <strong>realm_id</strong> to which the balancer is applied, a <strong>listener_protocol</strong> which the balancer will respond to (one of <strong>HTTP</strong> or <strong>TCP</strong>), the <strong>listener_balancer_port</strong> which specifies the port that the load balancer will be expecting network traffic on and finally the <strong>listener_instance_port</strong> which specifies the port on which instances will be receiving network traffic forwarded by the load balancer. As with other operations in the Deltacloud API, parameters may be specified by a requesting client using multipart/form-data or as application/x-www-form-urlencoded data.
+</p>
+
+<p>Example request:</p>
+
+<pre>
+OST /api/load_balancers?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+Content-Length: 121
+Content-Type: application/x-www-form-urlencoded
+
+name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP&
+listener_balancer_port=80&listener_instance_port=3001
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 201 Created
+Content-Type: application/xml
+Date: Thu, 28 Jul 2011 13:30:05 GMT
+Content-Length: 884
+
+<?xml version='1.0' encoding='utf-8' ?>
+<load_balancer href='http://localhost:3001/api/load_balancers/webtraffic-balancer' id='webtraffic-balancer'>
+ <actions>
+ <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer' method='delete' rel='destroy' />
+ <link href='http://localhost:3001/api/load_balancers/webtraffic-balancer/register' method='post' rel='register' />
+ </actions>
+ <public_addresses>
+ <address>webtraffic-balancer-1306196965.us-east-1.elb.amazonaws.com</address>
+ </public_addresses>
+ <created_at>Thu Jul 28 13:29:52 UTC 2011</created_at>
+ <realm href='http://localhost:3001/api/realms/us-east-1a' id='us-east-1a'></realm>
+ <listeners>
+ <listener protocol='HTTP'>
+ <load_balancer_port>80</load_balancer_port>
+ <instance_port>3001</instance_port>
+ </listener>
+ </listeners>
+ <instances>
+ </instances>
+</load_balancer>
+</pre>
+
+<h4>Delete a load balancer</h4>
+
+<p>To delete the specified load balancer from the back-end cloud provider use call <strong>DELETE /api/load_balancers/:id</strong>. The Deltacloud server will respond with <strong>HTTP 204 No Content</strong> for a succesful operation</p>
+
+<p>Example request:</p>
+
+<pre>
+DELETE /api/load_balancers/webtraffic-balancer?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 204 No Content
+Date: Thu, 28 Jul 2011 13:23:33 GMT
+</pre>
+
+ </div>
+ <div class="tab-pane" id="tab4">
+
+<h4>Register an instance with a load balancer</h4>
+
+<p>
+To register a running instance with a specified load balancer use call <strong>POST /api/load_balancers/:id/register</strong>. Clients must provide the <strong>instance_id</strong> as a parameter to the request. The Deltacloud server will respond with a <strong>HTTP 204 No Content</strong> after a succesful operation. The Deltacloud server will accept client request parameters encoded as multipart/form-data or as application/x-www-form-urlencoded data.
+</p>
+
+<p>Example request:</p>
+
+<pre>
+POST /api/load_balancers/secure-site-balancer/register?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+Content-Length: 22
+Content-Type: application/x-www-form-urlencoded
+
+instance_id=i-4f06b52e
+</pre>
+
+Server response:
+
+<pre>
+HTTP/1.1 204 No Content
+Date: Thu, 28 Jul 2011 18:20:03 GMT
+</pre>
+
+<h4>Unreagister an instance from a load balancer</h4>
+
+<p>
+To unregister a specified instance from the given load balancer use call <strong>POST /api/load_balancers/:id/unregister</strong>. The client must supply the <strong>instance_id</strong> parameter to identify the instance, either as multipart/form-data or as application/x-www-form-urlencoded data.
+</p>
+
+<p>Example request:</p>
+
+<pre>
+POST /api/load_balancers/secure-site-balancer/unregister?format=xml HTTP/1.1
+Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
+User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
+Host: localhost:3001
+Accept: */*
+Content-Length: 22
+Content-Type: application/x-www-form-urlencoded
+
+instance_id=i-4f06b52e
+</pre>
+
+<p>Server response:</p>
+
+<pre>
+HTTP/1.1 204 No Content
+Date: Thu, 28 Jul 2011 19:09:17 GMT
+</pre>
+
+ </div>
+</div>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/storage-resources.html">Storage resources <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a>
+
+<br/>
Added: deltacloud/trunk/site/content/rest-api.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/rest-api.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/rest-api.md (added)
+++ deltacloud/trunk/site/content/rest-api.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,184 @@
+---
+site_name: Deltacloud API
+title: REST API
+---
+
+<br/>
+
+<div class="row">
+ <div class="span9">
+
+<h3 id="rest">REST API</h3>
+
+<p>
+Apache Deltacloud is a REST-based (HATEOAS) cloud abstraction API. It enables management of resources in different IaaS clouds using a single API. There are back-end drivers communicating with each cloud provider's native API and the Deltacloud Core Framework provides the basis for implementing drivers to new IaaS clouds. Apache Deltacloud currently supports many back-end <a href="/drivers.html#drivers">cloud providers</a>.
+</p>
+
+<p>
+With Deltacloud project, you don't have to limit yourself to a single cloud provider. Instead of taking care of a number of clouds, you are dealing with just one API abstraction.
+</p>
+
+<h3 id="collections">Collections</h3>
+
+<p style="margin-bottom:0px">
+The following terms describe abstractions used in the Apache Deltacloud API. Each collection represents an entity in the back-end provider cloud, such as a running virtual server or a server image. Please note that the list of supported collections may differ from cloud to cloud. Only the appropriate collections are exposed for a given back-end driver (e.g. the Microsoft Azure driver currently exposes only the Buckets collection).
+</p>
+
+ </div>
+ <div class="span3">
+
+<ul class="nav nav-list well">
+ <li class="nav-header">
+ REST API
+ </li>
+ <li class="active"><a href="#rest">Introduction</a></li>
+ <ul class="nav nav-list">
+ <li><a href="#collections">Collections</a></li>
+ <li><a href="#requests">Client requests</a></li>
+ <li><a href="#auth">Authentication</a></li>
+ <li><a href="#response">Server responses</a></li>
+ <li><a href="#conv">API conventions</a></li>
+ <li><a href="#stab">API stability</a></li>
+ <li><a href="#doc">Online documentation</a></li>
+ </ul>
+ <li><a href="/api-entry-point.html">API entry point</a></li>
+ <li><a href="/compute-resources.html">Compute resources</a></li>
+ <li><a href="/storage-resources.html">Storage resources</a></li>
+</ul>
+
+ </div>
+</div>
+
+<dl class="dl dl-horizontal">
+<dt><h4>Realms</h4></dt>
+ <dd>
+ A distinct organizational unit within the back-end cloud, for exapmle a datacenter. A realm may but does not necessarily represent the geographical location of the compute resources which you access.
+ </dd>
+ <dt><h4>Instances</h4></dt>
+ <dd>
+ A realized virtual server, running in a given back-end cloud. Instances are instantiated from server images.
+ </dd>
+ <dt><h4>Images</h4></dt>
+ <dd>
+ Templates (virtual machine images) from which instances are created. Each image defines the root partition and initial storage for the instance operating system.
+ <dt><h4>Instance states</h4></dt>
+ <dd>
+ Instance states represent the instance lifecycle. at any time an instance is in one of states: start, pending, running, stopped, shutting_down, finished.
+ </dd>
+ <dt><h4>Keys</h4></dt>
+ <dd>
+ Keys represent credentials used to access a running instance. Keys can take the form of key (for example an RSA key) or of password (with username and password attributes).
+ </dd>
+ <dt><h4>Storage volume</h4></dt>
+ <dd>
+ A virtual storage device that can be attached to an instance and mounted by the OS.
+ </dd>
+ <dt><h4>Storage snapshot</h4></dt>
+ <dd>
+ Storage snapshots are copies, snapshots of a storage volume at a specified time.
+ </dd>
+ <dt><h4>Bucket</h4></dt>
+ <dd>
+ A container for data blobs. The organizational unit of a generic key ==> value based on data store (such as Rackspace CloudFiles or Amazon S3). Individual data items, blobs, are exposed as a subcollection under a bucket.
+ </dd>
+ <dt><h4>Blob</h4></dt>
+ <dd>
+ A generic binary data item that exists within a specified bucket (an object in Amazon S3 and Rackspace CloudFiles).
+ </dd>
+ <dt><h4>Address</h4></dt>
+ <dd>
+ Address represents an IP address. Depending on the back-end cloud provider, address can be public or private. Public address represents a unique, globally routable IP address, private address represents an address routable only within a private network.
+ </dd>
+ <dt><h4>Load Balancer</h4></dt>
+ <dd>
+ A load balancer allows a distribution of ingress network traffic received by a specified IP address to a number of instances.
+ </dd>
+ <dt><h4>Firewalls</h4></dt>
+ <dd>Sets of rules that govern the accessibility of a running instance over the public Internet.
+ </dd>
+ <dt><h4>Metrics</h4></dt>
+ <dd>
+ Metrics collection provides useful information about your cloud resources, e.g. CPU utilization or network throughput. It may be helpful for developers for better scaling and monitoring. The collection is currently supported only for Amazon EC2 cloud. It collects information from Amazon CloudWatch service.
+ </dd>
+</dl>
+
+<h3 id="requests">Client Requests</h3>
+
+<p>
+In accordance with REST principles, clients make requests through HTTP with the usual meanings assigned to the standard HTTP verbs GET, POST, PUT, and DELETE.
+</p>
+
+<p>
+Besides 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">Cloud APIs Rest Style Guide</a>.
+</p>
+
+<p>
+The URL space of the API is structured into collections of resources. The top level entities used in the Deltacloud API are: realms, images, instance states, instances, keys, storage volumes, storage snapshots, blob storage, hardware profiles and drivers.
+</p>
+
+<h3 id="auth">Authentication</h3>
+
+<p>
+The Deltacloud API server is stateless and does not keep any information about the current client. The Deltalcloud server does not store the credentials for the back-end cloud which the server is talking to. Instead, the server uses HTTP basic authentication and clients have to send the username/password for the back-end cloud on every request.
+</p>
+
+<p>
+The specifics of what needs to be sent varies from cloud to cloud; some cloud providers request a username and password for API access, the others use special-purpose API keys. Check the list of the <a href="/drivers.html#credentials">credentials</a> to find out what kind of information a specific cloud provider expects.
+</p>
+
+<h3 id="response">Server responses</h3>
+
+<p>
+The server can respond to client requests in various formats. The appropriate response format is determined by HTTP content negotiation. The primary format is XML. The output is also available as JSON and as HTML (mostly for testing). Clients can also explicitly request a specific response format by including the <strong>format=</strong> request parameter (<strong>http://deltacloudserver.foo/api?format=xml</strong> or <strong>http://deltacloudserver.foo/api?format=json</strong>).
+</p>
+
+<p>
+In general (especially for the HTML interface), list operations such as <strong>GET /api/realms</strong> will provide a list of objects of this resource type with only brief details. Full details can be retrieved by making a request <strong>GET /api/realms/:id</strong> to the URL of the individual realm.
+</p>
+
+<h3 id="conv">API conventions</h3>
+
+<p>
+Any XML element which represents an object (such as an instance) has a <strong>href</strong> and an <strong>id</strong> attribute. The href attribute provides the URL at which object-specific actions can be performed (for example a GET action applied to the URL will return details of the object). The id provides an identifier of the object, which is unique within its collection (there is a unique id for each Instance, Image, Realm etc).
+</p>
+
+<p>
+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>
+
+<h3 id="stab">API stability and evolution</h3>
+
+<p>
+Every change to the API is made in a way that allows old clients to work against newer versions of the API server.
+</p>
+
+<p>
+You may come across the following changes in newer versions of the API:
+</p>
+
+<ul>
+ <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>
+On the other hand, these changes would violate API stability and therefore they are not made:
+</p>
+
+<ul>
+ <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>
+
+<h3 id="doc">Online documentation</h3>
+
+<p>
+You can access an automatically generated documentation on every server running the Deltacloud Core API service through the URL <a href="http://localhost:3001/api/docs/">http://localhost:3001/api/docs/</a>. 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>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/api-entry-point.html">API entry point <i class="icon-arrow-right icon-white" style="vertical-align:baseline"> </i></a>
+
+<br/>
+
Added: deltacloud/trunk/site/content/ruby-client.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/ruby-client.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/ruby-client.md (added)
+++ deltacloud/trunk/site/content/ruby-client.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,128 @@
+---
+site_name: Deltacloud API
+title: The Deltacloud Ruby Client
+---
+<br/>
+
+<div class="row">
+ <div class="span8">
+
+<h3>Working with Deltacloud Ruby Client</h3>
+<p>Each type of a resource has an associated model. Where resource refers to other resources, natural navigation across the object model is possible. For example:</p>
+
+<pre>
+puts instance.image.name
+puts instance.hardware_profile.architecture
+</pre>
+
+<h4 id="realms">Listing realms</h4>
+<p>Retrieve a complete list of realms available to you:</p>
+
+<pre>realm = client.realms</pre>
+
+</div>
+ <div class="span4">
+
+<ul class="nav nav-list well">
+ <li class="nav-header">Deltacloud Ruby Client</li>
+ <li class="active"><a href="#realms">Listing realms</a></li>
+ <li><a href="#profiles">Listing hardware profiles</a></li>
+ <li><a href="#images">Listing images</a></li>
+ <li><a href="#instances1">Listing instances</a></li>
+ <li><a href="#instances2">Lauching instances</a></li>
+ <li><a href="#instances3">Manipulating instances</a></li>
+ <li><a href="http://deltacloud.apache.org/ruby-client/doc/index.html">Client documentation</a></li>
+</ul>
+
+ </div>
+</div>
+
+<p>You can access a specific realm by adding its identifier:</p>
+
+<pre>realm = client.realm( 'us' )</pre>
+
+<h4 id="profiles">Listing hardware profiles</h4>
+
+<p>Display a complete list of hardware profiles available for launching machines:</p>
+
+<pre>hwp = client.hardware_profiles</pre>
+
+<p>You can filter hardware profiles by architecture.</p>
+
+<pre>hardware_profiles = client.hardware_profiles( :architecture=>'x86_64' )</pre>
+
+<p>Retrieve a specific hardware profile by its identifier:</p>
+
+<pre>hardware_profile = client.hardware_profile( 'm1-small' )</pre>
+
+<h4 id="images">Listing images</h4>
+
+<p>Return a complete list of images:</p>
+
+<pre>images = client.images</pre>
+
+<p>Retrieve a list of images owned by the currently authenticated user:</p>
+
+<pre>images = client.images( :owner_id=>:self )</pre>
+
+<p>You can also retrieve a list of images visible to you but owned by a specific user:</p>
+
+<pre>images = client.images( :owner_id=>'daryll' )</pre>
+
+<p>Access a specific image by its identifier:</p>
+
+<pre>image = client.image( 'ami-8675309' )</pre>
+
+<h4 id="instances1">Listing instances</h4>
+
+<p>Get a list of all instances visible to you:</p>
+
+<pre>instances = client.instances</pre>
+
+<p>Retrieve a list of all running instances:</p>
+
+<pre>instances = client.instances( :state =>:running )</pre>
+
+<p>Look up the first instance in the list:</p>
+
+<pre>instance = client.instances.first</pre>
+
+<p>Find a specific instance by its identifier:</p>
+
+<pre>instance = client.instance( 'i-90125' )</pre>
+
+<h4 id="instances2">Launching instances</h4>
+
+<p>Launch an instance using an image identifier:</p>
+
+<pre>instance = client.create_instance(image_id)</pre>
+
+<p>You may specify a hardware profile:</p>
+
+<pre>instance = client.create_instance(image_id, :hwp_id => 'm1-small')</pre>
+
+<p>To create new instance, you can also use the 'user_name' feature:</p>
+
+<pre>instance = client.create_instance(image_id, :name => 'myinst1')</pre>
+
+<h4 id="instances3">Manipulating instances</h4>
+
+<p>Start an instance:</p>
+
+<pre>instance.start!</pre>
+
+<p>Execute the 'reboot' operation:</p>
+
+<pre>instance.reboot!</pre>
+
+<p>Destroy an instance:</p>
+
+<pre>instance.destroy!</pre>
+
+<br/>
+
+<p>For more details on Deltacloud Ruby client see the full <a href="http://deltacloud.apache.org/ruby-client/doc/index.html">documentation</a>.</p>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/usage.html#clients"><i class="icon-arrow-left icon-white" style="vertical-align:baseline"> </i> Back</a>
+
+<br/>
Added: deltacloud/trunk/site/content/run-deltacloud-server.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/run-deltacloud-server.md?rev=1353588&view=auto
==============================================================================
--- deltacloud/trunk/site/content/run-deltacloud-server.md (added)
+++ deltacloud/trunk/site/content/run-deltacloud-server.md Mon Jun 25 15:05:02 2012
@@ -0,0 +1,89 @@
+---
+site_name: Deltacloud API
+title: Run the Deltacloud server
+---
+<br/>
+<h3> Quick-start guide</h3>
+<p>This guide focuses on a linux environment. Some of the Deltacloud developers are running recent versions of <a href="http://fedoraproject.org/">Fedora</a>. However, you should be able to install Deltacloud on any OS that supports Ruby. If you are having any problems with installation, please <a href="/contact.html">let us know</a>, we'd love to hear from you!</p>
+
+<h3>Running the Deltacloud server</h3>
+<p>Start the server by typing <strong>deltacloudd -i driver_id</strong>.</p>
+<p>The <strong>driver_id</strong> is the name of the cloud provider that you have an account with, for example <code>deltacloudd -i ec2</code>.</p>
+<p>If you don't yet have an account with a cloud provider, you can still try the Deltacloud mock driver:</p>
+<pre>deltacloudd -i mock</pre>
+<p>This will start the Deltacloud server on your local machine with the mock driver, accepting connections on port 3001 (default). From version 0.4.0 of Deltacloud, you can use the '-l' flag to see all available <strong>driver_ids</strong> that can be used with the <strong>deltacloudd</strong> executable:</p>
+<pre>
+$ deltacloudd -l
+
+Available drivers:
+* condor
+* vsphere
+* opennebula
+* eucalyptus
+* rhevm
+* sbc
+* azure
+* gogrid
+* mock
+* rackspace
+* rimuhosting
+* terremark
+* ec2
+</pre>
+
+<h3>Deltacloud HTML interface</h3>
+<p>After you start the server, you are ready to use the Deltacloud HTML interface.</p>
+<p>Open the address <strong>http://localhost:3001/api</strong> in your web browser:</p>
+
+<p>To display the XML output from the server in the browser, append <strong>format=xml</strong> to each URL. On Webkit based browsers like Safari, you might need to instruct the server explicitly to <a href="http://www.gethifi.com/blog/webkit-team-admits-accept-header-error">return HTML</a>. Do this by appending <strong>format=html</strong> to each URL.</p>
+
+<p>Your browser will prompt you for <a href="/drivers.html#credentials" >credentials</a> when you invoke an operation that requires authentication.</p>
+
+<p>The '-h' flag will list all available options for <strong>deltacloudd</strong>. For example, to start the Deltacloud server with the Rackspace driver on <strong>port 10000</strong> you can use:</p>
+
+<pre>$ deltacloudd -i rackspace -p 10000</pre>
+
+<p>If you want to install the server on another machine and make Deltacloud available on your local network, you need to bind the Deltacloud server to an address other than 'localhost' (default). To start the server use the IP address of a machine where you installed and started Deltacloud. For instance:</p>
+
+<pre>$ deltacloudd -i ec2 -p 5000 -r 192.168.10.200</pre>
+
+<p>This will make the Deltacloud server available at the address <strong>http://192.168.10.200:5000/api.</strong> Instead of IP address you can also use the hostname to start the server on another machine.</p>
+
+<h3>Using CIMI</h3>
+
+<p>
+To use <a href="http://dmtf.org/standards/cloud">CIMI</a>, first, go to the direcotry <strong>~/deltacloud/server/bin</strong> and start the Deltacloud server in the background:
+</p>
+
+<pre>
+./deltacloudd -i mock --cimi &
+</pre>
+
+<p>
+Then go to the directory <strong>~/deltacloud/clients/cimi</strong> and start the CIMI client server in the background:
+</p>
+
+<pre>
+bin/start -u http://localhost:3001/cimi -r <your_server_host_name> &
+</pre>
+
+<p>
+Use the -r option to make your client accessible from other machines different from the machine on which you are running both servers.
+</p>
+
+<p>
+If there are some problems when you start up the servers, you may have missing dependencies. Check the <a href="/install-deltacloud.html#gem-list">RubyGems list</a> with the list above and make sure you don't have anything missing. If there are no problems with starting the servers, access the application using your browser by following URL:
+</p>
+
+<pre>
+http://<your_server_host_name>:4001/cimi
+</pre>
+
+<p>
+The browser will ask for credentials. To log in use mockuser and mockpassword as user ID and password.
+</p>
+
+<a class="btn btn-inverse btn-large" style="float: right" href="/usage.html">Use Deltacloud</a>
+
+<br/>
+