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 <[email protected]> Authored: Fri Jan 17 05:05:40 2014 -0800 Committer: Rick Wright <[email protected]> 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'
