Return-Path: 
 <deltacloud-dev-return-1453-apmail-incubator-deltacloud-dev-archive=incubator.apache.org@incubator.apache.org>
Delivered-To: apmail-incubator-deltacloud-dev-archive@minotaur.apache.org
Received: (qmail 34936 invoked from network); 29 Mar 2011 23:36:22 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3)
  by minotaur.apache.org with SMTP; 29 Mar 2011 23:36:22 -0000
Received: (qmail 58797 invoked by uid 500); 29 Mar 2011 23:36:22 -0000
Delivered-To: apmail-incubator-deltacloud-dev-archive@incubator.apache.org
Received: (qmail 58722 invoked by uid 500); 29 Mar 2011 23:36:22 -0000
Mailing-List: contact deltacloud-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:deltacloud-dev-help@incubator.apache.org>
List-Unsubscribe: <mailto:deltacloud-dev-unsubscribe@incubator.apache.org>
List-Post: <mailto:deltacloud-dev@incubator.apache.org>
List-Id: <deltacloud-dev.incubator.apache.org>
Reply-To: deltacloud-dev@incubator.apache.org
Delivered-To: mailing list deltacloud-dev@incubator.apache.org
Received: (qmail 58714 invoked by uid 99); 29 Mar 2011 23:36:21 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 29 Mar 2011 23:36:21 +0000
X-ASF-Spam-Status: No, hits=-5.0 required=5.0
	tests=RCVD_IN_DNSWL_HI,SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (athena.apache.org: domain of lutter@redhat.com designates
 209.132.183.28 as permitted sender)
Received: from [209.132.183.28] (HELO mx1.redhat.com) (209.132.183.28)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 29 Mar 2011 23:36:17 +0000
Received: from int-mx02.intmail.prod.int.phx2.redhat.com
 (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12])
	by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id p2TNZu3j010138
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK)
	for <deltacloud-dev@incubator.apache.org>; Tue, 29 Mar 2011 19:35:56 -0400
Received: from avon.watzmann.net (ovpn-113-147.phx2.redhat.com [10.3.113.147])
	by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id
 p2TNZtAK032277
	for <deltacloud-dev@incubator.apache.org>; Tue, 29 Mar 2011 19:35:56 -0400
From: lutter@redhat.com
To: deltacloud-dev@incubator.apache.org
Subject: [PATCH 3/3] Driver docs: explain how to switch drivers dynamically
Date: Tue, 29 Mar 2011 16:35:52 -0700
Message-Id: <1301441752-15265-4-git-send-email-lutter@redhat.com>
In-Reply-To: <1301441752-15265-1-git-send-email-lutter@redhat.com>
References: <1301441752-15265-1-git-send-email-lutter@redhat.com>
X-Scanned-By: MIMEDefang 2.67 on 10.5.11.12

From: David Lutterkort <lutter@redhat.com>

---
 site/content/_drivers.mdown |   30 +++++++++++++-
 site/output/drivers.html    |   95 +++++++++++++++++++++++++++++-------------
 2 files changed, 93 insertions(+), 32 deletions(-)

diff --git a/site/content/_drivers.mdown b/site/content/_drivers.mdown
index f952875..ed87d23 100644
--- a/site/content/_drivers.mdown
+++ b/site/content/_drivers.mdown
@@ -5,8 +5,6 @@ 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:
 
-<table providers></table>
-
 ## Setting up the code
 
 To set up a Deltacloud core and the drivers, install the
@@ -29,6 +27,34 @@ This will start a webserver running the mock driver on
 `http://localhost:3001/api`; you can simply browse to that URL to get a
 pretty view of the objects the driver deals with.
 
