Merge pull request #21162 from cro/linode-python-driver2

Update linode salt-cloud driver to support using either linode-python or apache-libcloud

doc/topics/cloud/linode.rst

@@ -6,8 +6,28 @@ Linode is a public cloud provider with a focus on Linux instances.
 
 Dependencies
 ============
+* linode-python >= 1.1
+
+OR
+
 * Libcloud >= 0.13.2
 
+This driver supports accessing Linode via linode-python or Apache Libcloud.
+Linode-python is recommended, it is more full-featured than Libcloud.  In
+particular using linode-python enables stopping, starting, and cloning
+machines.
+
+Driver selection is automatic.  If linode-python is present it will be used.
+If it is absent, salt-cloud will fall back to Libcloud.  If neither are present
+salt-cloud will abort.
+
+NOTE: linode-python 1.1 or later is recommended.  As of this publication it is
+not yet on PyPi.  Earlier versions of linode-python should work but can leak
+sensitive information into the debug logs.
+
+Linode-python can be downloaded from
+https://github.com/tjfontaine/linode-python.
+
 Configuration
 =============
 Linode requires a single API key, but the default root password for new 
@@ -98,3 +118,34 @@ command:
                 uuid:
                     8457f92eaffc92b7666b6734a96ad7abe1a8a6dd
     ...SNIP...
+
+
+Cloning
+=======
+
+When salt-cloud accesses Linode via linode-python it can clone machines.
+
+It is safest to clone a stopped machine.  To stop a machine run
+
+.. code-block:: bash
+
+    salt-cloud -a stop machine_to_clone
+
+To create a new machine based on another machine, add an entry to your linode
+cloud profile that looks like this:
+
+.. code-block:: yaml
+
+    li-clone:
+      provider: linode
+      clonefrom: machine_to_clone
+      script_args: -C
+
+Then run salt-cloud as normal, specifying `-p li-clone`.  The profile name can
+be anything--it doesn't have to be `li-clone`.
+
+`Clonefrom:` is the name of an existing machine in Linode from which to clone.
+`Script_args: -C` is necessary to avoid re-deploying Salt via salt-bootstrap.
+`-C` will just re-deploy keys so the new minion will not have a duplicate key
+or minion_id on the master.
+