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 2011/10/17 14:25:28 UTC
svn commit: r1185125 [2/2] - in /incubator/deltacloud/trunk/site: content/
lib/ output/
Added: incubator/deltacloud/trunk/site/output/developers.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/developers.html?rev=1185125&view=auto
==============================================================================
--- incubator/deltacloud/trunk/site/output/developers.html (added)
+++ incubator/deltacloud/trunk/site/output/developers.html Mon Oct 17 12:25:27 2011
@@ -0,0 +1,571 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+ <head>
+ <title>
+ Deltacloud - Information for Developers
+ </title>
+ <meta content='' name='keywords' />
+ <meta content='' name='description' />
+ <meta content='text/html; charset=utf-8' http-equiv='Content-Type' />
+ <link href='./styles/favicon.ico' rel='shortcut icon' type='image/x-icon' />
+ <link href='./styles/default.css' rel='StyleSheet' title='Main style' type='text/css' />
+ <link href='./styles/default-debug.css' rel='Alternate StyleSheet' title='Debug main style' type='text/css' />
+ </head>
+ <body>
+ <div id='header'>
+ <div class='container'>
+ <div id='headerLogo' onclick="location.href='index.html';" style='cursor: pointer;'>
+ <h1>
+ Deltacloud - Many clouds. One API. No problem.
+ </h1>
+ </div>
+ </div>
+ </div>
+ <div id='navigation'>
+ <div class='container' id='menu'>
+ <ul class='l0'>
+ <li>
+ <a class='inactive' href='./index.html' title='Deltacloud Home'>Home</a>
+ </li>
+ <li>
+ <a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
+ </li>
+ <li>
+ <a class='active' href='./developers.html' title='Information for developers'>Developers</a>
+ </li>
+ <li>
+ <a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
+ </li>
+ <li>
+ <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ <div id='frontpageHeader'></div>
+ <div id='main'>
+ <div class='container' id='content-deltacloud'>
+ <h1>Contribute to the Deltacloud Project</h1>
+
+ <p><a href="http://www.apache.org/" title="The Apache Software Foundation">Apache</a> Deltacloud is
+ free, open source software licensed under the
+ <a href="http://www.apache.org/licenses/LICENSE-2.0" title="The Apache License">apache license</a>.
+ Please feel free to <a href="contact.html">contact us</a> if you have any questions about the
+ project or with any suggestions on how to improve Deltacloud. The Deltacloud
+ developer community is open to anyone that wants to contribute!</p>
+
+ <p>This page contains information for developers:</p>
+
+ <p><a name="contents" /></p>
+
+ <p><ul class="toc">
+ <li>
+ <a href="#h1">Setting up the developer environment</a>
+ <ul>
+ <li>
+ <a href="#h1_1">Getting the sources</a>
+ </li>
+ <li>
+ <a href="#h1_2">Development dependencies</a>
+ </li>
+ <li>
+ <a href="#h1_3">Building from source and installing the Deltacloud gem</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#h2">Contribute to Deltacloud</a>
+ <ul>
+ <li>
+ <a href="#h2_1">Overview of the Deltacloud directory structure</a>
+ </li>
+ <li>
+ <a href="#h2_2">Forming and sending patches</a>
+ </li>
+ <li>
+ <a href="#h2_3">Use the Deltacloud github mirror</a>
+ </li>
+ <li>
+ <a href="#h2_4">Writing a new cloud provider driver</a>
+ </li>
+ <li>
+ <a href="#h2_5">Writing and running tests</a>
+ </li>
+ <li>
+ <a href="#h2_6">Licensing - the Apache Individual Contributor License Agreement</a>
+ </li>
+ </ul></li></ul></p>
+
+ <br>
+
+
+ <hr />
+
+ <br>
+
+
+ <h2 id="h1">Setting up the developer environment</h2>
+
+ <p>The information here is about setting up a dev environment for Deltacloud. If you
+ are interested in first trying out Deltacloud, you should instead follow the
+ instructions in the <a href="download.html">Download</a> page and read the
+ <a href="documentation.html#install_deltacloud">installation and quick start guide</a>.</p>
+
+ <p>Before setting up the development environment, make sure you have all the
+ <a href="documentation.html#dependencies">installation dependencies</a>.</p>
+
+ <h3 id="h1_1">Getting the sources</h3>
+
+ <p>Deltacloud provides the API server and drivers to various cloud providers.
+ It also includes a ruby client library and a commandline interface.</p>
+
+ <p><strong>First, make sure you have installed all <a href="documentation.html#dependencies">dependencies</a>.</strong></p>
+
+ <p>The Deltacloud repository is hosted at the Apache Software Foundation.
+ Apache uses <strong><em>subversion</em></strong> and you can find the Deltacloud subversion repository
+ at <a href="https://svn.apache.org/repos/asf/incubator/deltacloud">https://svn.apache.org/repos/asf/incubator/deltacloud</a>.</p>
+
+ <p>However many of the Deltacloud developers use the
+ <a href="http://git-scm.com/download">git version control system</a> and the Deltacloud
+ code is available through a git mirror. The instructions on this page are
+ thus specific to using <strong><em>git</em></strong> for getting the code and also
+ for making and sending patches.</p>
+
+ <p>If you don't already have <strong><em>git</em></strong> there are
+ <a href="http://git-scm.com/download">git binaries</a> available for specific systems.
+ Alternatively, if you use the <strong><em>yum</em></strong> or <strong><em>apt</em></strong> package managers:</p>
+
+ <pre><code>$ sudo yum install git
 <OR>
$ sudo apt-get install git
</code></pre>
+
+ <p>With <strong><em>git</em></strong> in place, to get the latest HEAD of the Deltacloud git repo:</p>
+
+ <pre><code>$ mkdir DeltacloudProject
$ cd DeltacloudProject
$ git clone git://git.apache.org/deltacloud.git
</code></pre>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h1_2">Development dependencies</h3>
+
+ <p>Apart from the <a href="documentation.html#dependencies">installation dependencies</a>,
+ in order to develop for Deltacloud you will need some additional libraries,
+ such as <a href="http://cukes.info/">cucumber</a>,
+ <a href="http://bashdb.sourceforge.net/ruby-debug/home-page.html">ruby-debug</a> and
+ <a href="http://rspec.info/">rpsec</a>. The Deltacloud source includes a Gemfile which
+ lists these development dependencies: <strong>/path/to/deltacloud/server/Gemfile</strong>.</p>
+
+ <p>Thus, the recommended way to get all development dependencies is with
+ <a href="http://gembundler.com/">Bundler</a>. If you don't already have bundler, install
+ it:</p>
+
+ <pre><code>$ sudo gem install bundler
</code></pre>
+
+ <p>Then, you can get all the required developer dependencies by:</p>
+
+ <pre><code>$ cd /path/to/deltacloud/server
$ bundle install --system
</code></pre>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h1_3">Building from source and installing the Deltacloud gem</h3>
+
+ <p>To build and install the Deltacloud server gem:</p>
+
+ <pre><code>$ cd path/to/DeltacloudProject/deltacloud/server
$ rake package
$ sudo gem install pkg/deltacloud-core-<version>.gem
</code></pre>
+
+ <p>Then install the Deltacloud client gem:</p>
+
+ <pre><code>$ cd path/to/DeltacloudProject/deltacloud/client
$ rake package
$ sudo gem install pkg/deltacloud-client-<version>.gem
</code></pre>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h2 id="h2">Contribute to Deltacloud</h2>
+
+ <p>The information here is aimed at helping developers more quickly understand the Deltacloud
+ project code, the process used by the development community for contributing and some
+ guidelines on how to go about adding a cloud provider driver to the Deltacloud project.</p>
+
+ <h3 id="h2_1">Overview of the Deltacloud directory structure</h3>
+
+ <p><strong>Note:</strong> the following is not an exhaustive list of all files and directories in the
+ Deltacloud project. Rather it is intended as an aid to ease familirisation
+ with the project files for developers - for example to quickly identify where
+ the Deltacloud cloud provider drivers are stored:</p>
+
+ <p><a name="deltacloud_directories"> .</a></p>
+
+ <pre><code>deltacloud
|-----------------------------------------------------------------------------------
|-d-->tests Contains Cucumber tests
|-----------------------------------------------------------------------------------
|-d-->site Files for this website
|-----------------------------------------------------------------------------------
|-d-->client Contains the Deltacloud ruby client
|-----------------------------------------------------------------------------------
|-d-->clients Contains other Deltacloud clients (e.g. java)
|-----------------------------------------------------------------------------------
|-d--> server
 |----------------------------------------------------------------------------
 |-f-->server.rb Contains the s
