Add docs for procuring GCE creds

docs/conf.py

@@ -55,7 +55,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'cloudbridge'
-copyright = u'2017, GVL and Galaxy Projects'
+copyright = u'2019, GVL and Galaxy Projects'
 author = u'GVL and Galaxy Projects'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -63,9 +63,9 @@ author = u'GVL and Galaxy Projects'
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '1.0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '1.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/topics/overview.rst

@@ -6,6 +6,7 @@ Introductions to all the key parts of CloudBridge you'll need to know:
    :maxdepth: 1
 
     How to install CloudBridge <install.rst>
+    Procuring access credentials <procuring_credentials.rst>
     Connection and authentication setup <setup.rst>
     Launching instances <launch.rst>
     Networking <networking.rst>

docs/topics/procuring_credentials.rst

@@ -1,27 +1,28 @@
-
 Procuring access credentials
-----------------------------
-To initialize a connection to a cloud and get a provider object, you will
-need to provide the cloud's access credentials to CloudBridge. This page
-will walk you through the process of procuring credentials. For more
-information on providing these credentials to CloudBridge, see
-`Providing Access Credentials <setup.html>`_.
+============================
+
+To initialize a connection to a cloud and get a provider object, you will need
+to provide the cloud's access credentials to CloudBridge. This page will walk
+you through the process of procuring credentials on different providers. For
+more information on using the obtained credentials with CloudBridge, see
+`Connection and Authentication Setup <setup.html>`_ page.
 
 .. _azure-creds:
 
 Microsoft Azure
-~~~~~~~~~~~~~~~
+---------------
 
-The page linked below from the Microsoft Documentation was used to create this
+The page linked below from the Microsoft documentation was used to create this
 section, and can be followed instead of this CloudBridge-specific documentation
-to procure Azure credentials for other purposes.
-https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal
+to procure Azure credentials
+https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal.
 
-In order to follow the isntructions below, one needs a Microsoft Azure
-account and Subscription, as well as portal access.
-The following section will walk you through the process of creating an
-application, which is required for API access, as well as help you locate
-all required Azure credentials for CloudBridge.
+In order to follow the instructions below, one needs a Microsoft Azure account
+and an active Subscription, as well as web portal access:
+https://portal.azure.com/ The following section will walk you through the
+process of creating an application, which is required for API access, as well
+as help you locate all required Azure credentials for API access via
+CloudBridge.
 
 Azure credentials require a `Subscription ID` which can be procured through
 `Subscriptions` in the Azure portal.
@@ -46,8 +47,8 @@ procured through the Azure Active Directory's `Properties`.
    :alt: Azure Directory 1
 
    The `Azure Active Directory` can be access by searching, or by choosing
-   `Azure Active Directory` in the `All Services` window. `Azure Active
-   Directory` is also a default favorite on the sidebar
+   `Azure Active Directory` in the `All Services` window.
+   `Azure Active Directory` is also a default favorite on the sidebar.
 
 .. figure:: captures/az-dir-2.png
    :alt: Azure Directory 2
@@ -57,16 +58,16 @@ procured through the Azure Active Directory's `Properties`.
 
 In order to access the API, an application needs to be registered and a key
 needs to be created. After creating an application through the
-`App Registrations` window under the `Active Directory`, the `Application
-ID` of the app will correspond to the `Client ID` in CloudBridge, and the
+`App Registrations` window under the `Active Directory`, the `Application ID`
+of the app will correspond to the `Client ID` in CloudBridge, and the
 generated value of its key, will correspond to the `Secret`.
 
 
 .. figure:: captures/az-app-1.png
    :alt: Azure App 1
 
-   `App Registrations` can be access by searching, or through choosing `App
-   Registrations` under `Azure Active Directory`
+   `App Registrations` can be access by searching, or through choosing
+   `App Registrations` under `Azure Active Directory`.
 
 .. figure:: captures/az-app-2.png
    :alt: Azure App 2
@@ -85,26 +86,26 @@ generated value of its key, will correspond to the `Secret`.
    :alt: Azure App 4
 
    After creating the application, one must select it, after which the
