libcloud-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anthonys...@apache.org
Subject [3/9] libcloud git commit: Create documentation for the cloudscale driver.
Date Fri, 02 Dec 2016 10:32:25 GMT
Create documentation for the cloudscale driver.


Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/fd9fefdf
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/fd9fefdf
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/fd9fefdf

Branch: refs/heads/trunk
Commit: fd9fefdf1a381328809e5f7329c755fa6eb5ee6c
Parents: 588cb0c
Author: Dave Halter <davidhalter88@gmail.com>
Authored: Tue Nov 22 16:26:04 2016 +0100
Committer: Dave Halter <davidhalter88@gmail.com>
Committed: Tue Nov 22 16:26:04 2016 +0100

----------------------------------------------------------------------
 .../images/provider_logos/cloudscale.png        | Bin 0 -> 61533 bytes
 docs/compute/_supported_methods_main.rst        |   2 +
 docs/compute/_supported_providers.rst           |   2 +
 docs/compute/drivers/cloudscale.rst             |  75 +++++++++++++++++++
 .../cloudscale/cloudscale_compute_simple.py     |  26 +++++++
 libcloud/compute/drivers/cloudscale.py          |  40 +++++++++-
 6 files changed, 141 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/libcloud/blob/fd9fefdf/docs/_static/images/provider_logos/cloudscale.png
----------------------------------------------------------------------
diff --git a/docs/_static/images/provider_logos/cloudscale.png b/docs/_static/images/provider_logos/cloudscale.png
new file mode 100644
index 0000000..c4de9c4
Binary files /dev/null and b/docs/_static/images/provider_logos/cloudscale.png differ

http://git-wip-us.apache.org/repos/asf/libcloud/blob/fd9fefdf/docs/compute/_supported_methods_main.rst
----------------------------------------------------------------------
diff --git a/docs/compute/_supported_methods_main.rst b/docs/compute/_supported_methods_main.rst
index d369cb7..23ca5d8 100644
--- a/docs/compute/_supported_methods_main.rst
+++ b/docs/compute/_supported_methods_main.rst
@@ -10,6 +10,7 @@ Provider                              list nodes create node reboot node
destroy
 `Bluebox Blocks`_                     yes        yes         yes         yes          yes
        yes        yes        
 `Brightbox`_                          yes        yes         no          yes          yes
        yes        no         
 `BSNL`_                               yes        yes         yes         yes          yes
        yes        yes        
+`cloudscale.ch`_                      yes        yes         yes         yes          yes
        yes        no         
 `CloudSigma (API v2.0)`_              yes        yes         no          yes          yes
        yes        no         
 `CloudStack`_                         yes        yes         yes         yes          yes
        yes        yes        
 `Cloudwatt`_                          yes        yes         yes         yes          yes
        yes        yes        
@@ -66,6 +67,7 @@ Provider                              list nodes create node reboot node
destroy
 .. _`Bluebox Blocks`: http://bluebox.net
 .. _`Brightbox`: http://www.brightbox.co.uk/
 .. _`BSNL`: http://www.bsnlcloud.com/
+.. _`cloudscale.ch`: https://www.cloudscale.ch/
 .. _`CloudSigma (API v2.0)`: http://www.cloudsigma.com/
 .. _`CloudStack`: http://cloudstack.org/
 .. _`Cloudwatt`: https://www.cloudwatt.com/

http://git-wip-us.apache.org/repos/asf/libcloud/blob/fd9fefdf/docs/compute/_supported_providers.rst
----------------------------------------------------------------------
diff --git a/docs/compute/_supported_providers.rst b/docs/compute/_supported_providers.rst
index 377a046..63313d1 100644
--- a/docs/compute/_supported_providers.rst
+++ b/docs/compute/_supported_providers.rst
@@ -10,6 +10,7 @@ Provider                              Documentation
 `Bluebox Blocks`_                                                                       BLUEBOX
            single region driver                                                         
                                                                                 :mod:`libcloud.compute.drivers.bluebox`
          :class:`BlueboxNodeDriver`          
 `Brightbox`_                                                                            BRIGHTBOX
          single region driver                                                           
                                                                               :mod:`libcloud.compute.drivers.brightbox`
        :class:`BrightboxNodeDriver`        
 `BSNL`_                               :doc:`Click </compute/drivers/bsnl>`        
     BSNL                single region driver                                            
                                                                                         
    :mod:`libcloud.compute.drivers.bsnl`              :class:`BSNLNodeDriver`            

