libcloud-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From to...@apache.org
Subject [1/6] git commit: Update Documentation for Google Compute Engine Also, some fixes to docstrings to play nicely with sphinx.
Date Fri, 17 Jan 2014 19:01:46 GMT
Updated Branches:
  refs/heads/trunk b4a708f31 -> 018a54aa5


Update Documentation for Google Compute Engine
Also, some fixes to docstrings to play nicely with sphinx.


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

Branch: refs/heads/trunk
Commit: 6369eace67bf6424b9a9058e58bbce67931d2997
Parents: 0841c5b
Author: Rick Wright <rickw@google.com>
Authored: Fri Jan 17 05:05:40 2014 -0800
Committer: Rick Wright <rickw@google.com>
Committed: Fri Jan 17 05:05:40 2014 -0800

----------------------------------------------------------------------
 docs/_static/images/provider_logos/gce.png      | Bin 11761 -> 0 bytes
 docs/_static/images/provider_logos/gcp.png      | Bin 0 -> 53640 bytes
 docs/compute/drivers/gce.rst                    | 100 +++++++++++++++++++
 docs/examples/compute/gce/gce_datacenter.py     |   9 ++
 .../compute/gce/gce_installed_application.py    |   6 ++
 .../examples/compute/gce/gce_service_account.py |   6 ++
 .../loadbalancer/gce/gce_authentication.py      |   7 ++
 docs/examples/loadbalancer/gce/gce_driver.py    |  13 +++
 docs/loadbalancer/drivers/gce.rst               |  46 +++++++++
 libcloud/compute/drivers/gce.py                 |  19 ++--
 libcloud/loadbalancer/drivers/gce.py            |   2 +-
 11 files changed, 199 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/_static/images/provider_logos/gce.png
