Google Git
Sign in
apache / deltacloud / 64c62c2437767af247a579a6c3c718e2641c1796 / . / site / output / assets / img / documentation.html
blob: d07d9b2e78bd685493fd43e043c07195dd3c199a [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html><head>
<title>
Deltacloud - Documentation
</title>
<meta content="" name="keywords">
<meta content="" name="description">
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
<link href="http://deltacloud.apache.org/styles/favicon.ico" rel="shortcut icon" type="image/x-icon">
<link href="documentation_files/default.css" rel="StyleSheet" title="Main style" type="text/css">
<link href="documentation_files/default-debug.css" rel="Alternate StyleSheet" title="Debug main style" type="text/css">
</head>
<body><div style="background: red"><h1>2015/07/20 - Apache Deltacloud has been retired. </h1><h2>For more information, please explore the <a href="http://attic.apache.org/">Attic</a>. </h2></div>
<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="http://deltacloud.apache.org/index.html" title="Deltacloud Home">Home</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/download.html" title="Get the latest releases">Download</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/developers.html" title="Information for developers">Developers</a>
</li>
<li>
<a class="active" href="http://deltacloud.apache.org/documentation.html" title="Project documentation">Documentation</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/contact.html" title="Contact us!">Contact</a>
</li>
</ul>
</div>
</div>
<div id="subnavigation">
<div class="container" id="submenu">
<ul class="l1">
<li>
<a class="active" href="http://deltacloud.apache.org/documentation.html">
Installation
</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/api.html">
REST API
</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/drivers.html">
Drivers
</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/client-ruby.html">
Ruby Client
</a>
</li>
<li>
<a class="inactive" href="http://deltacloud.apache.org/libdeltacloud.html">
Libdeltacloud
</a>
</li>
</ul>
</div>
</div>
<div id="frontpageHeader"></div>
<div id="main">
<div class="container" id="content-deltacloud">
<h1>Documentation</h1>
<p>The Deltacloud documentation is divided into the following parts:</p>
<ul>
<li>
<a href="http://deltacloud.apache.org/documentation.html">
Installation, dependencies and quick-start (this page)
</a>
</li>
<li>
<a href="http://deltacloud.apache.org/api.html">
REST API definition
</a>
</li>
<li>
<a href="http://deltacloud.apache.org/drivers.html">
Information about currently supported drivers
</a>
</li>
<li>
<a href="http://deltacloud.apache.org/client-ruby.html">
The Deltacloud Ruby client
</a>
</li>
<li>
<a href="http://deltacloud.apache.org/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/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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/drivers.html#credentials">
credentials
</a>
when you invoke an operation that requires
<a href="http://deltacloud.apache.org/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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/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>
<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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/drivers.html#credentials">
here.
</a>
</li>
</ul>
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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/drivers.html#credentials">
credentials
</a>
for access to the back-end cloud provider (Amazon EC2 in this case).
To
<a href="http://deltacloud.apache.org/api.html#create_instance">
create a new instance
</a>
from the
<a href="http://deltacloud.apache.org/api.html#h3_3">
image
</a>
with id 'ami-f51aff9c', in
<a href="http://deltacloud.apache.org/api.html#h3_1">
realm
</a>
'us-east-1c', with the
<a href="http://deltacloud.apache.org/api.html#h3_2">
hardware profile
</a>
'c1.medium', in
<a href="http://deltacloud.apache.org/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="http://deltacloud.apache.org/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="http://deltacloud.apache.org/api.html#create_blob">
create a blob
</a>
called 'my_new_blob' within the
<a href="http://deltacloud.apache.org/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="http://deltacloud.apache.org/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">
<div class="container">
<p>
<a href="http://www.apache.org/">
<img alt="Apache Software Foundation Logo" src="documentation_files/asf_logo_wide.png">
</a>
</p>
<p id="disclaimer">
Apache Deltacloud is a top-level project at the Apache
Software Foundation, having graduated from the ASF Incubator
in October 2011. Through a collaborative and meritocratic
development process, Apache projects deliver enterprise-grade,
freely available software products that attract large communities of users.
</p>
</div>
</div>
<script type="text/javascript">
var pkBaseURL = (("https:" == document.location.protocol) ? "https://stats.salasaga.org/aeolus/piwik/" : "http://stats.salasaga.org/aeolus/piwik/");
document.write(unescape("%3Cscript src='" + pkBaseURL + "piwik.js' type='text/javascript'%3E%3C/script%3E"));
</script><script src="documentation_files/piwik.js" type="text/javascript"></script>
<script type="text/javascript">
//<![CDATA[
try {
var piwikTracker = Piwik.getTracker(pkBaseURL + "piwik.php", 2);
piwikTracker.trackPageView();
piwikTracker.enableLinkTracking();
} catch( err ) {}
//]]>
</script>
<noscript>
<p>
<img alt='' src='http://stats.salasaga.org/aeolus/piwik/piwik.php?idsite=2' style='border:0' />
</p>
</noscript>
</body></html>