From 21b513544760f25edef2656cdf39e15db37e82c9 Mon Sep 17 00:00:00 2001
From: John Carr <john.carr@unrouted.co.uk>
Date: Thu, 1 Aug 2013 23:05:34 +0100
Subject: [PATCH] Initial pass at documenting how auth works for create_node
 and deploy_node

---
 libcloud/compute/base.py | 73 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 68 insertions(+), 5 deletions(-)

diff --git a/libcloud/compute/base.py b/libcloud/compute/base.py
index 0a84dd248d..aa1387e809 100644
--- a/libcloud/compute/base.py
+++ b/libcloud/compute/base.py
@@ -516,7 +516,58 @@ def _get_and_check_auth(self, auth):
                 'or NodeAuthSSHKey object', driver=self)
 
     def create_node(self, **kwargs):
-        """Create a new node instance.
+        """
+        Create a new node instance. This instance will be started
+        automatically.
+
+        Not all hosting API's are created equal and to allow libcloud to support
+        as many as possible there are some standard supported variations of
+        ``create_node``. These are declared using a ``features`` API. You can
+        inspect ``driver.features['create_node']`` to see what variation of the
+        API you are dealing with:
+
+        ``ssh_key``
+            You can inject a public key into a new node allows key based SSH
+            authentication.
+        ``password``
+            You can inject a password into a new node for SSH authentication.
+            If no password is provided libcloud will generated a password.
+            The password will be available as
+            ``return_value.extra['password']``.
+        ``generates_password``
+            The hosting provider will generate a password. It will be returned
+            to you via ``return_value.extra['password']``.
+
+        Some drivers allow you to set how you will authenticate with the
+        instance that is created. You can inject this initial authentication
+        information via the ``auth`` parameter.
+
+        If a driver supports the ``ssh_key`` feature flag for ``created_node``
+        you can upload a public key into the new instance::
+
+            >>> auth = NodeAuthSSHKey('pubkey data here')
+            >>> node = driver.create_node("test_node", auth=auth)
+
+        If a driver supports the ``password`` feature flag for ``create_node``
+        you can set a password::
+
+            >>> auth = NodeAuthPassword('mysecretpassword')
+            >>> node = driver.create_node("test_node", auth=auth)
+
+        If a driver supports the ``password`` feature and you don't provide the
+        ``auth`` argument libcloud will assign a password::
+
+            >>> node = driver.create_node("test_node")
+            >>> password = node.extra['password']
+
+        A password will also be returned in this way for drivers that declare
+        the ``generates_password`` feature, though in that case the password is
+        actually provided to the driver API by the hosting provider rather than
+        generated by libcloud.
+
+        You can only pass a :class:`NodeAuthPassword` or
+        :class:`NodeAuthSSHKey` to ``create_node`` via the auth parameter if
+        has the corresponding feature flag.
 
         :param name:   String with a name for this new node (required)
         :type name:   ``str``
@@ -619,8 +670,22 @@ def deploy_node(self, **kwargs):
         """
         Create a new node, and start deployment.
 
-        Depends on user providing authentication information or the Provider
-        Driver generating a password and returning it.
+        In order to be able to SSH into a created node access credentials are
+        required.
+
+        A user can pass either a :class:`NodeAuthPassword` or
+        :class:`NodeAuthSSHKey` to the ``auth`` argument. If the
+        ``create_node`` implementation supports that kind if credential (as
+        declared in ``self.features['create_node']``) then it is passed on to
+        ``create_node``. Otherwise it is not passed on to ``create_node`` and
+        it is only used for authentication.
+
+        If the ``auth`` parameter is not supplied but the driver declares it
+        supports ``generates_password`` then the password returned by
+        ``create_node`` will be used to SSH into the server.
+
+        Finally, if the ``ssh_key_file`` is supplied that key will be used to
+        SSH into the server.
 
         This function may raise a :class:`DeploymentException`, if a create_node
         call was successful, but there is a later error (like SSH failing or
@@ -646,8 +711,6 @@ def deploy_node(self, **kwargs):
         Deploy node is typically not overridden in subclasses.  The
         existing implementation should be able to handle most such.
 
-        @inherits: :class:`NodeDriver.create_node`
-
         :param deploy: Deployment to run once machine is online and
                             availble to SSH.
         :type deploy: :class:`Deployment`