Azure procuring credentials added

docs/topics/aws_mapping.rst

@@ -35,7 +35,6 @@ and the below screenshot shows how the switch between the various services.
 +------------------------+-----+
 
 .. figure:: captures/aws-services-dash.png
-   :scale: 50 %
    :alt: EC2, VPC, and S3
 
    Resources in AWS are separated into three dashboards depending on the
@@ -44,25 +43,18 @@ and the below screenshot shows how the switch between the various services.
 
 AWS - Labeled Resources
 -----------------------
-+------------------------+-------------------+----------------+----------------+----------+
-| Labeled Resource       | AWS Resource Type | CB ID          | CB Name        | CB Label |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSInstance            | Instance          | Instance ID    | Instance ID    | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSMachineImage        | AMI               | AMI ID         | AMI Name       | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSNetwork             | VPC               | VPC ID         | VPC ID         | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSSubnet              | Subnet            | Subnet ID      | Subnet ID      | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSRouter              | Route Table       | Route Table ID | Route Table ID | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSVolume              | Volume            | Volume ID      | Volume ID      | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSSnapshot            | Snapshot          | Snapshot ID    | Snapshot ID    | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
-| AWSVMFirewall          | Security Group    | Group ID       | Group Name     | tag:Name |
-+------------------------+-------------------+----------------+----------------+----------+
+================ ================= ============== ============== ========
+Labeled Resource AWS Resource Type CB ID          CB Name        CB Label
+================ ================= ============== ============== ========
+AWSInstance      Instance          Instance ID    Instance ID    tag:Name
+AWSMachineImage  AMI               AMI ID         AMI Name       tag:Name
+AWSNetwork       VPC               VPC ID         VPC ID         tag:Name
+AWSSubnet        Subnet            Subnet ID      Subnet ID      tag:Name
+AWSRouter        Route Table       Route Table ID Route Table ID tag:Name
+AWSVolume        Volume            Volume ID      Volume ID      tag:Name
+AWSSnapshot      Snapshot          Snapshot ID    Snapshot ID    tag:Name
+AWSVMFirewall    Security Group    Group ID       Group Name     tag:Name
+================ ================= ============== ============== ========
 
 The resources listed above are labeled, they thus have both the `name` and
 `label` properties in CloudBridge. These resources require a mandatory `label`
@@ -81,7 +73,6 @@ The below screenshots will help map these properties to AWS objects in the
 web portal.
 
 .. figure:: captures/aws-instance-dash.png
-   :scale: 50 %
    :alt: name, ID, and label properties for AWS EC2 Instances
 
    The CloudBridge `name` and `ID` properties map to the unchangeable
@@ -91,7 +82,6 @@ web portal.
    column.
 
 .. figure:: captures/az-ami-dash.png
-   :scale: 50 %
    :alt: name, ID, and label properties for AWS EC2 AMIs
 
    When an AWS resource allows for an unchangeable name, the CloudBridge
@@ -102,16 +92,14 @@ web portal.
 
 
 AWS - Unlabeled Resources
----------------------------
-+-----------------------+--------------------+-------+---------+----------+
-| Unlabeled Resource    | AWS Resource Type  | CB ID | CB Name | CB Label |
-+-----------------------+--------------------+-------+---------+----------+
-| AWSKeyPair            | Key Pair           | Name  | Name    | -        |
-+-----------------------+--------------------+-------+---------+----------+
-| AWSBucket             | Bucket             | Name  | Name    | -        |
-+-----------------------+--------------------+-------+---------+----------+
-| AWSBucketObject       | Bucket Object      | Key   | Key     | -        |
-+-----------------------+--------------------+-------+---------+----------+
+-------------------------
+================== ================= ===== ======= ========
+Unlabeled Resource AWS Resource Type CB ID CB Name CB Label
+================== ================= ===== ======= ========
+AWSKeyPair         Key Pair          Name  Name    -
+AWSBucket          Bucket            Name  Name    -
+AWSBucketObject    Bucket Object     Key   Key     -
+================== ================= ===== ======= ========
 
 The resources listed above are unlabeled. They thus only have the `name`
 property in CloudBridge. These resources require a mandatory `name`
@@ -123,7 +111,6 @@ support a `name` parameter for the `find` method in their corresponding
 services.
 
 .. figure:: captures/aws-bucket.png