----------------------------------------------------------------------
diff --git a/docs/_static/images/provider_logos/gce.png b/docs/_static/images/provider_logos/gce.png
deleted file mode 100644
index 4a97918..0000000
Binary files a/docs/_static/images/provider_logos/gce.png and /dev/null differ

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

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/compute/drivers/gce.rst
----------------------------------------------------------------------
diff --git a/docs/compute/drivers/gce.rst b/docs/compute/drivers/gce.rst
new file mode 100644
index 0000000..dc76204
--- /dev/null
+++ b/docs/compute/drivers/gce.rst
@@ -0,0 +1,100 @@
+Google Compute Engine Driver Documentation
+==========================================
+
+`Google Cloud Platform Compute Engine`_ gives users the ability to run
+large-scale workloads on virtual machines hosted on Google's infrastructure.
+It is a part of Google Cloud Platform.
+
+.. figure:: /_static/images/provider_logos/gcp.png
+    :align: center
+    :width: 500
+    :target: https://cloud.google.com/
+
+Google Compute Engine features:
+
+* High-performance virtual machines
+* Minute-level billing (10-minute minumum)
+* Fast VM provisioning
+* Native Load Balancing
+
+Connecting to Google Compute Engine
+-----------------------------------
+Libcloud supports two different methods for authenticating to Compute Engine:
+`Service Account`_ and `Installed Application`_
+
+Which one should I use?
+
+* Service Accounts are generally better suited for automated systems, cron
+  jobs, etc.  They should be used when access to the application/script is
+  limited and needs to be able to run with limited intervention.
+
+* Installed Application authentication is often the better choice when
+  creating an application that may be used by third-parties interactively. For
+  example, a desktop application for managing VMs that would be used by many
+  different people with different Google accounts.
+
+Once you have set up the authentication as described below, you pass the
+authentication information to the driver as described in `Examples`_
+
+
+Service Account
+~~~~~~~~~~~~~~~
+
+To set up Service Account authentication:
+
+1. Follow the instructions at 
+   https://developers.google.com/console/help/new/#serviceaccounts
+   to create and download a PKCS-12 private key.
+2. Convert the PKCS-12 private key to a .pem file using the following:
+   ``openssl pkcs12 -in YOURPRIVKEY.p12 -nodes -nocerts 
+   | openssl rsa -out PRIV.pem``
+3. Move the .pem file to a safe location
+4. You will need the Service Account's "Email Address" and the path to the
+   .pem file for authentication.
+5. You will also need your "Project ID" which can be found by clicking on the
+   "Overview" link on the left sidebar.
+
+Installed Application
+~~~~~~~~~~~~~~~~~~~~~
+
+To set up Installed Account authentication:
+
+1. Go to the `Google Developers Console`_
+2. Select your project
+3. In the left sidebar, go to "APIs & auth"
+4. Click on "Credentials" then "Create New Client ID"
+5. Select "Installed application" and "Other" then click "Create Client ID"
+6. For authentication, you will need the "Client ID" and the "Client Secret"
+7. You will also need your "Project ID" which can be found by clicking on the
+   "Overview" link on the left sidebar.
+
+Examples
+--------
+
+Additional example code can be found in the "demos" directory of Libcloud here:
+https://github.com/apache/libcloud/blob/trunk/demos/gce_demo.py
+
+1. Getting Driver with Service Account authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/compute/gce/gce_service_account.py
+
+2. Getting Driver with Installed Application authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/compute/gce/gce_installed_application.py
+
+3. Getting Driver using a default Datacenter (Zone)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/compute/gce/gce_datacenter.py
+
+API Docs
+--------
+
+.. autoclass:: libcloud.compute.drivers.gce.GCENodeDriver
+    :members:
+    :inherited-members:
+
+.. _`Google Cloud Platform Compute Engine`: https://cloud.google.com/products/compute-engine/
+.. _`Google Developers Console`: https://cloud.google.com/console

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/examples/compute/gce/gce_datacenter.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/gce/gce_datacenter.py b/docs/examples/compute/gce/gce_datacenter.py
new file mode 100644
index 0000000..59afbc6
--- /dev/null
+++ b/docs/examples/compute/gce/gce_datacenter.py
@@ -0,0 +1,9 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+ComputeEngine = get_driver(Provider.GCE)
+# Datacenter is set to 'us-central1-a' as an example, but can be set to any
+# zone, like 'us-central1-b' or 'europe-west1-a'
+driver = ComputeEngine('your_service_account_email', 'path_to_pem_file',
+                        datacenter='us-central1-a',
+                        project='your_project_id')

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/examples/compute/gce/gce_installed_application.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/gce/gce_installed_application.py b/docs/examples/compute/gce/gce_installed_application.py
new file mode 100644
index 0000000..d6a10ce
--- /dev/null
+++ b/docs/examples/compute/gce/gce_installed_application.py
@@ -0,0 +1,6 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+ComputeEngine = get_driver(Provider.GCE)
+driver = ComputeEngine('your_client_id', 'your_client_secret',
+                       project='your_project_id')

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/examples/compute/gce/gce_service_account.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/gce/gce_service_account.py b/docs/examples/compute/gce/gce_service_account.py
new file mode 100644
index 0000000..69e3b64
--- /dev/null
+++ b/docs/examples/compute/gce/gce_service_account.py
@@ -0,0 +1,6 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+ComputeEngine = get_driver(Provider.GCE)
+driver = ComputeEngine('your_service_account_email', 'path_to_pem_file',
+                        project='your_project_id')

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/examples/loadbalancer/gce/gce_authentication.py
----------------------------------------------------------------------
diff --git a/docs/examples/loadbalancer/gce/gce_authentication.py b/docs/examples/loadbalancer/gce/gce_authentication.py
new file mode 100644
index 0000000..0e3a623
--- /dev/null
+++ b/docs/examples/loadbalancer/gce/gce_authentication.py
@@ -0,0 +1,7 @@
+from libcloud.loadbalancer.types import Provider
+from libcloud.loadbalancer.providers import get_driver
+
+LoadBalancer = get_driver(Provider.GCE)
+driver = ComputeEngine('service_account_email_or_client_id',
+                       'pem_file_or_client_secret',
+                        project='your_project_id')

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/examples/loadbalancer/gce/gce_driver.py
----------------------------------------------------------------------
diff --git a/docs/examples/loadbalancer/gce/gce_driver.py b/docs/examples/loadbalancer/gce/gce_driver.py
new file mode 100644
index 0000000..c26f15e
--- /dev/null
+++ b/docs/examples/loadbalancer/gce/gce_driver.py
@@ -0,0 +1,13 @@
+from libcloud.compute.types import Provider
+from libcloud.compute.providers import get_driver
+
+from libcloud.loadbalancer.types import Provider as LBProvider
+from libcloud.loadbalancer.providers import get_driver as lb_get_driver
+
+ComputeEngine = get_driver(Provider.GCE)
+gce_driver = ComputeEngine('service_account_email_or_client_id',
+                           'pem_file_or_client_secret',
+                           project='your_project_id')
+
+LoadBalancer = lb_get_driver(LBProvider.GCE)
+lb_driver = LoadBalancer(gce_driver=gce_driver)

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/docs/loadbalancer/drivers/gce.rst
----------------------------------------------------------------------
diff --git a/docs/loadbalancer/drivers/gce.rst b/docs/loadbalancer/drivers/gce.rst
new file mode 100644
index 0000000..15983cb
--- /dev/null
+++ b/docs/loadbalancer/drivers/gce.rst
@@ -0,0 +1,46 @@
+Google Load Balancer Driver Documentation
+==========================================
+
+Loadbalancing in Compute Engine is native to Google Compute Engine.
+
+.. figure:: /_static/images/provider_logos/gcp.png
+    :align: center
+    :width: 500
+    :target: https://cloud.google.com/
+
+Connecting to Compute Engine Load Balancer
+------------------------------------------
+
+Refer to
+:doc:`Google Compute Engine Driver Documentation </compute/drivers/gce>` for
+information about setting up authentication for GCE.
+
+In order to instantiate a driver for the Load Balancer, you can either pass
+in the same authentication information as you would to the GCE driver, or you
+can instantiate the GCE driver and pass that to the Load Balancer driver.
+The latter is preferred (since you are probably getting a GCE driver anyway),
+but the former aligns more closely to the Libcloud API.
+
+Examples
+--------
+
+Additional example code can be found in the "demos" directory of Libcloud here:
+https://github.com/apache/libcloud/blob/trunk/demos/gce_lb_demo.py
+
+1. Getting Driver with GCE Driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/loadbalancer/gce/gce_driver.py
+
+2. Getting Driver with Authentication Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: /examples/loadbalancer/gce/gce_authentication.py
+
+API Docs
+--------
+
+.. autoclass:: libcloud.loadbalancer.drivers.gce.GCELBDriver
+    :members:
+    :inherited-members:
+

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/libcloud/compute/drivers/gce.py
----------------------------------------------------------------------
diff --git a/libcloud/compute/drivers/gce.py b/libcloud/compute/drivers/gce.py
index c8e770f..435b53e 100644
--- a/libcloud/compute/drivers/gce.py
+++ b/libcloud/compute/drivers/gce.py
@@ -492,7 +492,7 @@ class GCENodeDriver(NodeDriver):
     api_name = 'googleapis'
     name = "Google Compute Engine"
     type = Provider.GCE