-   `Application ID` will map to the `Client ID` in CloudBridge
+   `Application ID` will map to the `Client ID` in CloudBridge.
 
 .. figure:: captures/az-app-5.png
    :alt: Azure App 5
 
    In the application's `Settings` panel, under the `Keys` section, one will
-   be able to create a new `Secret`
+   be able to create a new `Secret`.
 
 .. figure:: captures/az-app-6.png
    :alt: Azure App 6
 
    Any name can be given to the key, and any expiration date, after which
    the `Save` button will generate the `Key` which will correspond to the
-   `Secret` in CloudBridge
+   `Secret` in CloudBridge.
 
 .. figure:: captures/az-app-7.png
    :alt: Azure App 7
 
    The value of the key will correspond to the `Secret` in CloudBridge and
-   needs to be saved at creation-time
+   needs to be saved at creation-time.
 
 
 Finally, in order to have appropriate permissions, you must assign an
@@ -119,34 +120,64 @@ specific roles can also be assigned for more limited access.
    :alt: Azure Roles 1
 
    Subscription-level access will allow the application to access resources
-   from multiple resource groups
+   from multiple resource groups.
 
 .. figure:: captures/az-role-2.png
    :alt: Azure Roles 2
 
    When roles are set at the level of the Resource Group, one must specify
    this Resource Group as part of the credentials, as the application will
-   not have enough permissions to create a Resource Group
+   not have enough permissions to create a Resource Group.
 
 .. figure:: captures/az-role-3.png
    :alt: Azure Roles 3
 
    Adding a role assignment to the application will give it appropriate
-   permissions to manage resources
+   permissions to manage resources.
 
 .. _google-creds:
 
-Google Compute Engine
-~~~~~~~~~~~~~~~~~~~~~
+Google Compute Engine (GCE)
+---------------------------
+
+For Google Compute Engine (GCE), create a service account followed by creating
+and downloading a key. Additional instructions are available at this link
+https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating_a_service_account.
+
+Start off by clicking on the `Create Service Account` button on the
+IAM & admin section of the Google Cloud Console:
+https://console.cloud.google.com/iam-admin/serviceaccounts.
+
+.. figure:: captures/gce-sa-1.png
+   :alt: GCE Service Account 1
+
+Next, we provide a name for the service account and an informative description.
+Note that the supplied name is used to create an email address for the service
+account. Once created, this email cannot be changed.
+
+.. figure:: captures/gce-sa-2.png
+   :alt: GCE Service Account 2
 
-For Google Compute Engine, create a service account following instructions
-from the link below:
-https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating_a_service_account
+We then assign a role to the service account. Depending on what you will be
+doing with the service account, and CloudBridge, you can set granular access
+roles for the service account. The `Editor` role on the project is very broad
+and will allow you to exercise all of the CloudBridge capabilities.
 
-Once created, grant the account appropriate permissions for your use through
-roles, and create a key, choosing JSON format, when prompted. These
-credentials can then be used with CloudBridge through the variables shown
-in the sections below.
+.. figure:: captures/gce-sa-3.png
+   :alt: GCE Service Account 3
+
+After a service account has been created, we need to add a key to it.
+
+.. figure:: captures/gce-sa-4.png
+   :alt: GCE Service Account key 1
+
+Finally, choose the JSON format for the key when prompted. The file that is
+downloaded will be used with CloudBridge through the variables shown
+on the `Connection and Authentication Setup <setup.html>`_ page. Note that you
+may have multiple keys associated with the same service account.
+
+.. figure:: captures/gce-sa-5.png
+   :alt: GCE Service Account key 2
 
 The JSON credentials file will have a similar form to the example shown
 below, and can either be passed through an absolute path to the file, or
@@ -167,3 +198,8 @@ through a variable containing the JSON dictionary itself.
       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
       "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-name%40my-project.iam.gserviceaccount.com"
     }
+
+
+.. Comments for documentation authors:
+.. When uploading pictures, process them using sips, as follows:
+.. sips -s format png -Z 1500 img-name.png