docs: Add deployment chapter to the documentation.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/f0112259 Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/f0112259 Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/f0112259 Branch: refs/heads/trunk Commit: f01122599d7095a92b47d34bbc8563c882693e4c Parents: ae9f2ca Author: Tomaz Muraus <[email protected]> Authored: Wed Sep 11 13:13:48 2013 +0200 Committer: Tomaz Muraus <[email protected]> Committed: Wed Sep 11 13:13:48 2013 +0200 ---------------------------------------------------------------------- docs/compute/deployment.rst | 95 ++++++++++++++++++++ .../compute/bootstrapping_puppet_on_node.py | 26 +++--- ...deployment_single_step_install_public_key.py | 30 +++++++ docs/troubleshooting.rst | 4 + 4 files changed, 145 insertions(+), 10 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/f0112259/docs/compute/deployment.rst ---------------------------------------------------------------------- diff --git a/docs/compute/deployment.rst b/docs/compute/deployment.rst new file mode 100644 index 0000000..2f0a721 --- /dev/null +++ b/docs/compute/deployment.rst @@ -0,0 +1,95 @@ +Deployment +========== + +Compute part of the API exposes a simple deployment functionality through the +:func:`libcloud.compute.base.NodeDriver.deploy_node` method. This functionality is +there to help you bootstrap a new server. It allows you to perform tasks such +as: + +* Install your public SSH key on the server +* Instal configuration management software +* Add an initial user account +* Install an initial set of SSL certificates and keys on the server + +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 +and replaced by other tools such as previously mentioned configuration +management software. + +Deployment classes +------------------ + +Deployment module exposes multiple classes which make running common +bootstrap tasks such as installing a file and running a shell command +on a server easier. + +All the available classes are listed bellow. + +.. autoclass:: libcloud.compute.deployment.SSHKeyDeployment +.. autoclass:: libcloud.compute.deployment.FileDeployment +.. autoclass:: libcloud.compute.deployment.ScriptDeployment +.. autoclass:: libcloud.compute.deployment.ScriptFileDeployment +.. autoclass:: libcloud.compute.deployment.MultiStepDeployment + +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: + +1. Create a server (same as ``create_node``, in fact it calls ``create_node`` + underneath) +2. Wait for the server to come online and SSH server to become available +3. Run provided bootstrap step(s) on the server + +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 +: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 a couple of additional arguments. The most important ones are ``deploy`` +and ``auth``: + +* ``deploy`` argument specifies which deployment step or steps to run after the + server has been created. +* ``auth`` arguments tells how to login in to the created server. If this + argument is not specified it is assumed that the provider API returns a root + 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. + +Examples which demonstrates how this method can be used are displayed bellow. + +Run a single deploy step using ScriptDeployment class +----------------------------------------------------- + +The example bellow runs a single step and installs your public key on the +server. + +.. literalinclude:: /examples/compute/deployment_single_step_install_public_key.py + :language: python + +Run multiple deploy steps using MultiStepDeployment class +--------------------------------------------------------- + +The example bellow runs two steps on the server using ``MultiStepDeployment`` +class. As a first step it installs you SSH key and as a second step it runs a +shell script. + +.. literalinclude:: /examples/compute/bootstrapping_puppet_on_node.py + :language: python + + +.. _`Chef`: http://www.opscode.com/chef/ +.. _`Puppet`: http://puppetlabs.com/ +.. _`Salt`: http://docs.saltstack.com/topics/ +.. _`CFEngine`: http://cfengine.com/ http://git-wip-us.apache.org/repos/asf/libcloud/blob/f0112259/docs/examples/compute/bootstrapping_puppet_on_node.py ---------------------------------------------------------------------- diff --git a/docs/examples/compute/bootstrapping_puppet_on_node.py b/docs/examples/compute/bootstrapping_puppet_on_node.py index c72921f..3acaa10 100644 --- a/docs/examples/compute/bootstrapping_puppet_on_node.py +++ b/docs/examples/compute/bootstrapping_puppet_on_node.py @@ -1,8 +1,14 @@ +from __future__ import with_statement + +import os + from libcloud.compute.types import Provider from libcloud.compute.providers import get_driver from libcloud.compute.deployment import MultiStepDeployment from libcloud.compute.deployment import ScriptDeployment, SSHKeyDeployment -import os + +# Path to the public key you would like to install +KEY_PATH = os.path.expanduser('~/.ssh/id_rsa.pub') RACKSPACE_USER = 'your username' RACKSPACE_KEY = 'your key' @@ -10,14 +16,17 @@ RACKSPACE_KEY = 'your key' Driver = get_driver(Provider.RACKSPACE) conn = Driver(RACKSPACE_USER, RACKSPACE_KEY) -# read your public key in +with open(KEY_PATH) as fp: + content = fp.read() + # Note: This key will be added to the authorized keys for the root user # (/root/.ssh/authorized_keys) -sd = SSHKeyDeployment(open(os.path.expanduser("~/.ssh/id_rsa.pub")).read()) -# a simple script to install puppet post boot, can be much more complicated. -script = ScriptDeployment("apt-get -y install puppet") -# a task that first installs the ssh key, and then runs the script -msd = MultiStepDeployment([sd, script]) +step_1 = SSHKeyDeployment(content) + +# A simple script to install puppet post boot, can be much more complicated. +step_2 = ScriptDeployment('apt-get -y install puppet') + +msd = MultiStepDeployment([step_1, step_2]) images = conn.list_images() sizes = conn.list_sizes() @@ -25,6 +34,3 @@ 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=msd) -# <Node: uuid=..., name=test, state=3, public_ip=['1.1.1.1'], -# provider=Rackspace ...> -# the node is now booted, with your ssh key and puppet installed. http://git-wip-us.apache.org/repos/asf/libcloud/blob/f0112259/docs/examples/compute/deployment_single_step_install_public_key.py ---------------------------------------------------------------------- diff --git a/docs/examples/compute/deployment_single_step_install_public_key.py b/docs/examples/compute/deployment_single_step_install_public_key.py new file mode 100644 index 0000000..787f873 --- /dev/null +++ b/docs/examples/compute/deployment_single_step_install_public_key.py @@ -0,0 +1,30 @@ +from __future__ import with_statement + +import os + +from libcloud.compute.types import Provider +from libcloud.compute.providers import get_driver +from libcloud.compute.deployment import SSHKeyDeployment + +# Path to the public key you would like to install +KEY_PATH = os.path.expanduser('~/.ssh/id_rsa.pub') + +RACKSPACE_USER = 'your username' +RACKSPACE_KEY = 'your key' + +Driver = get_driver(Provider.RACKSPACE) +conn = Driver(RACKSPACE_USER, RACKSPACE_KEY) + +with open(KEY_PATH) as fp: + content = fp.read() + +# Note: This key will be added to the authorized keys for the root user +# (/root/.ssh/authorized_keys) +step = SSHKeyDeployment(content) + +images = conn.list_images() +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) http://git-wip-us.apache.org/repos/asf/libcloud/blob/f0112259/docs/troubleshooting.rst ---------------------------------------------------------------------- diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 9de0922..64f3582 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -1,12 +1,16 @@ Troubleshooting =============== +.. _troubleshooting: + This page contains various tips which can help you troubleshoot and debug code with interfaces with libcloud. Debugging --------- +.. _debugging: + .. note:: If you are sharing debug output on our IRC channel or issue tracker using
