Documentation

The Deltacloud documentation is divided into the following parts:




Install Deltacloud

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.

Installation of Deltacloud itself

Once you've setup all the dependencies listed below, installing Deltacloud is as easy as typing: 

$ sudo gem install deltacloud-core
And thats it! The gem install 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 Apache website.


Installation dependencies

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:

More info on getting these follows:

ruby and ruby-devel

You need to install ruby. You can check to see if you already have a ruby installation by typing: 

$ ruby -v
If you see something that looks like the following: 

ruby 1.8.7 (2010-08-16 patchlevel 302) [i686-linux]
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: 

sudo yum install ruby
sudo yum install ruby-devel
OR 

sudo apt-get install ruby
sudo apt-get install ruby-devel

gem (RubyGems)

Deltacloud relies on a number of ruby gems so you also need to install RubyGems. As with ruby, you can check if you already have the gem executable installed by typing gem -v . Again, your package manager can help with the installation: 

$ sudo yum install rubygems

gcc-c++, libxml2, libxml2-devel, libxslt, libxslt-devel

These are required to build RubyGems that have C extensions. Again, typically the easiest way to get these is with you package manager: 

$ sudo yum install gcc-c++
$ sudo yum install libxml libxml2-devel
$ sudo yum install libxslt libxslt-devel

rake

Rake is Ruby's Make and is itself a ruby gem. Once you have RubyGems installed you can get rake with: 

$ sudo gem install rake



"Hello Deltacloud!", quick-start guide

This guide assumes a linux environment. Some of the Deltacloud developers are running recent versions of Fedora. 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 let us know, we'd love to hear from you!

Running the Deltacloud server

After you succesfully install Deltacloud, you can start the server by typing deltacloudd -i provider_id. The provider_id 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: 

deltacloudd -i mock
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 all available provider_ids that can be used with the deltacloudd executable. 

$ deltacloudd -l


Available drivers:
* condor
* vsphere
* opennebula
* eucalyptus
* rhevm
* sbc
* azure
* gogrid
* mock
* rackspace
* rimuhosting
* terremark
* ec2
After you start the server, the Deltacloud HTML interface is available at http://localhost:3001/api - open this address in your web browser. If you want to see XML output from the server in the browser, append format=xml to each URL. On Webkit based browsers like Safari, you might need to instruct the server explicitly to return HTML Do this by appending format=html to each URL. Your browser will prompt you for credentials when you invoke an operation that requires authentication.

The '-h' flag will list all available options for deltacloudd. For example, to start the Deltacloud server with the Rackspace driver on port 10000 you can use: 

$ deltacloudd -i rackspace -P 10000
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: 

$ deltacloudd -i ec2 -P 5000 -r 192.168.10.200
This will make the Deltacloud server available at the address http://192.168.10.200:5000/api.




The Deltacloud ruby client

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 192.168.10.244:5000 

require 'deltacloud'


api_url      = 'http://192.168.10.244:5000/api'
api_name     = 'TK2PJCAN9R1HKG2FK24Z'
api_password = 'aLe27rZlRhlBcVoQbL4JsVtaNga12vEL9d9kS5CA'


client = DeltaCloud.new( api_name, api_password, api_url )


# get a list of currently running instances (virtual machines)
client.instances.each do |instance|
 puts instance.name
end



other work with client here
More comprehensive information on using the Deltacloud ruby client in this way can be found in the client documentation. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing: 

$ sudo gem install deltacloud-client
Installing the Deltacloud client also gives you the deltacloudc command line tool. This executable makes use of the Deltacloud client library to speak to the Deltacloud server using the REST API. 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: 

$ deltacloudc collection operation [options]
The following examples assume that the Deltacloud server is running on your local machine port 3001 (the deltacloudd server daemon defaults to 'localhost:3001') and was started with the 'mock' provider (i.e. deltacloudd -i mock ). To list all collections available in the current driver: 

$ deltacloudc -l -u http://mockuser:mockpassword@localhost:3001/api
To get a list of all images: 

$ deltacloudc images index -u http://mockuser:mockpassword@localhost:3001/api
To list all operations for the buckets collection: 

$ deltacloudc buckets -l -u http://mockuser:mockpassword@localhost:3001/api
To create a new blob in the bucket called 'bucket1': 

$ deltacloudc blob create -i 'my_new_blob' -b 'bucket1' -f /home/marios/file.txt



Other HTTP clients - cURL

As interaction with the Deltacloud server is via HTTP calls, you can use any HTTP client to talk to it using the Deltacloud REST API. One popular command line tool available on most modern linux distributions is cURL. 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., deltacloudd -i ec2 ). To get a listing of all images available in the back-end cloud: 

curl  --user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
"http://localhost:3001/api/images?format=xml"
The cURL --user option is used to specify the username:password credentials for access to the back-end cloud provider (Amazon EC2 in this case). To create a new instance from the image with id 'ami-f51aff9c', in realm 'us-east-1c', with the hardware profile 'c1.medium', in firewall 'default': 

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"
To delete a firewall called 'develgroup': 

curl -X DELETE
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/firewalls/develgroup?format=xml
To create a blob called 'my_new_blob' within the bucket 'mybucket' from a local file with HTTP PUT specifying its content type and setting some some metadata key:value pairs: 

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
To retrieve blob metadata for the blob called 'my_new_blob': 

curl -iv -X HEAD
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml
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).