Return-Path: X-Original-To: apmail-deltacloud-commits-archive@www.apache.org Delivered-To: apmail-deltacloud-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 7F64FDB5B for ; Wed, 6 Mar 2013 22:09:19 +0000 (UTC) Received: (qmail 20814 invoked by uid 500); 6 Mar 2013 22:09:19 -0000 Delivered-To: apmail-deltacloud-commits-archive@deltacloud.apache.org Received: (qmail 20772 invoked by uid 500); 6 Mar 2013 22:09:19 -0000 Mailing-List: contact commits-help@deltacloud.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@deltacloud.apache.org Delivered-To: mailing list commits@deltacloud.apache.org Received: (qmail 20726 invoked by uid 99); 6 Mar 2013 22:09:19 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 06 Mar 2013 22:09:19 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id C06F4830E9C; Wed, 6 Mar 2013 22:09:18 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: marios@apache.org To: commits@deltacloud.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [3/5] SITE: addresses DTACLOUD-478, DTACLOUD-479 and removes crud Message-Id: <20130306220918.C06F4830E9C@tyr.zones.apache.org> Date: Wed, 6 Mar 2013 22:09:18 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/deltacloud/blob/c7f4d022/site/output/#storage-snapshots.md# ---------------------------------------------------------------------- diff --git a/site/output/#storage-snapshots.md# b/site/output/#storage-snapshots.md# deleted file mode 100644 index b7bf07c..0000000 --- a/site/output/#storage-snapshots.md# +++ /dev/null @@ -1,185 +0,0 @@ ---- -site_name: Deltacloud API -title: Storage snapshots ---- - -
- -
-× -This section is currently being updated. -
- -
-
- -

Storage snapshots

- -

-A storage_snapshot captures the point-in-time state of a storage_volume. Each snapshot has a created timestamp, and a storage_volume attribute referring to the volume from which the snapshot was made. -

- -

Get a list of all storage snapshots

- -

-To list all available storage snapshots use call GET /api/storage_snapshots. For Amazon EC2 this list includes any snapshots that are available to the requesting client account, including those that may not have been created by that account. As this list is very long the example below shows only part of the response: -

- -
-
- - - -
-
- -

-Example request: -

- -
-GET /api/storage_snapshots?format=xml HTTP/1.1
-Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
-User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
-Host: localhost:3001
-Accept: */*
-
- -

Server response:

- -
-HTTP/1.1 200 OK
-Content-Type: application/xml
-Date: Thu, 28 Jul 2011 22:08:36 GMT
-Content-Length: 156897
-
-<?xml version='1.0' encoding='utf-8' ?>
-<storage_snapshots>
-  <storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-45b8d024' id='snap-45b8d024'>
-    <created>Thu Jul 28 21:54:19 UTC 2011</created>
-    <storage_volume href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' id='vol-0bc0de60'></storage_volume>
-  </storage_snapshot>
-  <storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-d5a1c9b4' id='snap-d5a1c9b4'>
-    <created>Thu Jul 28 21:46:12 UTC 2011</created>
-    <storage_volume href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' id='vol-99fbe5f2'></storage_volume>
-  </storage_snapshot>
-  <storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-dda6cebc' id='snap-dda6cebc'>
-    <created>Thu Jul 28 21:51:55 UTC 2011</created>
-    <storage_volume href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' id='vol-99fbe5f2'></storage_volume>
-  </storage_snapshot>
-  <storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-d010f6b9' id='snap-d010f6b9'>
-    <created>Mon Oct 20 18:23:59 UTC 2008</created>
-    <storage_volume href='http://localhost:3001/api/storage_volumes/vol-351efb5c' id='vol-351efb5c'></storage_volume>
-  </storage_snapshot>
-  <storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-a310f6ca' id='snap-a310f6ca'>
-    <created>Mon Oct 20 18:25:53 UTC 2008</created>
-    <storage_volume href='http://localhost:3001/api/storage_volumes/vol-001efb69' id='vol-001efb69'></storage_volume>
-  </storage_snapshot>
-  (...)
-</storage_snapshots>
-
- -

Get the details for a storage snaphsot

- -

-To get all details for a specified storage snapshot, as shown below, use call GET /api/storage_snapshots/:id. -

- -

Example request:

- -
-GET /api/storage_snapshots/snap-45b8d024?format=xml HTTP/1.1
-Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
-User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
-Host: localhost:3001
-Accept: */*
-
- -

