You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by to...@apache.org on 2013/09/11 13:22:06 UTC
[4/6] git commit: docs: Add deployment chapter to the documentation.
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 <to...@apache.org>
Authored: Wed Sep 11 13:13:48 2013 +0200
Committer: Tomaz Muraus <to...@apache.org>
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