+`cloudscale.ch`_                      :doc:`Click </compute/drivers/cloudscale`      
  CLOUDSCALE          single region driver                                               
                                                                                         
 :mod:`libcloud.compute.drivers.cloudscale`        :class:`CloudscaleNodeDriver`       
 `CloudSigma (API v2.0)`_              :doc:`Click </compute/drivers/cloudsigma>`  
     CLOUDSIGMA          single region driver                                            
                                                                                         
    :mod:`libcloud.compute.drivers.cloudsigma`        :class:`CloudSigmaNodeDriver`      

 `CloudStack`_                         :doc:`Click </compute/drivers/cloudstack>`  
     CLOUDSTACK          single region driver                                            
                                                                                         
    :mod:`libcloud.compute.drivers.cloudstack`        :class:`CloudStackNodeDriver`      

 `Cloudwatt`_                          :doc:`Click </compute/drivers/cloudwatt>`   
     CLOUDWATT           single region driver                                            
                                                                                         
    :mod:`libcloud.compute.drivers.cloudwatt`         :class:`CloudwattNodeDriver`       

@@ -66,6 +67,7 @@ Provider                              Documentation
 .. _`Bluebox Blocks`: http://bluebox.net
 .. _`Brightbox`: http://www.brightbox.co.uk/
 .. _`BSNL`: http://www.bsnlcloud.com/
+.. _`cloudscale.ch`: https://www.cloudscale.ch/
 .. _`CloudSigma (API v2.0)`: http://www.cloudsigma.com/
 .. _`CloudStack`: http://cloudstack.org/
 .. _`Cloudwatt`: https://www.cloudwatt.com/

http://git-wip-us.apache.org/repos/asf/libcloud/blob/fd9fefdf/docs/compute/drivers/cloudscale.rst
----------------------------------------------------------------------
diff --git a/docs/compute/drivers/cloudscale.rst b/docs/compute/drivers/cloudscale.rst
new file mode 100644
index 0000000..5fbcdfc
--- /dev/null
+++ b/docs/compute/drivers/cloudscale.rst
@@ -0,0 +1,75 @@
+Cloudscale Compute Driver Documentation
+=======================================
+
+`cloudscale.ch`_ is a public cloud provider based in Switzerland.
+
+.. figure:: /_static/images/provider_logos/cloudscale.png
+    :align: center
+    :width: 200
+    :target: http://www.cloudscale.ch
+
+
+How to get an API Key
+---------------------
+
+Simply visit `<https://control.cloudscale.ch/user/api-tokens>`_ and start
+having fun!
+
+You can generate read and read/write API keys. These token types give you more
+access control. Revoking an API token is also possible.
+
+Using the API to the full extent
+--------------------------------
+
+Most of the `cloudscale.ch` API is covered by the simple commands:
+
+- ``driver.list_sizes()``
+- ``driver.list_images()``
+- ``driver.list_sizes()``
+- ``driver.reboot_node(node)``
+- ``driver.ex_start_node(node)``
+- ``driver.ex_stop_node(node)``
+- ``driver.ex_node_by_uuid(server_uuid)``
+- ``driver.destroy_node(node)``
+- ``driver.create_node(name, size, image, ex_create_attr={})``
+
+In our :ref:`example <cloudscale-examples>` below you can see how you use 
+``ex_create_attr`` when creating servers. Possible dictionary entries in 
+``ex_create_attr`` are:
+
+- ``ssh_keys``: ``list`` of ``strings``; A list of SSH public keys.
+- ``volume_size_gb``:  ``integer``; The size in GB of the root volume.
+- ``bulk_volume_size_gb``: ``integer``; The size in GB of the bulk storage volume.
+- ``use_public_network``: ``boolean`` Attaching/Detaching the public network interface.
+- ``use_private_network``: ``boolean`` Attaching/Detaching the private network interface.
+- ``use_ipv6``: ``boolean`` Enabling/Disabling IPv6.
+- ``anti_affinity_with``: ``string``; Pass the UUID of another server.
+- ``user_data``: ``string``; Cloud-init configuration (cloud-config). Provide YAML.
+
+
+There's more extensive documentation on these parameters in our
+`Server-Create API Documentation`_.
+
+.. _cloudscale-examples:
+
+Examples
+--------
+
+Create a cloudscale.ch server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/compute/cloudscale/cloudscale_compute_simple.py
+   :language: python
+
+API Docs
+--------
+
+.. autoclass:: libcloud.compute.drivers.cloudscale.CloudscaleNodeDriver
+    :members: create_node, list_images, list_nodes, list_sizes, 
+              wait_until_running, reboot_node, ex_start_node, ex_stop_node,
+              ex_node_by_uuid, destroy_node
+    :undoc-members: 
+
+.. _`cloudscale.ch`: https://www.cloudscale.ch
+.. _`cloudscale.ch API`: https://www.cloudscale.ch/en/api/v1
+.. _`Server-Create API Documentation`: https://www.cloudscale.ch/en/api/v1#servers-create