inatra routes
 |----------------------------------------------------------------------------
 |-d-->bin Contains the Deltacloud executable deltacloudd
 |----------------------------------------------------------------------------
 |-d-->views Contains haml views for each collection
 |----------------------------------------------------------------------------
 |-d-->tests Contains unit tests for drivers
 |----------------------------------------------------------------------------
 |-d-->lib
 |----------------------------------------------------------------------
 |-d-->sinatra Contains rabbit DSL and various helpers
 |----------------------------------------------------------------------
 |-d-->deltacloud�
A; |----------------------------------------------------------------
 |-d-->models Definition of each collection model
 |----------------------------------------------------------------
 |-d-->drivers Contains the drivers for each cloud provider
 |----------------------------------------------------------------
 |-d-->helpers Various helper methods used by the drivers
 |----------------------------------------------------------------
 |-d-->base_driver Contains the Deltacloud base driver
 |----------------------------------------------------------------
</code></pre>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h2_2">Forming and sending patches</h3>
+
+ <p>There are many ways to work with git and there are many
+ <a href="http://book.git-scm.com/">good resources</a> on using git. The Deltacloud community uses
+ a <strong><em>local_branch</em></strong> ---> <strong><em>patch</em></strong> ---> <strong><em>review</em></strong> ---> <strong><em>accept</em></strong> ---> <strong><em>commit</em></strong>
+ process for contributing to the project. The following shows the typical workflow used
+ by the core developers.</p>
+
+ <p>First you need to set some settings inside the git configuration file. In the root
+ of the git project (Deltacloud in this case) there is a .git hidden directory containing
+ the config file. Open this with your preferred editor:</p>
+
+ <pre><code>$ vim deltacloud/.git/config
</code></pre>
+
+ <p>Add the following to any existing configuration replacing the relevant values with your own:</p>
+
+ <pre><code>[sendemail]
signedoffbycc = no
chainreplyto = no
smtpserver = your_smpt.server.address
thread = yes
from = your_email_address
suppresscc = all

[core]
whitespace = trailing-space,space-before-tab

[apply]
whitespace = error-all
</code></pre>
+
+ <p>After getting the latest HEAD of the Deltacloud git repo, you will have one local
+ branch called <strong><em>trunk</em></strong>.</p>
+
+ <pre><code>$ git branch
* trunk
</code></pre>
+
+ <p>Fetch the latest changes from the git repo:</p>
+
+ <pre><code>$ git pull
</code></pre>
+
+ <p>Make a new local branch for your edits and give it a name:</p>
+
+ <pre><code>$ git checkout -b my_new_branch
</code></pre>
+
+ <p>Make your edits/changes/voodoo. Once done, review which files you changed:</p>
+
+ <pre><code>$ git status
</code></pre>
+
+ <p>Once you are happy with the changes and everything is working, commit those changes
+ to your local branch:</p>
+
+ <pre><code>$ git commit -a
</code></pre>
+
+ <p>This will open an editor (e.g., vi) for you to enter a commit message. Please keep this
+ short and succint in general and keep individual lines at no longer than 80 characters.
+ The command <strong>git log</strong> will show you recent commits together with their commit messages
+ as examples.</p>
+
+ <p>At this point, your local branch will contain the changes that you worked on and will
+ be different from your <strong><em>local</em></strong> <strong>trunk</strong> branch. In the meantime, other developers
+ may have already committed changes to the <strong><em>remote</em></strong> <strong>trunk</strong> branch in the Apache git repo.
+ Thus, you need to fetch any new changes and merge into your <strong><em>local</em></strong> <strong>trunk</strong> and then
+ rebase your local <strong>trunk</strong> onto the new branch which contains your changes.</p>
+
+ <p>Change to trunk and fetch upstream changes if any:</p>
+
+ <pre><code>$ git checkout trunk
$ git pull
</code></pre>
+
+ <p>Your <strong><em>local</em></strong> trunk is now up-to-date with the <strong><em>remote</em></strong> trunk in the git repo.
+ Next, rebase the <strong><em>local</em></strong> trunk onto the branch containing your changes:</p>
+
+ <pre><code>$ git rebase trunk my_new_branch
</code></pre>
+
+ <p>Now you are ready to make patches against trunk and send them to the Deltacloud mailing
+ list for review by other developers in the community:</p>
+
+ <pre><code>$ git format-patch -o /path/to/where/you/keep/patches/ trunk