+## Dynamic driver switching
+
+The driver specified with the `-i` switch when `deltacloudd` 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 `drivers`
+collection.
+
+Some drivers also support the notion of a *provider*. 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.
+
+The driver and provider can be selected in one of two ways:
+
+1. Through the request headers `X-Deltacloud-Driver` and
+   `X-Deltacloud-Provider`. For example, including the headers
+   `X-Deltacloud-Driver: ec2` and `X-Deltacloud-Provider: eu-west-1`
+   ensures that a request will be serviced by the EC2 driver, and that the
+   driver will use the eu-west-1 region in EC2.
+2. Through the matrix request parameters `driver` and `provider` in the
+   `api` component of the server's URL. For example, requesting
+   `http://localhost:3001/api;driver=ec2;provider=eu-west-1` has the same
+   effect as using the two request headers mentioned above.
+
+## Notes on specific drivers
+
+<table providers></table>
+
 ### EC2 Driver
 
 For the Amazon EC2 you need to install the `amazon-ec2` Ruby gem:
diff --git a/site/output/drivers.html b/site/output/drivers.html
index 3494813..5dcc2cc 100644
--- a/site/output/drivers.html
+++ b/site/output/drivers.html
@@ -82,21 +82,27 @@
         </li>
         <li>
         <a href="#h2">Launch the server</a>
+        </li>
+        <li>
+        <a href="#h3">Dynamic driver switching</a>
+        </li>
+        <li>
+        <a href="#h4">Notes on specific drivers</a>
         <ul>
         <li>
-        <a href="#h2_1">EC2 Driver</a>
+        <a href="#h4_1">EC2 Driver</a>
         </li>
         <li>
-        <a href="#h2_2">RHEV-M Driver</a>
+        <a href="#h4_2">RHEV-M Driver</a>
         </li>
         <li>
-        <a href="#h2_3">Rackspace Driver</a>
+        <a href="#h4_3">Rackspace Driver</a>
         </li>
         <li>
-        <a href="#h2_4">RimuHosting</a>
+        <a href="#h4_4">RimuHosting</a>
         </li>
         <li>
-        <a href="#h2_5">OpenNebula</a>
+        <a href="#h4_5">OpenNebula</a>
         </li>
         </ul></li></ul>
         <!-- = rest -->
@@ -106,6 +112,55 @@
         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&#x000A;</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&#x000A;</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>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.</p>
+        
+        <p>The driver and provider can be selected in one of two ways:</p>
+        
+        <ol>
+        <li>Through the request headers <code>X-Deltacloud-Driver</code> and
+        <code>X-Deltacloud-Provider</code>. For example, including the headers
+        <code>X-Deltacloud-Driver: ec2</code> and <code>X-Deltacloud-Provider: eu-west-1</code>
+        ensures that a request will be serviced by the EC2 driver, and that the
+        driver will use the eu-west-1 region in EC2.</li>
+        <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>
+        </ol>
+        
+        
+        <h2 id="h4">Notes on specific drivers</h2>
         <h3>Compute Drivers</h3>
         <table id='providers'>
           <tr>
@@ -340,27 +395,7 @@
         
         
         
-        <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&#x000A;</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&#x000A;</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>
-        
-        <h3 id="h2_1">EC2 Driver</h3>
+        <h3 id="h4_1">EC2 Driver</h3>
         
         <p>For the Amazon EC2 you need to install the <code>amazon-ec2</code> Ruby gem:</p>
         
@@ -373,7 +408,7 @@
         <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="h2_2">RHEV-M Driver</h3>
+        <h3 id="h4_2">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
@@ -386,18 +421,18 @@
         the RHEVM.dll.config file which is referenced from the profile.ps1
         file located in My Documents/WindowsPowershell directory</p>
         
-        <h3 id="h2_3">Rackspace Driver</h3>
+        <h3 id="h4_3">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>
         
-        <h3 id="h2_4">RimuHosting</h3>
+        <h3 id="h4_4">RimuHosting</h3>
         
         <p>Further details coming soon.</p>
         
-        <h3 id="h2_5">OpenNebula</h3>
+        <h3 id="h4_5">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
-- 
1.7.4