Documentation
The Deltacloud documentation is divided into the following parts:
- Installation, dependencies and quick-start (this page)
- REST API definition
- Information about currently supported drivers
- The Deltacloud Ruby client
- The libdeltacloud C library
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-coreInstallation 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:- ruby and ruby-devel,
- gem (RubyGems),
- gcc-c++,
- libxml2 and libxml2-devel,
- libxslt and libxslt-devel,
- rake
ruby and ruby-devel
You need to install ruby. You can check to see if you already have a ruby installation by typing:$ ruby -vruby 1.8.7 (2010-08-16 patchlevel 302) [i686-linux]sudo yum install ruby
sudo yum install ruby-develsudo apt-get install ruby
sudo apt-get install ruby-develgem (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 rubygemsgcc-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-develrake
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$ deltacloudd -l
Available drivers:
* condor
* vsphere
* opennebula
* eucalyptus
* rhevm
* sbc
* azure
* gogrid
* mock
* rackspace
* rimuhosting
* terremark
* ec2The '-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$ deltacloudd -i ec2 -P 5000 -r 192.168.10.200The 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:5000require '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$ sudo gem install deltacloud-client$ deltacloudc collection operation [options]- collection refers to the Deltacloud object collections, such as Instances, Images, Buckets, Realms etc, as described in greater detail in the REST API
- operation 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.
- options are listed by invoking deltacloudc -h One important option is -u, with which you specify the API_URL where the Deltacloud server is running. The API_URL takes the form http://[user]:[password]@[api_url]:[port]/[api] (examples follow). Alternatively, rather than having to supply the API_URL for every invocation of deltacloudc 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 here.
$ deltacloudc -l -u http://mockuser:mockpassword@localhost:3001/api$ deltacloudc images index -u http://mockuser:mockpassword@localhost:3001/api$ deltacloudc buckets -l -u http://mockuser:mockpassword@localhost:3001/api$ deltacloudc blob create -i 'my_new_blob' -b 'bucket1' -f /home/marios/file.txtOther 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"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"curl -X DELETE
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/firewalls/develgroup?format=xmlcurl -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=xmlcurl -iv -X HEAD
--user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
http://localhost:3001/api/buckets/mybucket/my_new_blob?format=xml