docs/compute/drivers/gce.rst

Google Compute Engine Driver Documentation
==========================================

`Google 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 minimum)
* Fast VM provisioning
* Persistent block storage (SSD and standard)
* Native Load Balancing

Connecting to Google Compute Engine
-----------------------------------

Libcloud supports three different methods for authenticating:
`Service Account`_, `Installed Application`_ and `Internal Authentication`_.

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.

* If you are running your code on an instance inside Google Compute Engine,
  the GCE driver will consult the internal metadata service to obtain an
  authorization token. The only value required for this type of
  authorization is your Project ID.

Once you have set up the authentication as described below, you pass the
authentication information to the driver as described in `Examples`_. Also
bear in mind that large clock drift (difference in time) between authenticating
host and google will cause authentication to fail.


Service Account
~~~~~~~~~~~~~~~

To set up Service Account authentication, you will need to download the
corresponding private key file in either the new JSON (preferred) format, or
the legacy P12 format.

1. Follow the instructions at
   https://developers.google.com/console/help/new/#serviceaccounts
   to create and download the private key.

   a. If you opt for the new preferred JSON format, download the file and
      save it to a secure location.

   b. If you opt to use the legacy P12 format:

      Convert the private key to a .pem file using the following:
      ``openssl pkcs12 -in YOURPRIVKEY.p12 -nodes -nocerts
      | openssl rsa -out PRIV.pem``

      Move the .pem file to a safe location

2. You will need the Service Account's "Email Address" and the path to the
   key file for authentication.
3. You will also need your "Project ID" (a string, not a numerical value) that
   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" (a string, not a numerical value) that
   can be found by clicking on the "Overview" link on the left sidebar.

Internal Authentication
~~~~~~~~~~~~~~~~~~~~~~~

To use GCE's internal metadata service to authenticate, simply specify
your Project ID and let the driver handle the rest. See the
`5. Using GCE Internal Authorization`_ example below.

Accessing Google Cloud services from your Libcloud nodes
--------------------------------------------------------
In order for nodes created with libcloud to be able to access or manage other
Google Cloud Platform services, you will need to specify a list of Service
Account Scopes.  By default libcloud will create nodes that only allow
read-only access to Google Cloud Storage. A few of the examples below
illustrate how to use Service Account Scopes.

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

4. Specifying Service Account Scopes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: /examples/compute/gce/gce_service_account_scopes.py

5. Using GCE Internal Authorization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. literalinclude:: /examples/compute/gce/gce_internal_auth.py

API Docs
--------

.. autoclass:: libcloud.compute.drivers.gce.GCENodeDriver
    :members:
    :inherited-members:

.. _`Google Compute Engine`: https://cloud.google.com/products/compute-engine/
.. _`Google Developers Console`: https://cloud.google.com/console