-   :scale: 50 %
    :alt: list of buckets on AWS dashboard
 
    Buckets can be found in the Amazon S3 portal. BucketObjects are contained
@@ -131,16 +118,14 @@ services.
 
 
 AWS - Special Unlabeled Resources
------------------------------------
-+--------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| Unlabeled Resource | AWS Resource Type      | CB ID | CB Name                                                                | CB Label |
-+--------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| AWSFloatingIP      | Elastic IP             | ID    | [public_ip]                                                            | -        |
-+--------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| AWSInternetGateway | Internet Gateway       | ID    | tag:Name                                                               | -        |
-+--------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| AWSVMFirewallRule  | Network Security Rules | ID    | Generated: [direction]-[protocol]-[from_port]-[to_port]-[cidr]-[fw_id] | -        |
-+--------------------+------------------------+-------+------------------------------------------------------------------------+----------+
+---------------------------------
+================== ====================== ===== ====================================================================== ========
+Unlabeled Resource AWS Resource Type      CB ID CB Name                                                                CB Label
+================== ====================== ===== ====================================================================== ========
+AWSFloatingIP      Elastic IP             ID    [public_ip]                                                            -
+AWSInternetGateway Internet Gateway       ID    tag:Name                                                               -
+AWSVMFirewallRule  Network Security Rules ID    Generated: [direction]-[protocol]-[from_port]-[to_port]-[cidr]-[fw_id] -
+================== ====================== ===== ====================================================================== ========
 
 While these resources are similarly unlabeled, they do not follow the same
 general rules as the ones listed above. Firstly, they differ by the fact

docs/topics/azure_mapping.rst

@@ -1,25 +1,18 @@
 Azure - Labeled Resources
 -------------------------
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| Labeled CloudBridge Resource          | Azure Resource Type    | CB ID | CB Name                | CB Label                           |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureInstance                         | Virtual Machine        | ID    | Name                   | tag:Label                          |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureMachineImage (Private)           | Image                  | ID    | Name                   | tag:Label                          |
-| AzureMachineImage (Marketplace Image) | VirtualMachineImage    | ID    | URN                    | URN                                |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureNetwork                          | Virtual Network        | ID    | Name                   | tag:Label                          |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureSubnet                           | Subnet                 | ID    | NetworkName/SubnetName | Network:tag:SubnetLabel_SubnetName |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureRouter                           | Route Table            | ID    | Name                   | tag:Label                          |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureVolume                           | Disk                   | ID    | Name                   | tag:Label                          |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureSnapshot                         | Snapshot               | ID    | Name                   | tag:Label                          |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
-| AzureVMFirewall                       | Network security group | ID    | Name                   | tag:Label                          |
-+---------------------------------------+------------------------+-------+------------------------+------------------------------------+
+===================================== ====================== ===== ====================== ==================================
+Labeled CloudBridge Resource          Azure Resource Type    CB ID CB Name                CB Label                           
+===================================== ====================== ===== ====================== ==================================
+AzureInstance                         Virtual Machine        ID    Name                   tag:Label
+AzureMachineImage (Private)           Image                  ID    Name                   tag:Label                          
+AzureMachineImage (Marketplace Image) VirtualMachineImage    ID    URN                    URN                                
+AzureNetwork                          Virtual Network        ID    Name                   tag:Label                          
+AzureSubnet                           Subnet                 ID    NetworkName/SubnetName Network:tag:SubnetLabel_SubnetName 
+AzureRouter                           Route Table            ID    Name                   tag:Label                          
+AzureVolume                           Disk                   ID    Name                   tag:Label                          
+AzureSnapshot                         Snapshot               ID    Name                   tag:Label                          
+AzureVMFirewall                       Network security group ID    Name                   tag:Label                          
+===================================== ====================== ===== ====================== ==================================
 
 The resources listed above are labeled, they thus have both the `name` and
 `label` properties in CloudBridge. These resources require a mandatory `label`
@@ -37,7 +30,6 @@ necessity in AWS. As such, the VMFirewall creation method requires a
 a tag with the key `network_id`.
 
 .. figure:: captures/az-label-dash.png
-   :scale: 50 %
    :alt: name and label properties in Azure portal
 
    The CloudBridge `name` property always maps to the unchangeable resource
