Updated Branches: refs/heads/trunk 90df4f66c -> 4a2945a4e
docs: Update upgrade notes, add a new section about key pair management and update existing docs. Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/56ad8509 Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/56ad8509 Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/56ad8509 Branch: refs/heads/trunk Commit: 56ad8509ebd716aa96c0d289edb23c9262d01aee Parents: b398aeb Author: Tomaz Muraus <[email protected]> Authored: Fri Dec 6 21:44:14 2013 +0100 Committer: Tomaz Muraus <[email protected]> Committed: Sun Dec 8 13:45:42 2013 +0100 ---------------------------------------------------------------------- docs/compute/api.rst | 3 ++ docs/compute/index.rst | 11 ++++- docs/compute/key_pair_management.rst | 51 ++++++++++++++++++++ docs/examples/compute/create_key_pair.py | 13 +++++ .../compute/import_key_pair_from_file.py | 13 +++++ .../compute/import_key_pair_from_string.py | 18 +++++++ docs/upgrade_notes.rst | 29 +++++++++++ 7 files changed, 137 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/compute/api.rst ---------------------------------------------------------------------- diff --git a/docs/compute/api.rst b/docs/compute/api.rst index 334f463..c45bbbe 100644 --- a/docs/compute/api.rst +++ b/docs/compute/api.rst @@ -25,6 +25,9 @@ Compute Base API .. autoclass:: libcloud.compute.base.StorageVolume :members: +.. autoclass:: libcloud.compute.base.KeyPair + :members: + .. autoclass:: libcloud.compute.types.NodeState :members: http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/compute/index.rst ---------------------------------------------------------------------- diff --git a/docs/compute/index.rst b/docs/compute/index.rst index 836925b..3487524 100644 --- a/docs/compute/index.rst +++ b/docs/compute/index.rst @@ -30,6 +30,7 @@ Compute * **NodeLocation** - represents a physical location where a server can be. * **NodeState** - represents a node state. Standard states are: ``running``, ``stopped``, ``rebooting``, ``terminated``, ``pending``, and ``unknown``. +* **KeyPair** - represents an SSH key pair object. Block Storage ~~~~~~~~~~~~~ @@ -56,12 +57,20 @@ Deployment ---------- Libcloud provides deployment functionality which makes bootstrapping a server -easier. It allows you to create a server and runn shell commands on it once the +easier. It allows you to create a server and run shell commands on it once the server has been created. For more information and examples, please see the :doc:`deployment page </compute/deployment>`. +SSH key pair management +----------------------- + +Compute API also allows you to manage your SSH key pairs. + +For more information and examples, please see the :doc:`key pair management +page </compute/key_pair_management>`. + Examples -------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/compute/key_pair_management.rst ---------------------------------------------------------------------- diff --git a/docs/compute/key_pair_management.rst b/docs/compute/key_pair_management.rst new file mode 100644 index 0000000..03fe6b7 --- /dev/null +++ b/docs/compute/key_pair_management.rst @@ -0,0 +1,51 @@ +SSH key pair management +======================= + +.. note:: + + This functionality is only available as part of the base API in Libcloud + 0.14.0 and above. Previously it was available on some drivers through + the extension methods. + +Key pair management functionality allows you to manage SSH key pairs on your +account. + +This includes the following functionality: + +* listing all the available key pairs on your account + (:func:`libcloud.compute.base.NodeDriver.list_key_pairs`) +* creating a new key pair + (:func:`libcloud.compute.base.NodeDriver.create_key_pair`) +* importing an existing public key + (:func:`libcloud.compute.base.NodeDriver.import_key_pair_from_string` + and :func:`libcloud.compute.base.NodeDriver.import_key_pair_from_file`) +* deleting an existing key pair + (:func:`libcloud.compute.base.NodeDriver.delete_key_pair`) + +Creating a new key pair +----------------------- + +This example shows how to create a new key pair using +:func:`libcloud.compute.base.NodeDriver.create_key_pair` method. + +To generate a new key pair, you only need to specify a `name` argument and the +provider will automatically generate a new key pair for you. Private key which +has been generated on your behalf is available in the value returned by the +create_key_pair method. + +.. literalinclude:: /examples/compute/create_key_pair.py + :language: python + +Importing an existing key pair +------------------------------ + +If you already have an existing key pair you would like to use, you can use +:func:`libcloud.compute.base.NodeDriver.import_key_pair_from_file` and +:func:`libcloud.compute.base.NodeDriver.import_key_pair_from_string` method +to import a public component of this pair. + +.. literalinclude:: /examples/compute/import_key_pair_from_file.py + :language: python + +.. literalinclude:: /examples/compute/import_key_pair_from_string.py + :language: python http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/examples/compute/create_key_pair.py ---------------------------------------------------------------------- diff --git a/docs/examples/compute/create_key_pair.py b/docs/examples/compute/create_key_pair.py new file mode 100644 index 0000000..d6f8bf7 --- /dev/null +++ b/docs/examples/compute/create_key_pair.py @@ -0,0 +1,13 @@ +from libcloud.compute.types import Provider +from libcloud.compute.providers import get_driver + +EC2_ACCESS_ID = 'your access id' +EC2_SECRET_KEY = 'your secret key' + +Driver = get_driver(Provider.EC2) +conn = Driver(EC2_ACCESS_ID, EC2_SECRET_KEY) + +key_pair = conn.create_key_pair(name='my-key-pair-1') + +# Private key which provided generated on your behalf should be available +# through key_pair.private_key attribute. http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/examples/compute/import_key_pair_from_file.py ---------------------------------------------------------------------- diff --git a/docs/examples/compute/import_key_pair_from_file.py b/docs/examples/compute/import_key_pair_from_file.py new file mode 100644 index 0000000..d14e0b2 --- /dev/null +++ b/docs/examples/compute/import_key_pair_from_file.py @@ -0,0 +1,13 @@ +import os + +from libcloud.compute.types import Provider +from libcloud.compute.providers import get_driver + +EC2_ACCESS_ID = 'your access id' +EC2_SECRET_KEY = 'your secret key' + +Driver = get_driver(Provider.EC2) +conn = Driver(EC2_ACCESS_ID, EC2_SECRET_KEY) + +key_file_path = os.path.expanduser('~/.ssh/id_rsa_my_key_pair_1.pub') +key_pair = conn.import_key_pair_from_file(key_file_path=key_file_path) http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/examples/compute/import_key_pair_from_string.py ---------------------------------------------------------------------- diff --git a/docs/examples/compute/import_key_pair_from_string.py b/docs/examples/compute/import_key_pair_from_string.py new file mode 100644 index 0000000..67e8c2e --- /dev/null +++ b/docs/examples/compute/import_key_pair_from_string.py @@ -0,0 +1,18 @@ +from __future__ import with_statement + +import os + +from libcloud.compute.types import Provider +from libcloud.compute.providers import get_driver + +EC2_ACCESS_ID = 'your access id' +EC2_SECRET_KEY = 'your secret key' + +Driver = get_driver(Provider.EC2) +conn = Driver(EC2_ACCESS_ID, EC2_SECRET_KEY) + +key_file_path = os.path.expanduser('~/.ssh/id_rsa_my_key_pair_1.pub') +with open(key_file_path, 'r') as fp: + key_material = fp.read() + +key_pair = conn.import_key_pair_from_string(key_material=key_material) http://git-wip-us.apache.org/repos/asf/libcloud/blob/56ad8509/docs/upgrade_notes.rst ---------------------------------------------------------------------- diff --git a/docs/upgrade_notes.rst b/docs/upgrade_notes.rst index 615f4e8..963059d 100644 --- a/docs/upgrade_notes.rst +++ b/docs/upgrade_notes.rst @@ -15,6 +15,35 @@ single class plus ``region`` argument model. More information on how this affects existing drivers and your code can be found bellow. +SSH Key pair management functionality has been promoted to the base API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSH key pair management functionality has been promoted to be a part of the +base compute API. + +As such, the following new classes and methods have been added: + +* `libcloud.compute.base.KeyPair` +* `libcloud.compute.base.NodeDriver.list_key_pairs` +* `libcloud.compute.base.NodeDriver.create_key_pair` +* `libcloud.compute.base.NodeDriver.import_key_pair_from_string` +* `libcloud.compute.base.NodeDriver.import_key_pair_from_file` +* `libcloud.compute.base.NodeDriver.delete_key_pair` + +Previously, this functionality was available in some of the provider drivers +(CloudStack, EC2, OpenStack) via the following extension methods: + +* `ex_list_keypairs` +* `ex_create_keypair` +* `ex_import_keypair_from_string` +* `ex_import_keypair` +* `ex_delete_keypair` + +Existing extension methods will continue to work until the next major release, +but you are strongly encouraged to start using new methods which are now part +of the base compute API and are guaranteed to work the same across different +providers. + Cache busting functionality is now only enabled in Rackspace first-gen driver ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