$ git send-email --compose --subject 'some subject'
 --thread /path/to/where/you/keep/patches/* --to deltacloud-dev@incubator.apache.org
</code></pre>
+
+ <p>Your patches will be reviewed by other members of the community. The general rule used
+ is that a patch will be committed to the repo if it receives at least one <strong>ACK</strong> and no
+ <strong>NACK</strong>. Once a patch is <strong>ACK</strong>ed it will be committed by one of the Deltacloud community
+ developers that have commit rights to the Apache repo. If your patches are on the mailing
+ list for a few days and no-one is responding to them feel free to send a reminder email
+ as patches may be missed/forgotten.</p>
+
+ <p>You can also contribute to the project by reviewing patches sent by other contributors:</p>
+
+ <p>Make a new branch where you will apply the patches and test:</p>
+
+ <pre><code>$ git checkout -b jsmith_patches
</code></pre>
+
+ <p>You can use either git am ("apply mail") to apply patches in mail format, or git apply for
+ plain-text patches. Using git am will also commit the patches to the local branch
+ preserving the author's commit messages whilst git apply will only apply the files but not
+ commit them. For simple patch review the difference between these is insignificant and
+ boils down to whether you like to save the patches as plain-text or in .mbox email format.</p>
+
+ <p>Save the patches to some known location, make sure you're on the branch you wish to apply
+ them onto, and then apply:</p>
+
+ <pre><code>$ git checkout jsmith_patches

$ cat /path/to/patches/0001-name-of-patch.txt | git apply
 _OR_
$ git am /path/to/patches/0001-name-of-patch.eml
</code></pre>
+
+ <p>If you think the patches are sane, do what the author intended and most importantly don't
+ break anything else, then you can send an <strong>ACK</strong> in response to the patches on the
+ Deltacloud <a href="contact.html">mailing list</a>. Similarly, if you think there is some problem
+ with the patches you should send a <strong>NACK</strong> with an explanation of the problem you have
+ found so that the author can address this.</p>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h2_3">Use the Deltacloud github mirror</h3>
+
+ <p>The Deltacloud project maintains a
+ <a href="https://github.com/apache/deltacloud">github page</a> which mirrors the Apache
+ repository. You can contribute through github if that is preferrable.
+ <a href="http://help.github.com/fork-a-repo/">Fork</a> the Deltacloud repo, make your changes and
+ commit them back to your fork. Then issue a
+ <a href="http://help.github.com/send-pull-requests/">pull request</a>. It may also be wise to
+ send an email to the Deltacloud <a href="contact.html">mailing list</a> to let the community know
+ about your pull request as in general the mailing list is checked much more often than
+ the github page.</p>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h2_4">Writing a new cloud provider driver</h3>
+
+ <p>The deltacloud drivers live in
+ <a href="#deltacloud_directories">deltacloud/server/lib/deltacloud/drivers</a>. The information here
+ is intended as a primer for anybody that wants to contribute a new cloud provider driver to
+ the Deltacloud project.</p>
+
+ <p>To add a driver for a hypothetical <strong>Foo</strong> cloud, you should start by adding a a directory
+ under /drivers/ and then a file for the driver itself, i.e.:</p>
+
+ <pre><code>deltacloud/server/lib/deltacloud/drivers/foo/foo_driver.rb
</code></pre>
+
+ <p>That file needs to define a class <strong>Deltacloud::Drivers::Foo::FooDriver</strong> and must be
+ a subclass of the Deltacloud::BaseDriver (example follows).</p>
+
+ <p>You need to decide which <a href="api.html#h1">collections</a> the provider for which you're
+ writing the driver supports - e.g. images, instances, keys, buckets/blobs (storage), etc.
+ and declare these with:</p>
+
+ <pre><code>def supported_collections
 DEFAULT_COLLECTIONS + [ :buckets ] - [ :storage_snapshots, :storage_volumes ]
end
</code></pre>
+
+ <p>The above declares that the driver supports the <strong>DEFAULT_COLLECTIONS</strong> (defined in
+ <strong>deltacloud/server/lib/drivers.rb</strong>) except <a href="api.html#h4_2">storage_snapshots</a> and
+ <a href="api.html#h4_1">storage_volumes</a> and additionally also supports the
+ <a href="api.html#h4_3">buckets</a> collection. For example, a storage only cloud provider driver
+ would support only the <strong>buckets</strong> colletion.</p>
+
+ <p>You can then start to define the methods for each of the collections that your driver
+ will support. The methods for each collection, as well as the routes that map to them
+ are defined in <strong>/deltacloud/server/server.rb</strong>. In general you can look at the existing
+ drivers for pointers on how to implement any specific method.</p>
+
+ <p>One important consideration is how your cloud provider driver will be communicating
+ with the cloud provider. Many of the existing drivers use external ruby gems for this
+ purpose: for example, the <strong>ec2</strong> driver uses the <a href="https://github.com/appoxy/aws/">aws</a>
+ gem, the <strong>rackspace</strong> driver uses the
+ <a href="https://github.com/rackspace/ruby-cloudfiles">cloudfiles</a> and
+ <a href="https://github.com/rackspace/ruby-cloudservers">cloudservers</a> gems. However, other drivers
+ implement their own clients with which to communicate with the cloud provider, such as
+ the IBM SBC driver and the Gogrid driver. This also explains why, under the /drivers
+ directory, some drivers contain only the provider_<strong><em>driver</em></strong>.rb file, whilst others also
+ define a provider_<strong><em>client</em></strong>.rb file. Whether you write your own client or use an existing
+ one is entirey at your discretion.</p>
+
+ <p>Thus, your driver for the cloud provider foo may start out looking something like:</p>
+
+ <pre><code>require 'deltacloud/base_driver'
require 'foo_lib' # a library for talking to the foo cloud

module Deltacloud
 module Drivers
 module Foo

class FooDriver < Deltacloud::BaseDriver

 def supported_collections
 DEFAULT_COLLECTIONS + [ :buckets ]
 end

 def images(credentials, opts={})
 client = new_foo_client(credentials)
 # use client to get a list of images from the back-end cloud and then create
 # a Deltacloud Image object for each of these. Filter the result
 # (eg specific image requested) and return to user
 end

 def realms(credentials, opts={})
 (...)
 end

 def instances(credentials, opts={})
 (...)
 end

 ... ETC

 private

 def new_foo_client(credentia
ls)
 client = FooLib::Service.new({:user => credentials.user,
 :pass => credentials.password })
 end

end
 end
 end
 end
</code></pre>
+
+ <p>One important method for drivers that implement the <a href="api.html#h3_5">instances</a>
+ collection is <strong>instance_states</strong>. This method represents the finite-state-machine
+ for instances which varies across cloud providers. For example, in some clouds
+ an instance may be in the 'running' state after creation, whereas in other clouds
+ an instance may need to be started explicitly. An example of what this method may
+ look like is:</p>
+
+ <pre><code>define_instance_states do
 start.to( :pending ) .on( :create )
 pending.to( :running ) .automatically
 running.to( :running ) .on( :reboot )
 running.to( :shutting_down ) .on( :stop )
 shutting_down.to( :stopped ) .automatically
 stopped.to( :finish ) .automatically
end
</code></pre>
+
+ <p>The voodoo used here (i.e. definition of .to and .on etc) is defined in
+ /deltacloud/server/lib/deltacloud/state_machine.rb.</p>
+
+ <p>Valid states are</p>
+
+ <ul>
+ <li><strong><code>:begin</code></strong></li>
+ <li><strong><code>:pending</code></strong></li>
+ <li><strong><code>:running</code></strong></li>
+ <li><strong><code>:shutting_down</code></strong></li>
+ <li><strong><code>:stopped</code></strong></li>
+ <li><strong><code>:end</code></strong></li>
+ </ul>
+
+
+ <p>The <code>:begin</code> state is the state an instance is in immediate before
+ being created. The <code>:end</code> state is the state an instance is in
+ immediately after being destroyed.</p>
+
+ <p>Valid transition actions are</p>
+
+ <ul>
+ <li><strong><code>:stop</code></strong></li>
+ <li><strong><code>:start</code></strong></li>
+ <li><strong><code>:reboot</code></strong></li>
+ </ul>
+
+
+ <p>Additionally, to indicate a transition that may occur <em>without</em> an
+ action being triggered, the action <strong><code>:automatically</code></strong> may be used,
+ as shown in the example above.</p>
+
+ <p>Depending on the collections you'll be supporting, some other methods that
+ your driver may implement are:</p>
+
+ <ul>
+ <li><code>hardware_profiles(credentials, opts=nil)</code></li>
+ <li><code>images(credentials, opts=nil )</code></li>
+ <li><code>realms(credentials, opts=nil)</code></li>
+ <li><code>instances(credentials, opts=nil)</code></li>
+ <li><code>create_instance(credentials, image_id, opts)</code></li>
+ <li><code>reboot_instance(credentials, id)</code></li>
+ <li><code>stop_instance(credentials, id)</code></li>
+ <li><code>destroy_instance(credentials, id)</code></li>
+ </ul>
+
+
+ <p>As a further example, the <code>hardware_profiles(...)</code> method should
+ return an array of <code>HardwareProfile</code> objects. The <code>opts</code> hash, if
+ present, must be inspected for <code>:id</code> and <code>:architecture</code> keys. If these keys
+ are present, the results should be filtered by the value associated with
+ each key. The <code>filter_on(...)</code> helper method is used for this filtering
+ and as you can see from existing driver method definitions, is invoked
+ in many of the driver collection methods:</p>
+
+ <pre><code>def hardware_profiles(credentials, opts=nil)
 hardware_profiles = # get all hardware profiles from provider
 hardware_profiles = filter_on( hardware_profiles, :id, opts )
 hardware_profiles = filter_on( hardware_profiles, :architecture, opts )
 return hardware_profiles
end
</code></pre>
+
+ <p>Once you've implemented some of the methods for your driver you can start to
+ 'run' it and test that things are working as expected. To do this, you need to
+ create a yaml file for your driver so that the Deltacloud server 'knows' about
+ it. Assuming you've written the driver for cloud Foo and you've called it
+ foo_driver.rb (which contains the class Deltacloud::Drivers::Foo::FooDriver)
+ , you need to drop a file into <strong>/deltacloud/server/config/drivers</strong> called
+ <strong>foo.yaml</strong>, containing the following:</p>
+
+ <pre><code>---
:foo:
 :name Foo
</code></pre>
+
+ <p>You can then start the Deltacloud server with:</p>
+
+ <pre><code>deltacloudd -i foo
</code></pre>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h2_5">Writing and running tests</h3>
+
+ <p>If you add a new feature or write a new driver, you might like to add some tests to
+ make sure everything is running as expected. At present the Deltacloud project uses
+ Unit tests which live in <strong>/deltacloud/server/tests</strong> as well as Cucumber tests which live
+ in <strong>/deltacloud/tests</strong>.</p>
+
+ <p>You can invoke the Unit tests:</p>
+
+ <pre><code>$ cd /path/to/deltacloud/server
$ rake test
</code></pre>
+
+ <p>As you can see by inspecting the Rakefile in /deltacloud/server, this will invoke all
+ Unit tests defined in /deltacloud/server/tests. You can invoke specific driver tests by:</p>
+
+ <pre><code>$ cd /path/to/deltacloud/server
$ rake test:rackspace
 _OR_
$ rake test:mock
 _etc_
</code></pre>
+
+ <p>You can invoke the Cucumber tests:</p>
+
+ <pre><code>$ cd /path/to/deltacloud/server
$ rake cucumber
</code></pre>
+
+ <p>Alternatively, you can bypass the Rakefile and invoke the cucumber tests directly:</p>
+
+ <pre><code>$ cd /path/to/deltacloud/server
$ cucumber ../tests/mock
 _OR_
$ cucumber ../tests/ec2
 _etc_
</code></pre>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <hr />
+
+ <br>
+
+
+ <h3 id="h2_6">Licensing - the Apache Individual Contributor License Agreement</h3>
+
+ <p>Deltacloud is an <a href="http://www.apache.org/">Apache Software Foundation</a> project. As such
+ and in keeping with all Apache projects, contributors are required to sign an individual
+ contributor license agreement. This, together with instructions on signing and sending
+ the agreement can be <a href="http://www.apache.org/licenses/icla.txt">found here</a>. Please do
+ not hesitate to <a href="contact.html">contact us</a> if you have any queries or require any
+ clarification about contributing to the Deltacloud project.</p>
+
+ <br>
+
+
+ <p><a href="#contents">contents</a></p>
+
+ <br>
+
+
+
+ </br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br></br>
+ </div>
+ </div>
+ <div id='footer-deltacloud'>
+ <div class='container'>
+ <p>
+ <a href='http://incubator.apache.org'>
+ <img alt='Apache Incubator Logo' src='http://incubator.apache.org/images/apache-incubator-logo.png' />
+ </a>
+ </p>
+ <p id='disclaimer'>
+ Apache Deltacloud is an effort undergoing incubation at The
+ Apache Software Foundation (ASF), sponsored by the Apache
+ Incubator PMC. Incubation is required of all newly accepted
+ projects until a further review indicates that the
+ infrastructure, communications, and decision making process have
+ stabilized in a manner consistent with other successful ASF
+ projects. While incubation status is not necessarily a reflection
+ of the completeness or stability of the code, it does indicate
+ that the project has yet to be fully endorsed by the ASF.
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Modified: incubator/deltacloud/trunk/site/output/documentation.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/documentation.html?rev=1185125&r1=1185124&r2=1185125&view=diff
==============================================================================
--- incubator/deltacloud/trunk/site/output/documentation.html (original)
+++ incubator/deltacloud/trunk/site/output/documentation.html Mon Oct 17 12:25:27 2011
@@ -31,11 +31,14 @@
<a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
</li>
<li>
- <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+ <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
</li>
<li>
<a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
</li>
+ <li>
+ <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+ </li>
</ul>
</div>
</div>
@@ -44,7 +47,7 @@
<ul class='l1'>
<li>
<a class='active' href='documentation.html'>
- Overview
+ Installation
</a>
</li>
<li>
@@ -58,11 +61,6 @@
</a>
</li>
<li>
- <a class='inactive' href='framework.html'>
- Framework
- </a>
- </li>
- <li>
<a class='inactive' href='client-ruby.html'>
Ruby Client
</a>
@@ -82,292 +80,462 @@
<p>The Deltacloud documentation is divided into the following parts:</p>
<ul>
<li>
+ <a href='documentation.html'>
+ Installation, dependencies and quick-start (this page)
+ </a>
+ </li>
+ <li>
<a href='api.html'>
REST API definition
</a>
</li>
<li>
<a href='drivers.html'>
- Currently-supported drivers
+ Information about currently supported drivers
</a>
</li>
<li>
- <a href='framework.html'>
- Framework for writing additional drivers
+ <a href='client-ruby.html'>
+ The Deltacloud Ruby client
</a>
</li>
<li>
- <a href='client-ruby.html'>
- Ruby client
+ <a href='libdeltacloud.html'>
+ The libdeltacloud C library
</a>
</li>
+ </ul>
+ <br />
+ <br />
+ <hr />
+ <br />
+ <a name='install_deltacloud'></a>
+ <h1>Install Deltacloud</h1>
+ This page lists the libraries and packages that you will need in order to install
+ the Deltacloud server, a "Hello Deltacloud" quick-start guide as well as some
+ information on interacting with the Deltacloud server after a succesful installation.
+ <h2>Installation of Deltacloud itself</h2>
+ Once you've setup all the dependencies listed below, installing Deltacloud is as easy as
+ typing:
+ <br />
+ <br />
+ <pre><code>$ sudo gem install deltacloud-core</code></pre>
+ And
+ <strong>thats it!</strong>
+ The
+ <strong>gem install</strong>
+ command will automatically fetch and install all other gems that the Deltacloud server
+ needs if you don't already have these. As an alternative you can get the latest
+ releases of Deltacloud from the
+ <a href='http://www.apache.org/dist/incubator/deltacloud/'>
+ Apache website.
+ </a>
+ <br />
+ <br />
+ <hr />
+ <br />
+ <a name='dependencies'></a>
+ <h2>Installation dependencies</h2>
+ The Deltacloud server relies on a number of external rubygems and other libraries.
+ You must have the following packages installed before trying to install and
+ run the Deltacloud server. Please note that the names of the packages below
+ may differ for your distribution (e.g. 'ruby-devel' vs 'ruby-dev'). In short, you need:
+ <br />
+ <br />
+ <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>
+ More info on getting these follows:
+ <h3>ruby and ruby-devel</h3>
+ You need to
+ <a href='http://www.ruby-lang.org/en/downloads/'>
+ install ruby.
+ </a>
+ You can check to see if you already have a ruby installation by typing:
+ <br />
+ <br />
+ <pre><code>$ ruby -v</code></pre>
+ If you see something that looks like the following:
+ <br />
+ <br />
+ <pre><code>ruby 1.8.7 (2010-08-16 patchlevel 302) [i686-linux]</code></pre>
+ then you can skip the ruby installation. Deltacloud requires ruby to be
+ at least version 1.8.7. You also need the development headers (ruby-devel) as
+ Deltacloud relies on some rubygems with C extensions. If you use a package manager
+ such as yum or apt-get:
+ <br />
+ <br />
+ <pre><code>sudo yum install ruby
sudo yum install ruby-devel</code></pre>
+ OR
+ <br />
+ <br />
+ <pre><code>sudo apt-get install ruby
sudo apt-get install ruby-devel</code></pre>
+ <h3>gem (RubyGems)</h3>
+ Deltacloud relies on a number of ruby gems so you also need to
+ <a href='http://docs.rubygems.org/read/chapter/3'>
+ install RubyGems.
+ </a>
+ As with ruby, you can check if you already have the
+ <strong>gem</strong>
+ executable installed by typing
+ <strong>gem -v</strong>
+ . Again, your package manager can help with the installation:
+ <br />
+ <br />
+ <pre><code>$ sudo yum install rubygems</code></pre>
+ <h3>gcc-c++, libxml2, libxml2-devel, libxslt, libxslt-devel</h3>
+ These are required to build RubyGems that have C extensions. Again, typically
+ the easiest way to get these is with you package manager:
+ <br />
+ <br />
+ <pre><code>$ sudo yum install gcc-c++
$ sudo yum install libxml libxml2-devel
$ sudo yum install libxslt libxslt-devel</code></pre>
+ <h3>rake</h3>
+ <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:
+ <br />
+ <br />
+ <pre><code>$ sudo gem install rake</code></pre>
+ <br />
+ <br />
+ <hr />
+ <br />
+ <a name='quick_start'></a>
+ <h1>"Hello Deltacloud!", quick-start guide</h1>
+ This guide assumes a linux environment. Some of the Deltacloud developers
+ are running recent versions of
+ <a href='http://fedoraproject.org'>
+ Fedora.
+ </a>
+ However, as Deltacloud is written in Ruby you should be able to install it on
+ any OS that supports Ruby. If you have succesfully installed Deltacloud or are
+ having any problems doing so, please
+ <a href='contact.html'>
+ let us know,
+ </a>
+ we'd love to hear from you!
+ <h2>Running the Deltacloud server</h2>
+ After you succesfully install Deltacloud, you can start the server by typing
+ <strong>
+ deltacloudd -i
+ <em>
+ provider_id.
+ </em>
+ </strong>
+ The
+ <strong>
+ <em>
+ provider_id
+ </em>
+ </strong>
+ is the name of the cloud provider that you have an account with, for example 'ec2'.
+ If you don't yet have an account with a cloud provider, you can still try the Deltacloud
+ mock driver:
+ <br />
+ <br />
+ <pre><code>deltacloudd -i mock</code></pre>
+ This will start the Deltacloud server on your local machine with the mock driver, accepting
+ connections on port 3001 (the default). From version 0.4.0 of Deltacloud, you can use the
+ '-l' flag to see
+ <a href='drivers.html#providers'>
+ all available
+ </a>
+ <strong>
+ <em>
+ provider_ids
+ </em>
+ </strong>
+ that can be used with the
+ <strong>deltacloudd</strong>
+ executable.
+ <br />
+ <br />
+ <pre><code>$ deltacloudd -l
<br />
Available drivers:
* condor
* vsphere
* opennebula
* eucalyptus
* rhevm
* sbc
* azure
* gogrid
* mock
* rackspace
* rimuhosting
* terremark
* ec2</code></pre>
+ After you start the server, the Deltacloud HTML interface is available at
+ <strong>
+ http://localhost:3001/api
+ </strong>
+ - open this address in your web browser. If you want to see XML output from the
+ server in the browser, append
+ <strong>
+ <em>
+ format=xml
+ </em>
+ </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>
+ <em>
+ format=html
+ </em>
+ </strong>
+ to each URL. Your browser will prompt you for
+ <a href='drivers.html#credentials'>
+ credentials
+ </a>
+ when you invoke an operation that requires
+ <a href='api.html#authentication'>
+ authentication.
+ </a>
+ <br />
+ <br />
+ The '-h' flag will list all available options for
+ <strong>deltacloudd.</strong>
+ For example, to start the Deltacloud server with the Rackspace driver on port 10000
+ you can use:
+ <br />
+ <br />
+ <pre><code>$ deltacloudd -i rackspace -P 10000</code></pre>
+ You may want to install the server on another machine and make Deltacloud available on
+ your local network. To do this you need to bind the Deltacloud server to an address other
+ than 'localhost' (default). For instance, if you install and start Deltacloud on a machine
+ with the IP address 192.168.10.200 you should start the server with:
+ <br />
+ <br />
+ <pre><code>$ deltacloudd -i ec2 -P 5000 -r 192.168.10.200</code></pre>
+ This will make the Deltacloud server available at the address
+ <strong>
+ http://192.168.10.200:5000/api.
+ </strong>
+ <br />
+ <br />
+ <br />
+ <br />
+ <hr />
+ <br />
+ <h2>The Deltacloud ruby client</h2>
+ The Deltacloud project also maintains a ruby client, which you need to install
+ seperately to the Deltacloud API server. The Deltacloud client consists of a
+ ruby library (packaged as a ruby gem) which you can use to programmatically
+ interact with the Deltacloud server and control your cloud infrastructure
+ across cloud providers. For example, assuming the Deltacloud server is
+ running at
+ <strong>
+ 192.168.10.244:5000
+ </strong>
+ <br />
+ <br />
+ <pre><code>require 'deltacloud'
<br />
api_url = 'http://192.168.10.244:5000/api'
api_name = 'TK2PJCAN9R1HKG2FK24Z'
api_password = 'aLe27rZlRhlBcVoQbL4JsVtaNga12vEL9d9kS5CA'
<br />
client = DeltaCloud.new( api_name, api_password, api_url )
<br />
# get a list of currently running instances (virtual machines)
client.instances.each do |instance|
 puts instance.name
end
<br />
<div id='do'>other work with client here</div></code></pre>
+ More comprehensive information on using the Deltacloud ruby client in this way
+ can be found in the
+ <a href='client-ruby.html'>
+ client documentation.
+ </a>
+ Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud
+ client by simply typing:
+ <br />
+ <br />
+ <pre><code>$ sudo gem install deltacloud-client</code></pre>
+ Installing the Deltacloud client also gives you the
+ <strong>
+ deltacloudc
+ </strong>
+ command line tool. This executable makes use of the Deltacloud client library to speak to the
+ Deltacloud server using the
+ <a href='api.html'>
+ REST API.
+ </a>
+ This allows you to to control your IAAS cloud infrastructure form the command line;
+ even better if you are familiar with linux scripting, you can knock up a bash script in no time
+ to automate your cloud infrastructure tasks.
+ The general usage pattern for deltacloudc is:
+ <br />
+ <br />
+ <pre><code>$ deltacloudc collection operation [options]</code></pre>
+ <ul>
<li>
- <a href='libdeltacloud.html'>
- C library
+ <strong>
+ <em>
+ collection
+ </em>
+ </strong>
+ refers to the Deltacloud object collections, such as Instances,
+ Images, Buckets, Realms etc, as described in greater detail in the
+ <a href='api.html#h1'>
+ REST API
+ </a>
+ </li>
+ <li>
+ <strong>
+ <em>
+ operation
+ </em>
+ </strong>
+ is collection dependant. All collections respond to 'index'
+ and 'show' operations (retrieve details on all objects in a given collection
+ or on a specific object, respectively); some collections respond to 'create' and 'destroy'
+ operations. The instances collection (realised virtual servers) responds to operations
+ for managing the instance lifecycle, such as 'stop', 'reboot' etc.
+ </li>
+ <li>
+ <strong>
+ <em>
+ options
+ </em>
+ </strong>
+ are listed by invoking
+ <strong>deltacloudc -h</strong>
+ One important option is
+ <strong>-u,</strong>
+ with which you specify the API_URL where the Deltacloud server is running. The API_URL
+ takes the form
+ <strong>
+ http://[user]:[password]@[api_url]:[port]/[api]
+ </strong>
+ (examples follow). Alternatively, rather than having to supply the API_URL for every
+ invocation of
+ <strong>
+ deltacloudc
+ </strong>
+ you have the choice of setting the API_URL environment variable
+ (e.g., export API_URL=http://mockuser:mockpassword@localhost:3001/api). A
+ listing of the credentials you need to provide for each back-end cloud provider
+ is available
+ <a href='drivers.html#credentials'>
+ here.
</a>
</li>
</ul>
- <h1>Usage</h1>
- <p>
- The server listens by default on
- <tt>
- http://localhost:3001/.
- </tt>
- For testing and exploring, the server can be used from a web browser and
- will return HTML to it. If you want to see XML output from the server in
- the browser, append
- <tt>
- ?format=xml
- </tt>
- to each URL.
- </p>
- <p>
- 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
- <tt>
- ?format=html
- </tt>
- to each URL.
- </p>
- <h2>Logging into the server</h2>
- <p>
- Deltacloud uses basic HTTP authentication to receive credentials from the
- client and passes them through to the backend cloud it is talking to. The
- credentials always consist of a username and password, and are never
- stored on the server. The exact credentials for logging into the server,
- and where you find them, depends on the backend cloud that the server is
- talking to.
- </p>
- <p>
- The following table gives details about how to set up the server and what
- credentials to provide for each of the supported clouds. The entry from
- the Driver column needs to be passed as the
- <tt>
- --driver
- </tt>
- option to
- <tt>
- deltacloudd.
- </tt>
- Note that some of the drivers require additional information, e.g.,
- API endpoint URL's, be passed through environment variables
- </p>
- <table id='providers'>
- <tr>
- <th>
- <strong>Cloud</strong>
- </th>
- <th>
- <strong>Driver</strong>
- </th>
- <th>
- <strong>Username</strong>
- </th>
- <th>
- <strong>Password</strong>
- </th>
- <th>
- <strong>Notes</strong>
- </th>
- </tr>
- <tr>
- <td>
- <strong>mock</strong>
- </td>
- <td>
- <tt>mock</tt>
- </td>
- <td>
- <tt>
- mockuser
- </tt>
- </td>
- <td>
- <tt>
- mockpassword
- </tt>
- </td>
- <td>
- The mock driver doesn't talk to any cloud; it just pretends to be a cloud
- </td>
- </tr>
- <tr>
- <td>
- <strong>Amazon EC2/S3</strong>
- </td>
- <td>
- <tt>ec2</tt>
- </td>
- <td>
- Access Key ID
- </td>
- <td>
- Secret Access Key
- </td>
- <td>
- This information can be found on the
- <a href='http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key'>Security Credentials</a>
- page in your AWS account
- </td>
- </tr>
- <tr>
- <td>
- <strong>Eucalyptus</strong>
- </td>
- <td>
- <tt>eucalyptus</tt>
- </td>
- <td>
- Access Key ID
- </td>
- <td>
- Secret Access Key
- </td>
- <td></td>
- </tr>
- <tr>
- <td>
- <strong>GoGrid</strong>
- </td>
- <td>
- <tt>gogrid</tt>
- </td>
- <td>
- API Key
- </td>
- <td>
- Shared Secret
- </td>
- <td>
- Go to
- <tt>My Account > API Keys</tt>
- for
- <a href='https://my.gogrid.com/gogrid/com.servepath.gogrid.GoGrid/index.html'>your account</a>
- and click on the key you want to use to find the shared secret.
- </td>
- </tr>
- <tr>
- <td>
- <strong>IBM SBC</strong>
- </td>
- <td>
- <tt>sbc</tt>
- </td>
- <td>
- Username
- </td>
- <td>
- Password
- </td>
- <td></td>
- </tr>
- <tr>
- <td>
- <strong>Microsoft Azure (Storage Account only)</strong>
- </td>
- <td>
- <tt>azure</tt>
- </td>
- <td>
- Public Storage Account Name
- </td>
- <td>
- Primary Access Key
- </td>
- <td>
- The Storage Account Name is chosen when you create the service (e.g. name in http://name.blob.core.windows.net/). This and the access key are available from the service control panel.
- </td>
- </tr>
- <tr>
- <td>
- <strong>OpenNebula</strong>
- </td>
- <td>
- <tt>opennebula</tt>
- </td>
- <td>
- OpenNebula user
- </td>
- <td>
- OpenNebula password
- </td>
- <td>
- Set the environment variable
- <tt>OCCI_URL</tt>
- to the address on which OpenNebula's OCCI server is listening.
- </td>
- </tr>
- <tr>
- <td>
- <strong>Rackspace Cloud Servers/Cloud Files</strong>
- </td>
- <td>
- <tt>rackspace</tt>
- </td>
- <td>
- Rackspace user name
- </td>
- <td>
- API Key
- </td>
- <td>
- Obtain the key from the
- <a href='https://manage.rackspacecloud.com/APIAccess.do'>API Access</a>
- page in your control panel
- </td>
- </tr>
- <tr>
- <td>
- <strong>RHEV-M</strong>
- </td>
- <td>
- <tt>rhevm</tt>
- </td>
- <td>
- <a href='http://markmc.fedorapeople.org/rhevm-api/en-US/html/chap-REST_API_Guide-Authentication.html'>RHEV-M user name plus Windows domain</a>
- , e.g.,
- <tt>admin@rhevm.example.com</tt>
- </td>
- <td>
- RHEV-M password
- </td>
- <td>
- Set environment variable
- <tt>API_PROVIDER</tt>
- to the URL of the RHEV-M REST API endpoint.
- </td>
- </tr>
- <tr>
- <td>
- <strong>Rimuhosting</strong>
- </td>
- <td>
- <tt>rimuhosting</tt>
- </td>
- <td>not used (?)</td>
- <td>API Key</td>
- <td></td>
- </tr>
- <tr>
- <td>
- <strong>Terremark</strong>
- </td>
- <td>
- <tt>terremark</tt>
- </td>
- <td>
- Username
- </td>
- <td>
- Password
- </td>
- <td></td>
- </tr>
- </table>
+ The following examples assume that the Deltacloud server is running on your local machine
+ port 3001 (the
+ <strong>deltacloudd</strong>
+ server daemon defaults to 'localhost:3001') and was started with the 'mock' provider
+ (i.e.
+ <strong>deltacloudd -i mock</strong>
+ ).
+ To list all collections available in the current driver:
+ <br />
+ <br />
+ <pre><code>$ deltacloudc -l -u http://mockuser:mockpassword@localhost:3001/api</code></pre>
+ To get a list of all
+ <strong>images:</strong>
+ <br />
+ <br />
+ <pre><code>$ deltacloudc images index -u http://mockuser:mockpassword@localhost:3001/api</code></pre>
+ To list all operations for the
+ <strong>buckets</strong>
+ collection:
+ <br />
+ <br />
+ <pre><code>$ deltacloudc buckets -l -u http://mockuser:mockpassword@localhost:3001/api</code></pre>
+ To create a new blob in the bucket called 'bucket1':
+ <br />
+ <br />
+ <pre><code>$ deltacloudc blob create -i 'my_new_blob' -b 'bucket1' -f /home/marios/file.txt</code></pre>
+ <br />
+ <br />
+ <hr />
+ <br />
+ <h2>Other HTTP clients - cURL</h2>
+ As interaction with the Deltacloud server is via HTTP calls, you can use any
+ HTTP client to talk to it using the Deltacloud
+ <a href='api.html'>
+ REST API.
+ </a>
+ One popular command line tool available on most modern linux distributions is
+ <a href='http://curl.haxx.se/'>
+ cURL.
+ </a>
+ We give some examples here of how you can use cURL to interact with Deltacloud,
+ demonstrating the flexibility and power of the Deltacloud REST API.
+ The following examples assume the Deltacloud server is running on locahost:3001,
+ and was started with the 'ec2' driver (i.e.,
+ <strong>deltacloudd -i ec2</strong>
+ ).
+ To get a
+ <a href='api.html#list_images'>
+ listing of all images
+ </a>
+ available in the back-end cloud:
+ <br />
+ <br />
+ <pre><code>curl --user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/images?format=xml"</code></pre>
+ The cURL
+ <strong>--user</strong>
+ option is used to specify the
+ <strong>username:password</strong>
+ <a href='drivers.html#credentials'>
+ credentials
+ </a>
+ for access to the back-end cloud provider (Amazon EC2 in this case).
+ To
+ <a href='api.html#create_instance'>
+ create a new instance
+ </a>
+ from the
+ <a href='api.html#h3_3'>
+ image
+ </a>
+ with id 'ami-f51aff9c', in
+ <a href='api.html#h3_1'>
+ realm
+ </a>
+ 'us-east-1c', with the
+ <a href='api.html#h3_2'>
+ hardware profile
+ </a>
+ 'c1.medium', in
+ <a href='api.html#h3_7'>
+ firewall
+ </a>
+ 'default':
+ <br />
+ <br />
+ <pre><code>curl -X POST -F "keyname=eftah" -F "image_id=ami-f51aff9c"
-F "realm_id=us-east-1c" -F "hwp_id=c1.medium" -F "firewalls1=default"
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/instances?format=xml"</code></pre>
+ To
+ <a href='api.html#delete_firewall'>
+ delete a firewall
+ </a>
+ called 'develgroup':
+ <br />
+ <br />
+ <pre><code>curl -X DELETE
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/firewalls/develgroup?format=xml</code></pre>
+ To
+ <a href='api.html#create_blob'>
+ create a blob
+ </a>
+ called 'my_new_blob' within the
+ <a href='api.html#h4_3'>
+ bucket
+ </a>
+ 'mybucket' from a local file with
+ <strong>
+ <em>
+ HTTP PUT
+ </em>
+ </strong>
+ specifying its content type and setting some some metadata
+ <strong>
+ <em>
+ key:value
+ </em>
+ </strong>
+ pairs:
+ <br />
+ <br />
+ <pre><code>curl -H 'content-type: text/html' -H 'X-Deltacloud-Blobmeta-Name:mariosblob'
-H 'X-Deltacloud-Blobmeta-Version:2.1' --upload-file
"/home/marios/Desktop/somefile.html"
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml</code></pre>
+ To
+ <a href='api.html#h4_3_10'>
+ retrieve blob metadata
+ </a>
+ for the blob called 'my_new_blob':
+ <br />
+ <br />
+ <pre><code>curl -iv -X HEAD
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml</code></pre>
+ Note the use of the '-iv' flags here which will ensure that cURL displays the
+ request and response headers (blob metadata is reported in the response headers,
+ with an empty response body).
</div>
</div>
<div id='footer-deltacloud'>
Modified: incubator/deltacloud/trunk/site/output/drivers.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/drivers.html?rev=1185125&r1=1185124&r2=1185125&view=diff
==============================================================================
--- incubator/deltacloud/trunk/site/output/drivers.html (original)
+++ incubator/deltacloud/trunk/site/output/drivers.html Mon Oct 17 12:25:27 2011
@@ -31,11 +31,14 @@
<a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
</li>
<li>
- <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+ <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
</li>
<li>
<a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
</li>
+ <li>
+ <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+ </li>
</ul>
</div>
</div>
@@ -44,7 +47,7 @@
<ul class='l1'>
<li>
<a class='inactive' href='documentation.html'>
- Overview
+ Installation
</a>
</li>
<li>
@@ -58,11 +61,6 @@
</a>
</li>
<li>
- <a class='inactive' href='framework.html'>
- Framework
- </a>
- </li>
- <li>
<a class='inactive' href='client-ruby.html'>
Ruby Client
</a>
@@ -83,79 +81,67 @@
<!-- = title + '</h1>' -->
<ul class="toc">
<li>
- <a href="#h1">Setting up the code</a>
- </li>
- <li>
- <a href="#h2">Launch the server</a>
+ <a href="#h1">Dynamic driver switching</a>
</li>
<li>
- <a href="#h3">Dynamic driver switching</a>
+ <a href="#h2">Driver functionality and Credentials</a>
</li>
<li>
- <a href="#h4">Notes on specific drivers</a>
+ <a href="#h3">Notes on specific drivers</a>
<ul>
<li>
- <a href="#h4_1">EC2 Driver</a>
+ <a href="#h3_1">EC2 Driver</a>
</li>
<li>
- <a href="#h4_2">Eucalyptus Driver</a>
+ <a href="#h3_2">Eucalyptus Driver</a>
</li>
<li>
- <a href="#h4_3">RHEV-M Driver</a>
+ <a href="#h3_3">RHEV-M Driver</a>
</li>
<li>
- <a href="#h4_4">Rackspace Driver</a>
+ <a href="#h3_4">Rackspace Driver</a>
</li>
<li>
- <a href="#h4_5">RimuHosting</a>
+ <a href="#h3_5">RimuHosting</a>
</li>
<li>
- <a href="#h4_6">OpenNebula</a>
+ <a href="#h3_6">OpenNebula</a>
</li>
<li>
- <a href="#h4_7">IBM Smartcloud Driver</a>
+ <a href="#h3_7">IBM Smartcloud Driver</a>
</li>
</ul></li></ul>
<!-- = rest -->
- <p>Deltacloud provides drivers for a growing number of popular clouds. All drivers
- can handle a set of standard operations, some of them also support a number of
- optional operations to expose the features of specific clouds more closely. The
- drivers and their capabilities are:</p>
-
- <h2 id="h1">Setting up the code</h2>
-
- <p>To set up a Deltacloud core and the drivers, install the
- <a href="http://rubygems.org/gems/deltacloud-core">deltacloud-core</a> Ruby gem:</p>
-
- <pre><code># gem install deltacloud-core
</code></pre>
-
- <p>RPM package will be available soon.</p>
-
- <h2 id="h2">Launch the server</h2>
-
- <p>The server is launched with the <code>deltacloudd</code> command and pass it the name
- of the driver you want to use:</p>
-
- <pre><code>$ deltacloudd -i mock
</code></pre>
-
- <p>This will start a webserver running the mock driver on
- <code>http://localhost:3001/api</code>; you can simply browse to that URL to get a
- pretty view of the objects the driver deals with.</p>
-
- <h2 id="h3">Dynamic driver switching</h2>
-
- <p>The driver specified with the <code>-i</code> switch when <code>deltacloudd</code> is launched is
- the default driver. Clients can switch drivers for any request. The list of
- drivers supported by the server can be obtained from the <code>drivers</code>
- collection.</p>
+ <p>Deltacloud provides drivers for a <a href="drivers.html#providers">growing number</a> of popular
+ IaaS cloud providers. This page contains notes pertinent to specific cloud provider drivers, such
+ as the <a href="drivers.html#credentials">credentials</a> that should be used for a given cloud provider.
+ Furthermore the information here outlines the mechanism through which any API call sent by a
+ given client to a Deltacloud server instance may be routed to a specific driver, regardless
+ of the 'default' driver that the Deltacloud server was invoked for.</p>
+
+ <hr />
+
+ <h2 id="h1">Dynamic driver switching</h2>
+
+ <p>When the Deltacloud server is started it is passed a parameter
+ that specifies the <strong>default</strong> driver to be used for API operations:</p>
+
+ <pre><code>$ deltacloudd -i ec2
</code></pre>
+
+ <p>The above for example starts the Detlacloud server with the Amazon EC2 driver. Whilst
+ it is possible to start a number of Deltacloud server instances for each cloud provider
+ that you wish to connect to (e.g., on different ports), a mechanism is provided with which
+ to instruct the server to use a specific driver, regardless of the current default. The
+ Deltacloud API <strong>drivers</strong> colletion (e.g. GET /api/drivers) provides a list of all currently
+ supported cloud provider drivers.</p>
<p>Some drivers also support the notion of a <em>provider</em>. Changing the provider
makes it possible to use the same driver against different instances of a
cloud, for example different regions in EC2 or different installations of
RHEV-M. The possible range of values for the provider is driver-specific,
- and listed below for each driver.</p>
+ and listed in the notes for each driver below.</p>
<p>The driver and provider can be selected in one of two ways:</p>
@@ -168,12 +154,14 @@
<li>Through the matrix request parameters <code>driver</code> and <code>provider</code> in the
<code>api</code> component of the server's URL. For example, requesting
<code>http://localhost:3001/api;driver=ec2;provider=eu-west-1</code> has the same
- effect as using the two request headers mentioned above.</li>
+ effect as using the two request headers in the example above.</li>
</ol>
- <h2 id="h4">Notes on specific drivers</h2>
- <h3>Compute Drivers</h3>
+ <hr />
+
+ <h2 id="h2">Driver functionality and Credentials</h2>
+ <h3>Compute Driver Functionality</h3>
<table id='providers'>
<tr>
<th class='emptycell'> </th>
@@ -356,17 +344,17 @@
<td class="supported">yes</td>
</tr>
</table>
- <h3>Storage Drivers</h3>
+ <h3>Storage Driver Functionality</h3>
<table id='providers'>
<tr>
<th class='emptycell'> </th>
<th>
<strong>Create</strong>
- new containers
+ new buckets
</th>
<th>
<strong>Update/delete</strong>
- containers
+ buckets
</th>
<th>
<strong>Create</strong>
@@ -442,30 +430,271 @@
<td class="not-supported">TBD</td>
</tr>
</table>
+ <p>
+ Deltacloud uses basic HTTP
+ <a href='api.html#h1_3'>
+ authentication
+ </a>
+ to receive credentials from the
+ client and passes them through to the backend cloud it is talking to. The
+ credentials always consist of a username and password, and are never
+ stored on the server. The exact credentials for logging into the server,
+ and where you find them, depends on the backend cloud that the server is
+ talking to.
+ </p>
+ <a name='credentials'></a>
+ <p>
+ The following table gives details about the credentials that must be
+ provided for each of the supported clouds. The entry from
+ the Driver column needs to be passed as the
+ <tt>
+ -i
+ </tt>
+ option to the
+ <tt>
+ deltacloudd
+ </tt>
+ server daemon. Note that some of the drivers require additional information, e.g.,
+ API endpoint URL's, be passed through environment variables, as addressed in the
+ <a href='drivers.html#specific_driver_notes'>
+ Notes
+ </a>
+ for Specific Drivers section below.
+ </p>
+ <h3>Cloud provider credentials</h3>
+ <table id='providers'>
+ <tr>
+ <th>
+ <strong>Cloud</strong>
+ </th>
+ <th>
+ <strong>Driver</strong>
+ </th>
+ <th>
+ <strong>Username</strong>
+ </th>
+ <th>
+ <strong>Password</strong>
+ </th>
+ <th>
+ <strong>Notes</strong>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <strong>mock</strong>
+ </td>
+ <td>
+ <tt>mock</tt>
+ </td>
+ <td>
+ <tt>
+ mockuser
+ </tt>
+ </td>
+ <td>
+ <tt>
+ mockpassword
+ </tt>
+ </td>
+ <td>
+ The mock driver doesn't talk to any cloud; it just pretends to be a cloud
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Amazon EC2/S3</strong>
+ </td>
+ <td>
+ <tt>ec2</tt>
+ </td>
+ <td>
+ Access Key ID
+ </td>
+ <td>
+ Secret Access Key
+ </td>
+ <td>
+ This information can be found on the
+ <a href='http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key'>Security Credentials</a>
+ page in your AWS account
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Eucalyptus</strong>
+ </td>
+ <td>
+ <tt>eucalyptus</tt>
+ </td>
+ <td>
+ Access Key ID
+ </td>
+ <td>
+ Secret Access Key
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ <strong>GoGrid</strong>
+ </td>
+ <td>
+ <tt>gogrid</tt>
+ </td>
+ <td>
+ API Key
+ </td>
+ <td>
+ Shared Secret
+ </td>
+ <td>
+ Go to
+ <tt>My Account > API Keys</tt>
+ for
+ <a href='https://my.gogrid.com/gogrid/com.servepath.gogrid.GoGrid/index.html'>your account</a>
+ and click on the key you want to use to find the shared secret.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>IBM SBC</strong>
+ </td>
+ <td>
+ <tt>sbc</tt>
+ </td>
+ <td>
+ Username
+ </td>
+ <td>
+ Password
+ </td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Microsoft Azure (Storage Account only)</strong>
+ </td>
+ <td>
+ <tt>azure</tt>
+ </td>
+ <td>
+ Public Storage Account Name
+ </td>
+ <td>
+ Primary Access Key
+ </td>
+ <td>
+ The Storage Account Name is chosen when you create the service (e.g. name in http://name.blob.core.windows.net/). This and the access key are available from the service control panel.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>OpenNebula</strong>
+ </td>
+ <td>
+ <tt>opennebula</tt>
+ </td>
+ <td>
+ OpenNebula user
+ </td>
+ <td>
+ OpenNebula password
+ </td>
+ <td>
+ Set the environment variable
+ <tt>OCCI_URL</tt>
+ to the address on which OpenNebula's OCCI server is listening.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Rackspace Cloud Servers/Cloud Files</strong>
+ </td>
+ <td>
+ <tt>rackspace</tt>
+ </td>
+ <td>
+ Rackspace user name
+ </td>
+ <td>
+ API Key
+ </td>
+ <td>
+ Obtain the key from the
+ <a href='https://manage.rackspacecloud.com/APIAccess.do'>API Access</a>
+ page in your control panel
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>RHEV-M</strong>
+ </td>
+ <td>
+ <tt>rhevm</tt>
+ </td>
+ <td>
+ <a href='http://markmc.fedorapeople.org/rhevm-api/en-US/html/chap-REST_API_Guide-Authentication.html'>RHEV-M user name plus Windows domain</a>
+ , e.g.,
+ <tt>admin@rhevm.example.com</tt>
+ </td>
+ <td>
+ RHEV-M password
+ </td>
+ <td>
+ Set environment variable
+ <tt>API_PROVIDER</tt>
+ to the URL of the RHEV-M REST API endpoint.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Rimuhosting</strong>
+ </td>
+ <td>
+ <tt>rimuhosting</tt>
+ </td>
+ <td>not used (?)</td>
+ <td>API Key</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>
+ <strong>Terremark</strong>
+ </td>
+ <td>
+ <tt>terremark</tt>
+ </td>
+ <td>
+ Username
+ </td>
+ <td>
+ Password
+ </td>
+ <td></td>
+ </tr>
+ </table>
- <h3 id="h4_1">EC2 Driver</h3>
+ <p><a name="providers">.</a></p>
- <p>For the Amazon EC2 you need to install the
- <a href="https://github.com/appoxy/aws">aws</a> Ruby gem:</p>
+ <hr />
- <pre><code># gem install aws
</code></pre>
+ <p><a name="specific_driver_notes"> .</a></p>
- <p>When using the driver for Amazon EC2, the credentials passed in
- response to the HTTP 401 authentication challenge should be your
- <em>access_key</em> and <em>secret_access_key</em></p>
+ <h2 id="h3">Notes on specific drivers</h2>
- <p>These credentials may be found on the <a href="http://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key">Access Identifiers</a>
- page at Amazon AWS.</p>
+ <h3 id="h3_1">EC2 Driver</h3>
<p>The providers for the EC2 driver correspond to AWS's regions, and currently
are <code>us-east-1</code>, <code>us-east-1</code>, <code>eu-west-1</code>, <code>ap-southeast-1</code>.</p>
- <h3 id="h4_2">Eucalyptus Driver</h3>
+ <hr />
+
+ <h3 id="h3_2">Eucalyptus Driver</h3>
- <p>The Eucalyptus driver is based on the EC2 driver, and therefore also
- requires the <code>aws</code> gem.</p>
+ <p>The Eucalyptus driver is based on the EC2 driver.</p>
<p>The driver allows selecting the Eucalyptus installation by setting a
provider in the format</p>
@@ -478,7 +707,9 @@
<pre><code>X-Deltacloud-Driver: eucalyptus
X-Deltacloud-Provider: ec2=192.168.1.1:8773;s3=192.168.1.2:8773
</code></pre>
- <h3 id="h4_3">RHEV-M Driver</h3>
+ <hr />
+
+ <h3 id="h3_3">RHEV-M Driver</h3>
<p>The RHEV-M driver needs to be installed on a Windows machine which has the
RHEV-M Powershell API installed and configured. Assuming the directory
@@ -491,18 +722,24 @@
the RHEVM.dll.config file which is referenced from the profile.ps1
file located in My Documents/WindowsPowershell directory</p>
- <h3 id="h4_4">Rackspace Driver</h3>
+ <hr />
+
+ <h3 id="h3_4">Rackspace Driver</h3>
<p>When using the Rackspace-cloud driver (Rackspace cloud used to be called
"Mosso") - the password in a HTTP 401 challenge should be your API key, NOT
- your rackspace account password. (you can get the API-key, or generate a
- new one, from the rackspace console).</p>
+ your rackspace account password. You can get the API-key, or generate a
+ new one, from the rackspace console.</p>
- <h3 id="h4_5">RimuHosting</h3>
+ <hr />
+
+ <h3 id="h3_5">RimuHosting</h3>
<p>Further details coming soon.</p>
- <h3 id="h4_6">OpenNebula</h3>
+ <hr />
+
+ <h3 id="h3_6">OpenNebula</h3>
<p>When using the <a href="http://www.opennebula.org/">OpenNebula</a> driver, the
credentials passed in response to the HTTP 401 authentication challenge
@@ -511,7 +748,9 @@
<p>The address, on which the OCCI server is listening, needs to be defined in
an environment variable called OCCI_URL.</p>
- <h3 id="h4_7">IBM Smartcloud Driver</h3>
+ <hr />
+
+ <h3 id="h3_7">IBM Smartcloud Driver</h3>
<p>When using the IBM SmartCloud driver, the credentials passed in response to
the HTTP 401 authentication challenge should be your IBM SmartCloud
Modified: incubator/deltacloud/trunk/site/output/libdeltacloud.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/libdeltacloud.html?rev=1185125&r1=1185124&r2=1185125&view=diff
==============================================================================
--- incubator/deltacloud/trunk/site/output/libdeltacloud.html (original)
+++ incubator/deltacloud/trunk/site/output/libdeltacloud.html Mon Oct 17 12:25:27 2011
@@ -31,11 +31,14 @@
<a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
</li>
<li>
- <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+ <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
</li>
<li>
<a class='active' href='./documentation.html' title='Project documentation'>Documentation</a>
</li>
+ <li>
+ <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+ </li>
</ul>
</div>
</div>
@@ -44,7 +47,7 @@
<ul class='l1'>
<li>
<a class='inactive' href='documentation.html'>
- Overview
+ Installation
</a>
</li>
<li>
@@ -58,11 +61,6 @@
</a>
</li>
<li>
- <a class='inactive' href='framework.html'>
- Framework
- </a>
- </li>
- <li>
<a class='inactive' href='client-ruby.html'>
Ruby Client
</a>
Modified: incubator/deltacloud/trunk/site/output/roadmap.html
URL: http://svn.apache.org/viewvc/incubator/deltacloud/trunk/site/output/roadmap.html?rev=1185125&r1=1185124&r2=1185125&view=diff
==============================================================================
--- incubator/deltacloud/trunk/site/output/roadmap.html (original)
+++ incubator/deltacloud/trunk/site/output/roadmap.html Mon Oct 17 12:25:27 2011
@@ -31,11 +31,14 @@
<a class='inactive' href='./download.html' title='Get the latest releases'>Download</a>
</li>
<li>
- <a class='inactive' href='./contribute.html' title='Information about design/development process'>Contribute</a>
+ <a class='inactive' href='./developers.html' title='Information for developers'>Developers</a>
</li>
<li>
<a class='inactive' href='./documentation.html' title='Project documentation'>Documentation</a>
</li>
+ <li>
+ <a class='inactive' href='./contact.html' title='Contact us!'>Contact</a>
+ </li>
</ul>
</div>
</div>
@@ -59,9 +62,9 @@
in order of priority.</p>
<p>If you have anything you'd like to see added to the roadmap, or think that
- some items should receive more attention, please let us know on the
- <a href="/contribute.html">mailing list</a>. Of course, the quickest way to get anything into
- Deltacloud is to <a href="/contribute.html">send us patches</a> — we will of course take patches
+ some items should receive more attention, please <a href="contact.html">let us know</a>.
+ Of course, the quickest way to get anything into
+ Deltacloud is to send us patches; we will of course take patches
for anything, regardless of whether they adress items on the roadmap or
anything else.</p>