@@ -47,7 +39,6 @@ a tag with the key `network_id`.
    pointed out in the screenshot above.
 
 .. figure:: captures/az-net-id.png
-   :scale: 50 %
    :alt: network id in Azure portal
 
    The CloudBridge `ID` property most often maps to the Resource ID in Azure,
@@ -55,7 +46,6 @@ a tag with the key `network_id`.
    screenshot shows where to find a resource's ID in Azure's web portal.
 
 .. figure:: captures/az-net-label.png
-   :scale: 50 %
    :alt: network label in Azure portal
 
    The CloudBridge `label` property most often maps to the tag with key
@@ -121,7 +111,6 @@ below screenshots will show how to find Subnets and their labels in the
 Azure web portal.
 
 .. figure:: captures/az-subnet-name.png
-   :scale: 50 %
    :alt: subnet name in Azure portal
 
    The CloudBridge `name` property for Subnets corresponds to the
@@ -133,7 +122,6 @@ Azure web portal.
    rather nested within a Network, in the Subnets tab as shown above.
 
 .. figure:: captures/az-subnet-label.png
-   :scale: 50 %
    :alt: subnet label in Azure portal
 
    The CloudBridge `label` property most often maps to the tag with key
@@ -146,15 +134,13 @@ Azure web portal.
 
 Azure - Unlabeled Resources
 ---------------------------
-+--------------------+----------------------------------------+-------+---------+----------+
-| Unlabeled Resource | Azure Resource Type                    | CB ID | CB Name | CB Label |
-+--------------------+----------------------------------------+-------+---------+----------+
-| AzureKeyPair       | StorageAccount:Table                   | Name  | Name    | -        |
-+--------------------+----------------------------------------+-------+---------+----------+
-| AzureBucket        | StorageAccount:BlobContainer           | Name  | Name    | -        |
-+--------------------+----------------------------------------+-------+---------+----------+
-| AzureBucketObject  | StorageAccount:BlobContainer:BlockBlob | Name  | Name    | -        |
-+--------------------+----------------------------------------+-------+---------+----------+
+================== ====================================== ===== ======= ========
+Unlabeled Resource Azure Resource Type                    CB ID CB Name CB Label
+================== ====================================== ===== ======= ========
+AzureKeyPair       StorageAccount:Table                   Name  Name    -        
+AzureBucket        StorageAccount:BlobContainer           Name  Name    -        
+AzureBucketObject  StorageAccount:BlobContainer:BlockBlob Name  Name    -        
+================== ====================================== ===== ======= ========
 
 The resources listed above are unlabeled. They thus only have the `name`
 property in CloudBridge. These resources require a mandatory `name`
@@ -166,7 +152,6 @@ resources support a `name` parameter for the `find` method in their
 corresponding services.
 
 .. figure:: captures/az-storacc.png
-   :scale: 50 %
    :alt: storage account in Azure portal
 
    Bucket and Key Pair objects are different than other resources in Azure,
@@ -180,15 +165,13 @@ corresponding services.
 
 Azure - Special Unlabeled Resources
 -----------------------------------
-+-------------------------+------------------------+--------------------+--------------------+----------+
-| Unlabeled Resource      | Azure Resource Type    | CB ID              | CB Name            | CB Label |
-+-------------------------+------------------------+--------------------+--------------------+----------+
-| AzureFloatingIP         | Public IP Address      | ID                 | [public_ip]        | -        |
-+-------------------------+------------------------+--------------------+--------------------+----------+
-| AzureInternetGateway    | None                   | cb-gateway-wrapper | cb-gateway-wrapper | -        |
-+-------------------------+------------------------+--------------------+--------------------+----------+
-| AzureVMFirewallRule     | Network Security Rules | ID                 | name               | -        |
-+-------------------------+------------------------+--------------------+--------------------+----------+
+==================== ====================== ================== ================== ========
+Unlabeled Resource   Azure Resource Type    CB ID              CB Name            CB Label
+==================== ====================== ================== ================== ========
+AzureFloatingIP      Public IP Address      ID                 [public_ip]        -
+AzureInternetGateway None                   cb-gateway-wrapper cb-gateway-wrapper -
+AzureVMFirewallRule  Network Security Rules ID                 name               -
+==================== ====================== ================== ================== ========
 
 While these resources are similarly unlabeled, they do not follow the same
 general rules as the ones listed above. Firstly, they differ by the fact