Server response:

- -
-HTTP/1.1 200 OK
-Content-Type: application/xml
-Date: Thu, 28 Jul 2011 22:08:36 GMT
-Content-Length: 329
-
-<?xml version='1.0' encoding='utf-8' ?>
-<storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-45b8d024' id='snap-45b8d024'>
-  <created>Thu Jul 28 21:54:19 UTC 2011</created>
-  <storage_volume href='http://localhost:3001/api/storage_volumes/vol-0bc0de60' id='vol-0bc0de60'></storage_volume>
-</storage_snapshot>
-
- -

Create a new storage snapshot

- -

-To create a new storage_snapshot use call POST /api/storage_snapshots. Clients must specify the storage_volume from which the snapshot is created by supplying the volume_id parameter. The Deltacloud server responds with HTTP 201 Created after a succesful operation and provides details of the new storage_snapshot. Clients may specify operation parameters as multipart/form-data, or as application/x-www-form-urlencoded data: -

- -

Example request:

- -
-POST /api/storage_snapshots?format=xml HTTP/1.1
-Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
-User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
-Host: localhost:3001
-Accept: */*
-Content-Length: 22
-Content-Type: application/x-www-form-urlencoded
-
-volume_id=vol-99fbe5f2
-
- -

Server response:

- -
-HTTP/1.1 201 Created
-Date: Thu, 28 Jul 2011 21:46:48 GMT
-Content-Length: 329
-
-<?xml version='1.0' encoding='utf-8' ?>
-<storage_snapshot href='http://localhost:3001/api/storage_snapshots/snap-d5a1c9b4' id='snap-d5a1c9b4'>
-  <created>Thu Jul 28 21:46:12 UTC 2011</created>
-  <storage_volume href='http://localhost:3001/api/storage_volumes/vol-99fbe5f2' id='vol-99fbe5f2'></storage_volume>
-</storage_snapshot>
-
- -

Delete a storage snapshot

- -

-To delete the specified storage_snapshot use call DELETE /api/storage_snapshots/:id. The operation returns a HTTP 204 No Content after a succesful operation: -

- -

Example request:

- -
-DELETE /api/storage_snapshots/snap-dda6cebc?format=xml HTTP/1.1
-Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
-User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
-Host: localhost:3001
-Accept: */*
-
- -

Server response:

- -
-HTTP/1.1 204 No Content
-Date: Thu, 28 Jul 2011 22:26:07 GMT
-
- -Blob storage - -
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/c7f4d022/site/output/#usage.md# ---------------------------------------------------------------------- diff --git a/site/output/#usage.md# b/site/output/#usage.md# deleted file mode 100644 index 6921528..0000000 --- a/site/output/#usage.md# +++ /dev/null @@ -1,135 +0,0 @@ ---- -site_name: Deltacloud API -title: Usage ---- -
- -

Using API

- -

Creating an instance

- -

Switching a driver

- -

Clients

-Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server. - -

The Deltacloud Ruby client

-You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing: - -
$ sudo gem install deltacloud-client
- -

The Deltacloud client consists of a Ruby library (packaged as a ruby gem) which you can use to interact with the Deltacloud server and control your cloud infrastructure across cloud providers.

- -

To use the client, you must require deltacloud:

- -
require 'deltacloud'
- -

Connect to a Deltacloud provider using these commands:

- -
-require 'deltacloud'
-
-api_url      = 'http://localhost:3001/api'
-api_name     = 'mockuser'
-api_password = 'mockpassword'
-
-client = DeltaCloud.new( api_name, api_password, api_url )
-
-# work with client here
-
- -

In addition to creating a client, operations may occur within a block included on the initialization.

- -
-DeltaCloud.new( api_name, api_password, api_url ) do |client|
-  # work with client here
-end
-
- -

In case of a failure, every underlying HTTP transport exceptions will be thrown away and returned back to the caller.

- -Work with the Ruby client - -
-
- -

HTTP clients - cURL

- -

-Basically, you interact with the Deltacloud server via HTTP calls, so you can use any HTTP client to talk to Deltacloud using the REST API. -

- -

