Updated Branches: refs/heads/trunk d53fc6480 -> 4e0bc947d
Initial pass at documenting how auth works for create_node and deploy_node Signed-off-by: Tomaz Muraus <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/4e0bc947 Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/4e0bc947 Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/4e0bc947 Branch: refs/heads/trunk Commit: 4e0bc947d97750598308a4cce810fb6ef3b00b9f Parents: d53fc64 Author: John Carr <[email protected]> Authored: Thu Aug 1 23:05:34 2013 +0100 Committer: Tomaz Muraus <[email protected]> Committed: Tue Aug 6 14:13:10 2013 +0200 ---------------------------------------------------------------------- libcloud/compute/base.py | 73 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 68 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/4e0bc947/libcloud/compute/base.py ---------------------------------------------------------------------- diff --git a/libcloud/compute/base.py b/libcloud/compute/base.py index 9985b66..1c589c6 100644 --- a/libcloud/compute/base.py +++ b/libcloud/compute/base.py @@ -516,7 +516,58 @@ class NodeDriver(BaseDriver): '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 @@ class NodeDriver(BaseDriver): """ 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 @@ class NodeDriver(BaseDriver): 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`