docs/topics/os_mapping.rst

@@ -1,24 +1,17 @@
 OpenStack - Labeled Resources
------------------------
-+------------------------+------------------------+-----------+----------------+----------+
-| Labeled Resource       | OS Resource Type       | CB ID     | CB Name        | CB Label |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackInstance      | Instance               | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackMachineImage  | Image                  | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackNetwork       | Network                | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackSubnet        | Subnet                 | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackRouter        | Router                 | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackVolume        | Volume                 | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackSnapshot      | Snapshot               | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
-| OpenStackVMFirewall    | Security Group         | ID        | ID             | Name     |
-+------------------------+------------------------+-----------+----------------+----------+
+-----------------------------
+===================== ================ ===== ======= ========
+Labeled Resource      OS Resource Type CB ID CB Name CB Label
+===================== ================ ===== ======= ========
+OpenStackInstance     Instance         ID    ID      Name
+OpenStackMachineImage Image            ID    ID      Name
+OpenStackNetwork      Network          ID    ID      Name
+OpenStackSubnet       Subnet           ID    ID      Name
+OpenStackRouter       Router           ID    ID      Name
+OpenStackVolume       Volume           ID    ID      Name
+OpenStackSnapshot     Snapshot         ID    ID      Name
+OpenStackVMFirewall   Security Group   ID    ID      Name
+===================== ================ ===== ======= ========
 
 The resources listed above are labeled, they thus have both the `name` and
 `label` properties in CloudBridge. These resources require a mandatory `label`
@@ -38,7 +31,6 @@ the description, by appending the following string to the user-provided descript
 (if any) at creation: "[CB-AUTO-associated-network-id: associated_net_id]"
 
 .. figure:: captures/os-instance-dash.png
-   :scale: 50 %
    :alt: name, ID, and label properties for OS Instances
 
    The CloudBridge `name` and `ID` properties map to the unchangeable
@@ -48,16 +40,14 @@ the description, by appending the following string to the user-provided descript
 
 
 OpenStack - Unlabeled Resources
----------------------------
-+-----------------------+------------------------+-------+---------+----------+
-| Unlabeled Resource    | OS Resource Type       | CB ID | CB Name | CB Label |
-+-----------------------+------------------------+-------+---------+----------+
-| OpenStackKeyPair      | Key Pair               | Name  | Name    | -        |
-+-----------------------+------------------------+-------+---------+----------+
-| OpenStackBucket       | Object Store Container | Name  | Name    | -        |
-+-----------------------+------------------------+-------+---------+----------+
-| OpenStackBucketObject | Object                 | Name  | Name    | -        |
-+-----------------------+------------------------+-------+---------+----------+
+-------------------------------
+===================== ====================== ===== ======= ========
+Unlabeled Resource    OS Resource Type       CB ID CB Name CB Label
+===================== ====================== ===== ======= ========
+OpenStackKeyPair      Key Pair               Name  Name    -
+OpenStackBucket       Object Store Container Name  Name    -        
+OpenStackBucketObject Object                 Name  Name    -
+===================== ====================== ===== ======= ========
 
 The resources listed above are unlabeled. They thus only have the `name`
 property in CloudBridge. These resources require a mandatory `name`
@@ -69,7 +59,6 @@ support a `name` parameter for the `find` method in their corresponding
 services.
 
 .. figure:: captures/os-kp-dash.png
-   :scale: 50 %
    :alt: KeyPair details on OS dashboard
 
    KeyPairs and other unlabeled resources in OpenStack have `name` that is
@@ -78,16 +67,14 @@ services.
 
 
 OpenStack - Special Unlabeled Resources