-cURL is a popular command line tool available on most modern linux distributions. See the following examples to learn how to use cURL to interact with Deltacloud. There is an assumption that the Deltacloud server is running on locahost:3001, and was started with the 'ec2' driver (i.e., deltacloudd -i ec2 ). -

- -

-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).

- -

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"
-
- -

Delete a firewall called 'develgroup':

- -
-curl -X DELETE
---user "pGbAJ1TsVg5PKs3BK27O:dPs47ralgBlldqYNbLg3scthsg4g8v0L9d6Mb5DK"
-http://localhost:3001/api/firewalls/develgroup?format=xml
-
- -

-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
-
- -

-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
-
- -

-The '-iv' flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body). -

- -

Libdeltacloud Client (C library)

-

-Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the deltacloud API. -

- -Get the source code: -
-$ git clone git://git.fedorahosted.org/deltacloud/libdeltacloud.git
-
- -

-Full documentation for the library contains the list of data structures, all documented files with brief descriptions and also the exapmles of working with libdeltacloud. -

- http://git-wip-us.apache.org/repos/asf/deltacloud/blob/c7f4d022/site/output/#write-new-driver.md# ---------------------------------------------------------------------- diff --git a/site/output/#write-new-driver.md# b/site/output/#write-new-driver.md# deleted file mode 100644 index 5d54cb3..0000000 --- a/site/output/#write-new-driver.md# +++ /dev/null @@ -1,140 +0,0 @@ ---- -site_name: Deltacloud API -title: Write New Provider Driver ---- - -
- -

Writing a provider driver

- -

The deltacloud drivers are stored in deltacloud/server/lib/deltacloud/drivers

To ad a driver for hypotetical Foo cloud, add a directory into /drivers/ and then a file for a driver itself: - -
deltacloud/server/lib/deltacloud/drivers/foo/foo_driver.rb
- -

You need to define a class Deltacloud::Drivers::Foo::FooDriver to this file. The class must be a subclass of the Deltacloud::BaseDriver. -

- -

Set up which collections the provider for you are writing the driver supports - e.g. images, instances, keys, buckets/blobs (storage), etc.:

- -
-def supported_collections
-  DEFAULT_COLLECTIONS + [ :buckets ] - [ :storage_snapshots, :storage_volumes ]
-end
-
- -

This declares that the driver supports the DEFAULT_COLLECTIONS (defined in deltacloud/server/lib/drivers.rb) except storage_snapshots and storage_volumes and also the buckets collection. A storage only cloud provider driver would support only the buckets colletion.

- -

-Then, you can define the methods for each collection that your driver supports. The methods, as well as the routes to them, are defined in deltacloud/server/lib/deltacloud/server.rb. In general, you can look at the existing drivers to have the idea of how to implement any specific method. -

- -

-You should consider how the driver will be communicating with the cloud provider. Many of the existing drivers use external ruby gems for this purpose: for example, the ec2 driver uses the aws gem, the rackspace driver uses the cloudfiles and cloudservers gems. However, other drivers implement their own clients 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 _driver.rb file, whilst others also define a provider_client.rb file. It is entirely up to you, whether you write your own client or use an existing one. -

- -

Thus, your driver for the cloud provider foo may look like:

- -
-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(credentials)
-      client = FooLib::Service.new({:user => credentials.user,
-                                    :pass => credentials.password })
-    end
-
-end
-        end
-      end
-    end
-
- -

-An important method for drivers that implement the instances collection is instance_states. This method represents the finite-state-machine for instances which varies across cloud providers. 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. For example: -

- -
-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
-
- -

-The definiton of .to and on. etc is defined in /deltacloud/server/lib/deltacloud/state_machine.rb. -

- -

Valid states are:

- -
    -
  • :begin
    • -
  • :pending
    • -
  • :running
    • -
  • :shutting_down
    • -
  • :stopped
    • -
  • :end
    • -
- -

The instance is located in the:begin state before being created. Immediately after being destroyed the instance is removed to the :end state.

- -

Valid transition actions are:

- -
    -
  • :stop
    • -
  • :start
    • -
  • :reboot
    • -
- -

The action :automatically may be used to indicate a tranisition that may occur without an action being triggered (see the example above).

- -

You can implement some other methods according to the collections you will be supporting:

