[libcloud] 01/02: Update deployment docs.

[to...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tomaz pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/libcloud.git

commit e0af06c1cd5a0d221766a9b0720ffa4b9a830324
Author: Tomaz Muraus <to...@tomaz.me>
AuthorDate: Wed Jul 17 23:09:08 2019 +0200

    Update deployment docs.
---
 docs/compute/deployment.rst                        | 23 +++++++++++++++-------
 .../deployment_single_step_install_public_key.py   |  5 ++++-
 2 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/docs/compute/deployment.rst b/docs/compute/deployment.rst
index 1ac9f6f..31c1935 100644
--- a/docs/compute/deployment.rst
+++ b/docs/compute/deployment.rst
@@ -17,7 +17,7 @@ As noted above, this functionality is there to help you bootstrap a server
 and is not a replacement for a configuration management software such as
 `Chef`_ `Puppet`_, `Salt`_, `CFEngine`_ and others.
 
-Once your server has been bootstrapped, libcloud.deploy task should be done
+Once your server has been bootstrapped, libcloud.deploy task should be finished
 and replaced by other tools such as previously mentioned configuration
 management software.
 
@@ -34,7 +34,7 @@ Keys which contain the following header should generally work:
 
 * ``-----BEGIN RSA PRIVATE KEY-----``
 * ``-----BEGIN DSA PRIVATE KEY-----``
-* ``-----BEGIN ECDSA PRIVATE KEY-----``
+* ``-----BEGIN EC PRIVATE KEY-----``
 
 And keys which contain the following header won't work:
 
@@ -80,8 +80,10 @@ Using deployment functionality
 This section describes how to use deployment functionality and
 :func:`libcloud.compute.base.NodeDriver.deploy_node` method.
 
-deploy_node method allows you to create a cloud server and run bootstrap
-commands on it. It works in the following steps:
+deploy_node method allows you to create a server and run bootstrap commands on
+it.
+
+This method performs the following operations:
 
 1. Create a server (same as ``create_node``, in fact it calls ``create_node``
    underneath)
@@ -91,13 +93,13 @@ commands on it. It works in the following steps:
 As noted above, second step waits for node to become available which means it
 can take a while. If for some reason deploy_node is timing out, make sure you
 are using a correct ``ssh_username``. You can troubleshoot deployment issues
-using LIBCLOUD_DEBUG method which is described on the
+using ``LIBCLOUD_DEBUG`` method which is described on the
 :ref:`troubleshooting page <troubleshooting>`.
 
 :func:`libcloud.compute.base.NodeDriver.deploy_node` takes the same base
 keyword arguments as the :func:`libcloud.compute.base.NodeDriver.create_node`
-method and couple of additional arguments. The most important ones are
-``deploy`` and ``auth``:
+method and a couple of additional arguments. The most important ones are
+``deploy``, ``auth`` and ``ssh_key``:
 
 * ``deploy`` argument specifies which deployment step or steps to run after the
   server has been created.
@@ -106,6 +108,13 @@ method and couple of additional arguments. The most important ones are
   password once the server has been created and this password is then used to
   log in. For more information, please see the create_node and deploy_node
   method docstring.
+* ``ssh_key`` - A path to a private SSH key file which will be used to
+  authenticate. Key needs to be in a format which is supported by paramiko
+  (see section on supported key types above).
+* ``ssh_username`` - SSH username used to login. If not provided, it defaults
+  to ``root``
+* ``ssh_port`` - Port of the SSH server. If not provided, it defaults to
+  ``22``.
 
 Some examples which demonstrate how this method can be used are displayed
 below.
diff --git a/docs/examples/compute/deployment_single_step_install_public_key.py b/docs/examples/compute/deployment_single_step_install_public_key.py
index 787f873..6c0e264 100644
--- a/docs/examples/compute/deployment_single_step_install_public_key.py
+++ b/docs/examples/compute/deployment_single_step_install_public_key.py
@@ -6,6 +6,9 @@ from libcloud.compute.types import Provider
 from libcloud.compute.providers import get_driver
 from libcloud.compute.deployment import SSHKeyDeployment
 
+# Path to the private SSH key file used to authenticate
+PRIVATE_SSH_KEY_PATH = os.path.expanduser('~/.ssh/id_rsa')
+
 # Path to the public key you would like to install
 KEY_PATH = os.path.expanduser('~/.ssh/id_rsa.pub')
 
@@ -27,4 +30,4 @@ sizes = conn.list_sizes()
 
 # deploy_node takes the same base keyword arguments as create_node.
 node = conn.deploy_node(name='test', image=images[0], size=sizes[0],
-                        deploy=step)
+                        deploy=step, ssh_key=PRIVATE_SSH_KEY_PATH)