------------------------------------
-+--------------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| Unlabeled Resource       | OS Resource Type       | CB ID | CB Name                                                                | CB Label |
-+--------------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| OpenStackFloatingIP      | Floating IP            | ID    | [public_ip]                                                            | -        |
-+--------------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| OpenStackInternetGateway | Network `public`       | ID    | 'public'                                                               | -        |
-+--------------------------+------------------------+-------+------------------------------------------------------------------------+----------+
-| OpenStackVMFirewallRule  | Security Group Rule    | ID    | Generated: [direction]-[protocol]-[from_port]-[to_port]-[cidr]-[fw_id] | -        |
-+--------------------------+------------------------+-------+------------------------------------------------------------------------+----------+
+---------------------------------------
+======================== =================== ===== ====================================================================== ========
+Unlabeled Resource       OS Resource Type    CB ID CB Name                                                                CB Label
+======================== =================== ===== ====================================================================== ========
+OpenStackFloatingIP      Floating IP         ID    [public_ip]                                                            -
+OpenStackInternetGateway Network `public`    ID    'public'                                                               -
+OpenStackVMFirewallRule  Security Group Rule ID    Generated: [direction]-[protocol]-[from_port]-[to_port]-[cidr]-[fw_id] -
+======================== =================== ===== ====================================================================== ========
 
 While these resources are similarly unlabeled, they do not follow the same
 general rules as the ones listed before. Firstly, they differ by the fact

docs/topics/procuring_credentials.rst