http://git-wip-us.apache.org/repos/asf/libcloud/blob/fd9fefdf/docs/examples/compute/cloudscale/cloudscale_compute_simple.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/cloudscale/cloudscale_compute_simple.py b/docs/examples/compute/cloudscale/cloudscale_compute_simple.py
new file mode 100644
index 0000000..eb2f99d
--- /dev/null
+++ b/docs/examples/compute/cloudscale/cloudscale_compute_simple.py
@@ -0,0 +1,26 @@
+from pprint import pprint
+
+import libcloud
+
+cls = libcloud.get_driver(
+    libcloud.DriverType.COMPUTE,
+    libcloud.DriverType.COMPUTE.CLOUDSCALE
+)
+
+driver = cls('3pjzjh3h3rfynqa4iemvtvc33pyfzss2')
+
+sizes = driver.list_sizes()
+images = driver.list_images()
+pprint(sizes)
+pprint(images)
+
+new_node = driver.create_node(
+    name='hello-darkness-my-old-friend',
+    size=sizes[0],
+    image=images[0],
+    ex_create_attr=dict(
+        ssh_keys=['ssh-rsa AAAAB3Nza...'],
+        use_private_network=True,
+    )
+)
+pprint(new_node)

http://git-wip-us.apache.org/repos/asf/libcloud/blob/fd9fefdf/libcloud/compute/drivers/cloudscale.py
----------------------------------------------------------------------
diff --git a/libcloud/compute/drivers/cloudscale.py b/libcloud/compute/drivers/cloudscale.py
index 156f249..e654e57 100644
--- a/libcloud/compute/drivers/cloudscale.py
+++ b/libcloud/compute/drivers/cloudscale.py
@@ -86,12 +86,25 @@ class CloudscaleNodeDriver(NodeDriver):
         super(CloudscaleNodeDriver, self).__init__(key, **kwargs)
 
     def list_nodes(self):
+        '''
+        List all your existing compute nodes.
+        '''
         return self._list_resources('/v1/servers', self._to_node)
 
     def list_sizes(self):
+        '''
+        Lists all available sizes. On cloudscale these are known as flavors.
+        '''
         return self._list_resources('/v1/flavors', self._to_size)
 
     def list_images(self):
+        '''
+        List all images.
+
+        Images are identified by slugs on cloudscale.ch. This means that minor
+        version upgrades (e.g. Ubuntu 16.04.1 to Ubuntu 16.04.2) will be
+        possible within the same id ``ubuntu-16.04``.
+        '''
         return self._list_resources('/v1/images', self._to_image)
 
     def create_node(self, name, size, image, location=None, ex_create_attr={}):
@@ -115,10 +128,6 @@ class CloudscaleNodeDriver(NodeDriver):
                                  droplet creation
         :type ex_create_attr: ``dict``
 
-        :keyword    ex_user_data:  User data to be added to the node on create.
-                                     (optional)
-        :type       ex_user_data:  ``str``
-
         :return: The newly created node.
         :rtype: :class:`Node`
         """
@@ -136,19 +145,42 @@ class CloudscaleNodeDriver(NodeDriver):
         return self._to_node(result.object)
 
     def reboot_node(self, node):
+        '''
+        Reboot a node. It's also possible to use ``node.reboot()``.
+        '''
         return self._action(node, 'reboot')
 
     def ex_start_node(self, node):
+        '''
+        Start a node. This is only possible if the node is stopped.
+        '''
         return self._action(node, 'start')
 
     def ex_stop_node(self, node):
+        '''
+        Stop a specific node. Similar to ``shutdown -h now``. This is only
+        possible if the node is running.
+        '''
         return self._action(node, 'stop')
 
     def ex_node_by_uuid(self, uuid):
+        '''
+        :param str ex_user_data: A valid uuid that references your exisiting
+            cloudscale.ch server.
+        :type       ex_user_data:  ``str``
+
+        :return: The server node you asked for.
+        :rtype: :class:`Node`
+        '''
         res = self.connection.request(self._get_server_url(uuid))
         return self._to_node(res.object)
 
     def destroy_node(self, node):
+        '''
+        Delete a node. It's also possible to use ``node.destroy()``.
+        This will irreversibly delete the cloudscale.ch server and all its
+        volumes. So please be cautious.
+        '''
         res = self.connection.request(
             self._get_server_url(node.id),
             method='DELETE'


Mime
View raw message