-    website = 'https://www.googleapis.com/'
+    website = 'https://cloud.google.com/'
 
     NODE_STATE_MAP = {
         "PROVISIONING": NodeState.PENDING,
@@ -962,16 +962,19 @@ class GCENodeDriver(NodeDriver):
 
         Firewall rules should be supplied in the "allowed" field.  This is a
         list of dictionaries formated like so ("ports" is optional)::
+
             [{"IPProtocol": "<protocol string or number>",
-              "ports": [ "<port_numbers or ranges>"}]
+              "ports": "<port_numbers or ranges>"}]
 
         For example, to allow tcp on port 8080 and udp on all ports, 'allowed'
         would be::
+
             [{"IPProtocol": "tcp",
               "ports": ["8080"]},
              {"IPProtocol": "udp"}]
-        See U{Firewall Reference<https://developers.google.com/compute/docs/
-        reference/latest/firewalls/insert>} for more information.
+
+        See `Firewall Reference <https://developers.google.com/compute/docs/
+        reference/latest/firewalls/insert>`_ for more information.
 
         :param  name: Name of the firewall to be created
         :type   name: ``str``
@@ -1166,6 +1169,7 @@ class GCENodeDriver(NodeDriver):
         Nodes will be named with the base name and a number.  For example, if
         the base name is 'libcloud' and you create 3 nodes, they will be
         named::
+
             libcloud-000
             libcloud-001
             libcloud-002
@@ -1205,7 +1209,7 @@ class GCENodeDriver(NodeDriver):
         :type     use_existing_disk: ``bool``
 
         :keyword  poll_interval: Number of seconds between status checks.
-        :type	  poll_interval: ``int``
+        :type     poll_interval: ``int``
 
         :keyword  timeout: The number of seconds to wait for all nodes to be
                            created before timing out.
@@ -1649,9 +1653,8 @@ class GCENodeDriver(NodeDriver):
                                automatic_restart=None):
         """Set the maintenance behavior for the node.
 
-        See Scheduling_ documentation for more info.
-        _Scheduling:
-        https://developers.google.com/compute/docs/instances#onhostmaintenance
+        See `Scheduling <https://developers.google.com/compute/
+        docs/instances#onhostmaintenance>`_ documentation for more info.
 
         :param  node: Node object
         :type   node: :class:`Node`

http://git-wip-us.apache.org/repos/asf/libcloud/blob/6369eace/libcloud/loadbalancer/drivers/gce.py
----------------------------------------------------------------------
diff --git a/libcloud/loadbalancer/drivers/gce.py b/libcloud/loadbalancer/drivers/gce.py
index 75f18a5..61aee22 100644
--- a/libcloud/loadbalancer/drivers/gce.py
+++ b/libcloud/loadbalancer/drivers/gce.py
@@ -97,7 +97,7 @@ class GCELBDriver(Driver):
         pool, then adding the members to the target pool.
 
         :param  name: Name of the new load balancer (required)
-        :type   ``str``
+        :type   name: ``str``
 
         :param  port: Port or range of ports the load balancer should listen
                       on, defaults to all ports.  Examples: '80', '5000-5999'


Mime
View raw message