@@ -0,0 +1,161 @@
+
+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>`.
+
+**Microsoft Azure**
+
+For Microsoft Azure, the link below shows how to create service principle
+credentials:
+https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal
+
+After having a Microsoft Azure account, in order to have API access,
+application credentials are needed. The following section will walk you
+through the process of creating and/or locating all required credentials.
+
+Azure credentials require a `Subscription ID` which can be procured through
+`Subscriptions` in the Azure portal.
+
+.. figure:: captures/az-sub-1.png
+   :alt: Azure Subscriptions 1
+
+   Subscriptions can be accessed by searching, or by choosing `Subscriptions`
+   in the `All Services` window
+
+.. figure:: captures/az-sub-2.png
+   :alt: Azure Subscriptions 2
+
+   The `Subscription ID` will be found in the list of subscriptions
+
+
+Another piece of credentials that already exists on any Azure account is a
+`Tenant ID` which will correspond to the `Active Directory ID`, which can be
+procured through the Azure Active Directory's `Properties`.
+
+.. figure:: captures/az-dir-1.png
+   :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
+
+.. figure:: captures/az-dir-2.png
+   :alt: Azure Directory 2
+
+   The `Directory ID` will be found in the Directory's `Properties` section
+
+
+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
+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`
+
+.. figure:: captures/az-app-2.png
+   :alt: Azure App 2
+
+   The `New Application Registration` button will allow users to create a
+   new application
+
+.. figure:: captures/az-app-3.png
+   :alt: Azure App 3
+
+   The `Name` has to be unique within the subscription and will be used to
+   identify the `Application` later on. The `Sign-on URL` can be any
+   URL-looking string. It does not have to point towards anything.
+
+.. figure:: captures/az-app-4.png
+   :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
+
+.. 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`
+
+.. 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
+
+.. 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
+
+
+Finally, in order to have appropriate permissions, you must assign an
+appropriate role to the newly created application. Permissions can be
+assigned at the level of the Subscription, or at the level of each Resource
+Group. `Contributor` access is recommended for general use in order to have
+sufficient permissions to create and manage all types of resources, but
+specific roles can also be assigned for more limited access.
+
+
+.. figure:: captures/az-role-1.png
+   :alt: Azure Roles 1
+
+   Subscription-level access will allow the application to access resources
+   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
+
+.. 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
+
+
+**Google**
+
+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
+
+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.
+
+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
+through a variable containing the JSON dictionary itself.
+
+
+.. code-block:: json
+
+    {
+      "type": "service_account",
+      "project_id": "my-project",
+      "private_key_id": "b12321312441245gerg245245g42c245g254t425",
+      "private_key": "-----BEGIN PRIVATE KEY-----\nMIICWgIBAAKBgE1EJDPKM/2wck/CZYCS7F2cXoHXDBhXYtdeV+h70Nk+ABs6scAV\nApYoobJAVpDeL+lutYAwtbscNz5K915DiNEkBf48LhfBWc5ea07OnClOGC9zASja\nif6ujIdhbITaNat9rdG939gQWqyaDW4wzYfvurhfmxICNgZA1YpWco1HAgMBAAEC\ngYAc+vLtLelEPNsTSWGS0Qiwr8bOwl75/kTHbM5iF5ak9NlLXT9wQTEgKwtC9VjC\nq2OjFXAkLaDsFlAuICYaCBCXn1nUqNoYhaSEQNwGnWIz376letXg/mX+BALSPMFR\nhE6mbdmaL4OV1X8j8uf2VcrLfVFCCZfhPu/TM5D6bVFYoQJBAJRHNKYU/csAB/NE\nzScJBv7PltOAoYpxbyFZb1rWcV9mAn34382b0YBXbp3Giqvifs/teudUbRpAzzLm\n5gr8tzECQQCFZh4tNIzeZZYUqkQxrxgqnnONey1hX7K+BlGyC6n2o26sE+I7cLij\n2kbuWoSFMAIdM2Hextv9k+ZrwUas4V33AkAfi9Korvib0sLeP7oB3wrM9W9aShiU\nMrP4/WUSh2MRb8uB74v123vD+VYAXTgtf3+JTzYBt1WK61TpuHQizEdRAkBjt8hL\nBoNfJBUicXz0nuyzvyql0jREG+NjhRnAvFNbGSR74Yk14bdEVMC9IFD7tr190pEQ\nlRqR3eNbHWmVhgpVAkBgveeM73R1tFXS6UosBtfDI1zut44Ce0RoADOIxjXqgjOi\nXSrevYvoKCl09yhLNAnKD+QvT/YbshW/jibYXwdj\n-----END PRIVATE KEY-----",
+      "client_email": "service-name@my-project.iam.gserviceaccount.com",
+      "client_id": "13451345134513451345",
+      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+      "token_uri": "https://oauth2.googleapis.com/token",
+      "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"
+    }

docs/topics/setup.rst

@@ -1,77 +1,53 @@
 Setup
 -----
 To initialize a connection to a cloud and get a provider object, you will
-need to provide the cloud's access credentials to CloudBridge. These may
-be provided in one of following ways:
+need to provide the cloud's access credentials to CloudBridge. For more
+details on how to create and find these credentials, see `Procuring Access
+Credentials <procuring_credentials.html>`. Once available, these may be
+provided in one of following ways:
 
 1. Environment variables
 2. A dictionary
 3. Configuration file
 
-Procuring access credentials
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-**Microsoft Azure**
-
-For Microsoft Azure, create service principle credentials following
-instructions from the link below:
-https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-create-service-principal-portal#check-azure-subscription-permissions
-
-**Google**
-
-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
-
-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.
-
-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
-through a variable containing the JSON dictionary itself.
-
-
-.. code-block:: json
-
-    {
-      "type": "service_account",
-      "project_id": "my-project",
-      "private_key_id": "b12321312441245gerg245245g42c245g254t425",
-      "private_key": "-----BEGIN PRIVATE KEY-----\nMIICWgIBAAKBgE1EJDPKM/2wck/CZYCS7F2cXoHXDBhXYtdeV+h70Nk+ABs6scAV\nApYoobJAVpDeL+lutYAwtbscNz5K915DiNEkBf48LhfBWc5ea07OnClOGC9zASja\nif6ujIdhbITaNat9rdG939gQWqyaDW4wzYfvurhfmxICNgZA1YpWco1HAgMBAAEC\ngYAc+vLtLelEPNsTSWGS0Qiwr8bOwl75/kTHbM5iF5ak9NlLXT9wQTEgKwtC9VjC\nq2OjFXAkLaDsFlAuICYaCBCXn1nUqNoYhaSEQNwGnWIz376letXg/mX+BALSPMFR\nhE6mbdmaL4OV1X8j8uf2VcrLfVFCCZfhPu/TM5D6bVFYoQJBAJRHNKYU/csAB/NE\nzScJBv7PltOAoYpxbyFZb1rWcV9mAn34382b0YBXbp3Giqvifs/teudUbRpAzzLm\n5gr8tzECQQCFZh4tNIzeZZYUqkQxrxgqnnONey1hX7K+BlGyC6n2o26sE+I7cLij\n2kbuWoSFMAIdM2Hextv9k+ZrwUas4V33AkAfi9Korvib0sLeP7oB3wrM9W9aShiU\nMrP4/WUSh2MRb8uB74v123vD+VYAXTgtf3+JTzYBt1WK61TpuHQizEdRAkBjt8hL\nBoNfJBUicXz0nuyzvyql0jREG+NjhRnAvFNbGSR74Yk14bdEVMC9IFD7tr190pEQ\nlRqR3eNbHWmVhgpVAkBgveeM73R1tFXS6UosBtfDI1zut44Ce0RoADOIxjXqgjOi\nXSrevYvoKCl09yhLNAnKD+QvT/YbshW/jibYXwdj\n-----END PRIVATE KEY-----",
-      "client_email": "service-name@my-project.iam.gserviceaccount.com",
-      "client_id": "13451345134513451345",
-      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
-      "token_uri": "https://oauth2.googleapis.com/token",
-      "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"
-    }
-
 
 Providing access credentials through environment variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The following environment variables must be set, depending on the provider in use.
 
+
 **Amazon**
 
-===================  ==================
-Mandatory variables  Optional Variables
-===================  ==================
+===================
+Mandatory variables
+===================
 AWS_ACCESS_KEY
 AWS_SECRET_KEY
-===================  ==================
+===================
+
 
 **Openstack**
 
-===================  ==================
-Mandatory variables  Optional Variables
-===================  ==================
-OS_AUTH_URL			 NOVA_SERVICE_NAME
-OS_USERNAME			 OS_COMPUTE_API_VERSION
-OS_PASSWORD			 OS_VOLUME_API_VERSION
-OS_PROJECT_NAME      OS_STORAGE_URL
-OS_REGION_NAME       OS_AUTH_TOKEN
-===================  ==================
+===================
+Mandatory variables
+===================
+OS_AUTH_URL
+OS_USERNAME
+OS_PASSWORD
+OS_PROJECT_NAME
+OS_REGION_NAME
+===================
+
+=======================
+Optional Variables
+=======================
+NOVA_SERVICE_NAME
+OS_COMPUTE_API_VERSION
+OS_VOLUME_API_VERSION
+OS_STORAGE_URL
+OS_AUTH_TOKEN
+=======================
+
 
 **Microsoft Azure**
 
@@ -87,27 +63,43 @@ when initializing the relevant services. This operation similarly requires a
 "contributor" or "owner" role.
 For more information on roles, see: https://docs.microsoft.com/en-us/azure/role-based-access-control/overview
 
-======================  ==================
-Mandatory variables     Optional Variables
-======================  ==================
-AZURE_SUBSCRIPTION_ID   AZURE_REGION_NAME
-AZURE_CLIENT_ID         AZURE_RESOURCE_GROUP
-AZURE_SECRET            AZURE_STORAGE_ACCOUNT
-AZURE_TENANT            AZURE_VM_DEFAULT_USER_NAME
-                        AZURE_PUBLIC_KEY_STORAGE_TABLE_NAME
-======================  ==================
+======================
+Mandatory variables
+======================
+AZURE_SUBSCRIPTION_ID
+AZURE_CLIENT_ID
+AZURE_SECRET
+AZURE_TENANT
+======================
+
+====================================
+Optional Variables
+====================================
+AZURE_REGION_NAME
+AZURE_RESOURCE_GROUP
+AZURE_STORAGE_ACCOUNT
+AZURE_VM_DEFAULT_USER_NAME
+AZURE_PUBLIC_KEY_STORAGE_TABLE_NAME
+====================================
 
 
 **Google**
 
-=======================  ==================
-Mandatory variables      Optional Variables
-=======================  ==================
-GCE_SERVICE_CREDS_FILE   GCE_PROJECT_NAME
-           or            GCE_DEFAULT_ZONE
-GCE_SERVICE_CREDS_DICT   GCE_REGION_NAME
-=======================  ==================
+=======================
+Mandatory variables
+=======================
+GCE_SERVICE_CREDS_FILE
+or
+GCE_SERVICE_CREDS_DICT
+=======================
 
+==================
+Optional Variables
+==================
+GCE_PROJECT_NAME
+GCE_DEFAULT_ZONE
+GCE_REGION_NAME
+==================
 
 
 Once the environment variables are set, you can create a connection as follows:
@@ -145,6 +137,7 @@ will override environment values.
 Some optional configuration values can only be provided through the config
 dictionary. These are listed below for each provider.
 
+
 **CloudBridge**
 
 ====================  ==================