Update GCP user docs.

Update all GCP user docs to bring up to standard of equivalent AWS docs.

README.md

@@ -3,9 +3,12 @@
 ## Supported Platforms
 
 * [AWS](docs/user/aws/README.md)
+* [AWS (UPI)](docs/user/aws/install_upi.md)
 * [Azure](docs/user/azure/README.md)
 * [Bare Metal (UPI)](docs/user/metal/install_upi.md)
 * [Bare Metal (IPI) (Experimental)](docs/user/metal/install_ipi.md)
+* [GCP](docs/user/gcp/README.md)
+* [GCP (UPI)](docs/user/gcp/install_upi.md)
 * [Libvirt with KVM](docs/dev/libvirt/README.md) (development only)
 * [OpenStack (experimental)](docs/user/openstack/README.md)
 * [vSphere](docs/user/vsphere/install_upi.md)

docs/user/gcp/dns.md

@@ -39,11 +39,19 @@ authoritative nameservers from the DNS zone records.
 
 ![GCP: Get registrar setup for DNS zone](images/zone_nameserver_records.png)
 
-## Step 4: Update Registrar
+## Step 4a: Root Domain - Update Registrar
 
 Each registrar requires a slightly different procedure. Using the four nameserver values from the previous step,
 you will update the registrar records to the Google Cloud DNS nameservers.
 
+If you are migrating your root domain to Google Cloud DNS, you should migrate existing DNS records:
+
+[GCP: Migrating to Cloud DNS][migrate]
+
+## Step 4b: Subdomain - Perform DNS Delegation
+
+For a subdomain of example.com (e.g. clusters.example.com), you must add delegation records to the parent/root domain. This may require a request to your company's IT department or the division which controls the root domain and DNS services for your company.
 
 [create-dns-zone]: https://cloud.google.com/dns/docs/quickstart
 [lookup-name-servers]: https://cloud.google.com/dns/docs/update-name-servers#look_up_your_name_servers
+[migrate]: https://cloud.google.com/dns/docs/migrating

docs/user/gcp/iam.md

@@ -1,7 +1,5 @@
 # GCP Service Account
-
+To install OpenShift to your GCP project, the installer requires a service account, which provides authentication and authorization to access data in the Google APIs. You can use an existing IAM service account that contains the required roles or create one by following these steps:
-Before proceeding with the OpenShift install, you should create a secondary IAM service account following the steps
-outlined here:
 
 
 ## Step 1: Create a Service Account
@@ -12,7 +10,8 @@ Create a GCP service account using the console or the CLI
 
 ## Step 2: Assign Project Roles to your Service Account
 
-You need to assign the proper roles to the newly created service account so it can be used to create an OpenShift cluster.
+A service account needs to be granted permission for specific APIs in order to access the services used to created a cluster. You can assign the proper roles during or after the creation of a service account. The simplest approach to assigning roles would be to make the service account an Owner of the project, but that service account would then have complete control over the project, which would be a decided risk. Note that service accounts with these roles are only required for installation (and destruction); the [post-install docs](postinstall.md) outline optional steps for removing the roles granted here.
+
 The minimum set of [roles][gcp-roles] you can assign the service account are the following:
 - Compute Admin
 - DNS Administrator
@@ -25,16 +24,15 @@ If you want the OpenShift cluster to create new limited credentials for its own
 role:
 - Service Account Key Admin
 
-Optionally, you can just assign the "Owner" role to your service account.
-
 To assign roles to your service account you may use the console or the CLI:
 
 [GCP: Assign service account roles][sa-assign]
 
+![Add roles to a GCP service account](images/gcp-roles.png)
+
 ## Step 3: Create and save a Service Account Key
 
-You will need to create and save a service account key for your service account so you can use it with the OpenShift
+You will need to create and save a service account key for your service account so you can use it with the OpenShift Installer. You should create the key in JSON format.
-Installer.
 
 [GCP: Creating a service account key][sa-key]
 

docs/user/gcp/install.md

@@ -49,10 +49,12 @@ In your GCP project, there will be a new private DNS zone (for internal lookups)
 
 There will be six running VM instances in the Project.
 
-The nodes within the Virtual Network utilize the internal DNS and use the Router and Internal API load balancers. External/Internet
+The nodes within the Virtual Network utilize the internal DNS and use the Router and External API load balancers. External/Internet
 access to the cluster use the Router and External API load balancers. Compute instances are spread equally across all running availability
 zones for the region.
 
 The OpenShift console is available via the kubeadmin login provided by the installer.
 
+![OpenShift web console](images/install_console.png)
+
 [cloud-install]: https://cloud.openshift.com/clusters/install

docs/user/gcp/limits.md

@@ -1,14 +1,86 @@
 # Handling quota on GCP
-All cloud providers have some concept of limits imposed to protect their services from misuse as well as protect customers from mistakes that can leads to excessive charges.  In GCP these will vary by region, project and account.  This is great news in terms of flexibility but can present an initial hurdle if the defaults in your project are too low.
+Quota limits vary by region, project and account. You can view the limits for your project here:
 
