Fixed up the GCP deployment guide for CLI v0.6 (kubeflow#1021)

* WIP Fixing up the GCP deployment guide for CLI.

* Further updates during CLI deployment testing.

* More tweaks to wording for clarity.

Author: sarahmaddox

content/docs/gke/deploy/deploy-cli.md

@@ -16,8 +16,10 @@ Before installing Kubeflow on the command line:
 
 1. Ensure you have installed the following tools:
 
-    * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
-    * [gcloud](https://cloud.google.com/sdk/)
+  * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+  * [gcloud](https://cloud.google.com/sdk/). If you already have `gcloud`
+    installed, run `gcloud components update` to
+     get the latest version of all your installed Cloud SDK components.
 
 1. If you're using
   [Cloud Shell](https://cloud.google.com/shell/), enable 
@@ -70,16 +72,18 @@ Follow these steps to deploy Kubeflow:
 
     ```bash
     # The following command is optional, to make kfctl binary easier to use.
-    export PATH=$PATH:<path to kfctl in your kubeflow installation>
-    export ZONE=<your target zone> #where the deployment will be created
+    export PATH=$PATH:<path to your kfctl file>
+    export ZONE=<your target GCP zone> # where the deployment will be created
 
     export PROJECT=<your GCP project ID>
     
-    # The value of KFAPP must consist of lower case alphanumeric characters or '-', and must start and end with an alphanumeric character. (For example,  'kubeflow-test' or 'kfw-test'.)
+    # Set KFAPP to the name of your Kubeflow application. See detailed
+    # description in the text below this code snippet.
+    # For example,  'kubeflow-test' or 'kfw-test'.
     export KFAPP=<your choice of application directory name>
-    # Default uses Cloud IAP:
+    # Run this command for the default installation which uses Cloud IAP:
     kfctl init ${KFAPP} --platform gcp --project ${PROJECT}
-    # Alternatively, use this command if you want to use basic authentication:
+    # Alternatively, run this command if you want to use basic authentication:
     kfctl init ${KFAPP} --platform gcp --project ${PROJECT} --use_basic_auth -V
 
     cd ${KFAPP}
@@ -90,6 +94,9 @@ Follow these steps to deploy Kubeflow:
      configurations to be stored. This directory is created when you run
      `kfctl init`. If you want a custom deployment name, specify that name here.
      The value of this variable becomes the name of your deployment.
+     The value of KFAPP must consist of lower case alphanumeric characters or
+     '-', and must start and end with an alphanumeric character.
+     For example,  'kubeflow-test' or 'kfw-test'.
      The value of this variable cannot be greater than 25 characters. It must
      contain just the directory name, not the full path to the directory.
      The content of this directory is described in the next section.
@@ -98,37 +105,41 @@ Follow these steps to deploy Kubeflow:
    * **${ZONE}** - You can see a list of zones [here](https://cloud.google.com/compute/docs/regions-zones/#available).
      If you plan to use accelerators, make sure to pick a zone that supports the type you want.
    * When you run `kfctl init` you need to choose to use either IAP or basic 
-     authentication, as described below.
+     authentication, as described above.
    * `kfctl generate all` attempts to fetch your email address from your 
      credential. If it can't find a valid email address, you need to pass a
      valid email address with flag `--email <your email address>`. This email 
      address becomes an administrator in the configuration of your Kubeflow 
      deployment.
 
 
-1. The deployment process creates a separate deployment for your data storage. After
-   running `kfctl apply` you should notice two new [deployments](https://console.cloud.google.com/dm/deployments):
+1. The deployment process creates a separate deployment for your data storage. 
+   After running `kfctl apply` you should notice two new [deployments](https://console.cloud.google.com/dm/deployments):
    * **{KFAPP}-storage**: This deployment has persistent volumes for your
      pipelines.
-   * **{KFAPP}**: This deployment has all the components of Kubeflow, including a [GKE cluster](https://console.cloud.google.com/kubernetes/list) named **${KFAPP}** with Kubeflow installed.
+   * **{KFAPP}**: This deployment has all the components of Kubeflow, including 
+     a [GKE cluster](https://console.cloud.google.com/kubernetes/list) 
+     named **${KFAPP}** with Kubeflow installed.
 
-1. Once the deployment finishes, check the resources installed in the namespace `kubeflow` in your new cluster.  To do this from the command line, first set your `kubectl` credentials to point to the new cluster:
+1. When the deployment finishes, check the resources installed in the namespace
+   `kubeflow` in your new cluster.  To do this from the command line, first set 
+   your `kubectl` credentials to point to the new cluster:
 
     ```
     gcloud container clusters get-credentials ${KFAPP} --zone ${ZONE} --project ${PROJECT}
     ```
 
-   Then, see what's installed in the `kubeflow` *namespace* of your GKE cluster:
+   Then see what's installed in the `kubeflow` namespace of your GKE cluster:
 
     ```
-    kubectl -n kubeflow get  all
+    kubectl -n kubeflow get all
     ```
 
-
-1. Kubeflow will be available at the following URI:
+1. Access the Kubeflow central dashboard at the following URI when it becomes
+  available:
 
     ```
-    https://<deployment_name>.endpoints.<project>.cloud.goog/
+    https://<KFAPP>.endpoints.<project-id>.cloud.goog/
     ```
    * It can take 20 minutes for the URI to become available.
      Kubeflow needs to provision a signed SSL certificate and register a DNS 
@@ -145,9 +156,9 @@ Follow these steps to deploy Kubeflow:
 
 ## Understanding the deployment process
 
-The deployment process is controlled by 4 different commands:
+The `kfctl` deployment process includes by the following commands:
 
-* **init** - one time set up.
+* **init** - performs a one-time setup.
 * **generate** - creates configuration files defining the various resources.
 * **apply** - creates or updates the resources.
 * **delete** - deletes the resources.
@@ -159,7 +170,7 @@ following:
 * **platform** - all GCP resources; that is, anything that doesn't run on 
   Kubernetes.
 * **k8s** - all resources that run on Kubernetes.
-* **all** - GCP and Kubernetes resources.
+* **all** - all GCP and Kubernetes resources.
 
 ### App layout
 
@@ -178,16 +189,20 @@ Your Kubeflow app directory **${KFAPP}** contains the following files and direct
   * The directory is created when you run `kfctl generate platform`.
   * You can modify these configurations to customize your GCP infrastructure.
 
-* **kustomize** is a directory that contains the kustomize packages for Kubeflow applications.
+* **kustomize** is a directory that contains the kustomize packages for Kubeflow 
+  applications. See 
+  [how Kubeflow uses kustomize](/docs/components/misc/kustomize/).
 
   * The directory is created when you run `kfctl generate`.
-  * You can customize the Kubernetes resources (modify the manifests and run `kfctl apply` again).
+  * You can customize the Kubernetes resources by modifying the manifests and 
+    running `kfctl apply` again.
 
 ### GCP service accounts
 
 Creating a deployment using `kfctl` creates three service accounts in your 
-GCP project. These service accounts are created using the principle of least 
-privilege. The three service accounts are:
+GCP project. These service accounts are created using the [principle of least 
+privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege). 
+The three service accounts are:
 
 * `${KFAPP}-admin` is used for some admin tasks like configuring the load 
   balancers. The principle is that this account is needed to deploy Kubeflow but 
@@ -196,7 +211,7 @@ privilege. The three service accounts are:
   GCP resources (Cloud Storage, BigQuery, etc.). This account has a much smaller 
   set of privileges compared to `admin`.
 * `${KFAPP}-vm` is used only for the virtual machine (VM) service account. This
-  account has minimal permissions, needed to send metrics and logs to 
+  account has the minimal permissions needed to send metrics and logs to 
   [Stackdriver](https://cloud.google.com/stackdriver/).
 
 ## Next steps

content/docs/gke/deploy/oauth-setup.md

@@ -10,7 +10,7 @@ when deploying Kubeflow on GCP,
 then you must follow these instructions to create an OAuth client for use
 with Kubeflow.
 
-You can skip the instructons on this page if you want to use basic 
+You can skip the instructions on this page if you want to use basic 
 authentication (username and password) with Kubeflow instead of Cloud IAP.
 Cloud IAP is recommended for production deployments or deployments with access 
 to sensitive data.
@@ -42,50 +42,57 @@ address to verify the user's identity.
       alt="OAuth consent screen"
       class="mt-3 mb-3 p-3 border border-info rounded">
 
-1. On the [credentials tab](https://console.cloud.google.com/apis/credentials):
+1. On the [credentials screen](https://console.cloud.google.com/apis/credentials):
    * Click **Create credentials**, and then click **OAuth client ID**.
    * Under **Application type**, select **Web application**.
    * In the **Name** box enter any name for your OAuth client ID. This is *not*
      the name of your application nor the name of your Kubeflow deployment. It's
      just a way to help you identify the OAuth client ID.
 
-1. You need to click create 
-
-   * You will see a dialog box like the one below
+1. Click **Create**. A dialog box appears, like the one below:
 
      <img src="/docs/images/new-oauth.png" 
       alt="OAuth consent screen"
       class="mt-3 mb-3 p-3 border border-info rounded">
 
-   * You should write down the CLIENT_ID because you will need it in the next step
+1. Copy the **client ID** shown in the dialog box, because you need the client
+  ID in the next step.
 
-1. From the credentials tab find your newly created OAuth credential and click the pencil icon to
-   edit
+1. On the **Create credentials** screen, find your newly created OAuth 
+  credential and click the pencil icon to edit it:
    
     <img src="/docs/images/oauth-edit.png" 
      alt="OAuth consent screen"
      class="mt-3 mb-3 p-3 border border-info rounded">
 
-1. In the **Authorized redirect URIs** box, enter the following (if it's not already present
-   in the list of authorized redirect URIs):
+1. In the **Authorized redirect URIs** box, enter the following (if it's not 
+  already present in the list of authorized redirect URIs):
 
     ```
     https://iap.googleapis.com/v1/oauth/clientIds/<CLIENT_ID>:handleRedirect
     ```
-    * `<CLIENT_ID>` is the OAuth client ID, something like `XXX.apps.googleusercontent.com`.
-    * Note that the URI is not dependent on the Kubeflow deployment or endpoint. Multiple Kubeflow
-      deployments can share the same OAuth client without the need to modify the redirect URIs.
+    * `<CLIENT_ID>` is the OAuth client ID, something like 
+      `XXX.apps.googleusercontent.com`. Do not include the angle brackets around
+      the client ID.
+    * Note that the URI is not dependent on the Kubeflow deployment or endpoint. 
+      Multiple Kubeflow deployments can share the same OAuth client without the 
+      need to modify the redirect URIs.
     
-    * Here's an example of the completed form:
-      <img src="/docs/images/oauth-credential.png" 
-        alt="OAuth credentials"
-        class="mt-3 mb-3 p-3 border border-info rounded">
 
 1. Press **Enter/Return** to add the URI. Check that the URI now appears as
   a confirmed item under **Authorized redirect URIs**. (The URI should no longer be
   editable.)
-1. Make note of the **client ID** and **client secret** that appear in the OAuth
-  client window. You need them later to enable Cloud IAP.
+
+    Here's an example of the completed form:
+    <img src="/docs/images/oauth-credential.png" 
+      alt="OAuth credentials"
+      class="mt-3 mb-3 p-3 border border-info rounded">
+
+1. Click **Save**.
+
+1. Make note that you can find your OAuth client credentials in the credentials
+  section of the GCP Console. You need to retrieve the **client ID** and 
+  **client secret** later when you're ready to enable Cloud IAP.
 
 ## Next steps