- -
    -
  • hardware_profiles(credentials, opts=nil)
    • -
  • images(credentials, opts=nil)
    • -
  • realms(credentials, opts=nil)
    • -
  • instances(credentials, opts=nil)
    • -
  • create_instance(credentials, image_id, opts)
    • -
  • reboot_instance(credentials, id)
    • -
  • stop_instance(credentials, id)
    • -
  • destroy_instance(credentials, id)
    • -
- -

-The hardware_profiles(...) method should return an array of HardwareProfile objects. The opts hash, if present, must be inspected for :id and :architecture keys. If these keys are present, the results should be filtered by the value associated with each key. The filter_on(...) 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: -

- - http://git-wip-us.apache.org/repos/asf/deltacloud/blob/c7f4d022/site/output/#writing-tests.md# ---------------------------------------------------------------------- diff --git a/site/output/#writing-tests.md# b/site/output/#writing-tests.md# deleted file mode 100644 index fe79d5c..0000000 --- a/site/output/#writing-tests.md# +++ /dev/null @@ -1,57 +0,0 @@ ---- -site_name: Deltacloud API -title: Writing and running tests ---- - -
- -

Writing and running tests

- -

-You should add a test to every new feature or new driver you create to make sure, that everything is running as expected. There are two different directories in the Deltacloud project, where the tests are stored: /deltacloud/server/tests for Unit tests for drivers and /deltacloud/tests for Cucumber tests. -

- -

Initiate the Unit tests:

- -
-$ cd /path/to/deltacloud/server
-$ rake test
-
- -

This will invoke all Unit tests defined in /deltacloud/server/tests by inspecting the Rakefile in /deltacloud/server. To invoke a specific driver tests type:

- -
-$ cd /path/to/deltacloud/server
-$ rake test:rackspace
-  _OR_
-$ rake test:mock
-  _etc_
-
- -

Initiate the Cucumber tests:

- -
-$ cd /path/to/deltacloud/server
-$ rake cucumber
-
- -

Alternatively, you can invoke the cucumber tests directly without using Rakefile:

- -
-$ cd /path/to/deltacloud/server
-$ cucumber ../tests/mock
-  _OR_
-$ cucumber ../tests/ec2
-  _etc_
-
- -
- - Back - - - -
http://git-wip-us.apache.org/repos/asf/deltacloud/blob/c7f4d022/site/output/about.html ---------------------------------------------------------------------- diff --git a/site/output/about.html b/site/output/about.html index b0327fa..649a5d3 100644 --- a/site/output/about.html +++ b/site/output/about.html @@ -44,7 +44,7 @@ About
  • Download
    • @@ -99,11 +99,8 @@
    -
    - -

    About Deltacloud

    -
    -

    Deltacloud provides the API server and drivers necessary for connecting to cloud providers.

    +

    About Deltacloud

    +

    Deltacloud provides the API server and drivers necessary for connecting to cloud providers.

    Deltacloud maintains long-term stability for scripts, tools and applications and backward compatibility across different versions.

    @@ -112,33 +109,21 @@

    All of this means you can start an instance on an internal cloud and with the same code start another on EC2 or RHEV-M.

    -
    - -
    +
    Deltacloud API SOA diagram
    -
    -
    -

    How does Deltacloud work?

    -
    -

    Deltacloud contains a cloud abstraction API - whether the Deltacloud classic API, the DMTF CIMI API or even the EC2 API. The API works as a wrapper around a large number of clouds, abstracting their differences. For every cloud provider there is a driver "speaking" that cloud provider's native API, freeing you from dealing with the particulars of each cloud's API.

    +

    How does Deltacloud work?

    +

    Deltacloud contains a cloud abstraction API - whether the Deltacloud classic API, the DMTF CIMI API or even the EC2 API. The API works as a wrapper around a large number of clouds, abstracting their differences. For every cloud provider there is a driver "speaking" that cloud provider's native API, freeing you from dealing with the particulars of each cloud's API.

    Install Deltacloud and start the deltacloudd daemon server. You can use your favourite HTTP client to talk to the server using the Deltacloud REST API, the DMTF CIMI API or even the EC2 API. Deltacloud even comes with an HTML interface so you can simply use your web browser to control your cloud infrastructure straight out of the box. The HTML interface is written with the jQuery mobile framework, so it is compatible with your mobile or tablet devices.

    -
    - -Deltacloud concept scheme - -
    - -Get Deltacloud +
    Deltacloud concept scheme
    Get Deltacloud
    -