-## Baseline usage
+[GCP: IAM & Admin > Quotas][gcp-console-quota]
-A vanilla IPI installation will result in 24 CPUs, 3 Static IPs and 768 GB of storage consumed.
 
-## Common problems
+## Significant Resource Usage & Quotas
-Be sure to consider cluster growth and consumption from other clusters if using a shared projectd.  The most likely areas of contention are CPU, Static IPs and Storage (SSD) quota.  Whenever an installation fails the installer CLI will return the relevant error message stating which quota was exceeded in a particular region.
+These resources seem to be the most likely to encounter quota limit issues when installing a cluster on GCP. If you encounter a quota issue with a resource not on this list, please [let us know](https://github.com/openshift/installer/issues/new).
+
+### Storage
+A standard OpenShift installation utilizes 768 GB of storage (Persistent Disk SSD). Several regions have a default storage quota of 500 GB, which would cause a minimal installation to fail due to exceeding quotas. 
+
+Regions with a default limit of 500 GB are:
+* asia-east2
+* asia-northeast2
+* asia-south1
+* australia-southeast1
+* europe-north1
+* europe-west2
+* europe-west3
+* europe-west6
+* northamerica-northeast1
+* southamerica-east1
+* us-west2 
+
+If you must install to one of these regions and cannot install to a region with a higher quota, you will need to request a quota increase, as described in [the example below](#increasing-limits).
+
+### Firewall Rules
+An OpenShift cluster utilizes ~40 firewall rules. Some projects may have a quota as low as 200 firewall rules, which would limit the project to a maximum of five cluster installations. You can [check the firewall quota for your project here](https://console.cloud.google.com/iam-admin/quotas?service=compute.googleapis.com&metric=Firewall%20rules&_ga=2.10895548.-966099186.1563042928).
+
+### Compute
+A standard OpenShift installation uses 24 CPUs: each machine (both control-plane and compute) is allotted 4 CPUs. 
+
+Many regions have a default CPU quota limit of 24:
+* asia-east2
+* asia-northeast2
+* asia-south1
+* australia-southeast1
+* europe-north1
+* europe-west2
+* europe-west3
+* europe-west6
+* northamerica-northeast1
+* southamerica-east1
+* us-west2
+
+With these limits, a project can deploy only a single cluster with six total nodes (no further scaling) in these regions. If you need to do more than that in one of these regions with your project, you will need to [increase the limit](#increasing-limits).
+
+Note that these limits are for plain CPUs. All N2 machine-types have a limit of 24 CPUs for [all the regions in which they are available](https://cloud.google.com/compute/docs/regions-zones/#available).
+
+## Other Resource Usage
+### Forwarding Rules
+A standard OpenShift installation creates 2 forwarding rules.
+
+### IP Addresses
+A standard OpenShift installation creates 3 in-use global IP addresses.  
+
+### Networks
+A standard OpenShift instlalation creates 2 networks.
+
+### Routers
+A standard OpenShift installation creates 1 router.
+
+### Routes
+A standard OpenShift installation creates 2 routes.
+
+### Subnetworks
+A standard OpenShift installation creates 2 subnetworks.
+427052
 
 ## Increasing limits
-To adjust quotas visit the [GCP console][gcp-console-quota] and make necessary changes.  This will likely involve filing a support ticket so it's best to plan ahead as this is often the most time consuming barrier to your first running cluster.  For more detailed information please refer to the [GCP documentation][gcp-docs-quota].
+To adjust quotas visit the [GCP Console][gcp-console-quota], select the quotas you wish to edit, and click Edit Quotas. A form will ask for your contact info and the new quota limits. Documentation states most requests are handled within 24 to 48 hours, but it is best to plan ahead and submit these requests as early as possible. Note that requests can only be made through the GCP Console--and not the CLI.
+
+[GCP: Resource Quotas][gcp-docs-quota].
 
 [gcp-console-quota]: https://console.cloud.google.com/iam-admin/quotas
 [gcp-docs-quota]: https://cloud.google.com/compute/quotas
+
+### Example: Using Montréal (northamerica-northeast1)
+The Montréal region is listed above as one of the regions with a storage quota of 500 GB. Attempting to run an OpenShift install on a standard account will result in the error: 
+
+>Error: Error waiting for instance to create: Quota 'SSD_TOTAL_GB' exceeded.  Limit: 500.0 in region northamerica-northeast1. 
+
+
+In order to install to this region it would be necessary to edit the quota and request an increase. 
+![Edit GCP Quota](images/gcp-quota.png)
+Please note that this request description is only an example and cannot guarantee your request will be granted. 

docs/user/gcp/postinstall.md

@@ -1,7 +1,7 @@
 # Service Account: Post Install
 
 If the service account used to create the cluster was given the Owner role or included the Service Account Key Admin role, 
-the service account no longer requires elevated permissions after install. You may change its role to Reader or 
+the service account no longer requires elevated permissions after install. You may change its role to Viewer or 
 remove all roles bound to it. You can perform these steps by revisiting the service account role binding step you performed
 earlier.