Google Container Engine clarifications (#2142)

* update code block languages * rewrite intro and remove whitespace * rewrite prerequisites * add CircleCI 2.0 project as prerequisite * update bullet style * rewrite "Base Image" section * update product to google kubernetes engine * add links to authenticate GCP doc * add additional environment variable section * rename GOOGLE_AUTH * clarify where to add variables * update decode and store service account step * add dollar sign to env vars * various typos, newlines and sundry * remove dollar signs Environment variables should not be prefixed with dollar signs unless they are used explicitly in a bash command. * clean and clarify authentication step * minor typo in google auth doc * rewrite configuration walkthrough Clarify why we're using "_json_key" as the username. Properly indent steps within a deploy job. * add final commands for gcloud config * be more explicit about auth differences for images
circleci · Mar 14, 2018 · 18e0082 · 18e0082
1 parent 6b3822f
commit 18e0082
Show file tree

Hide file tree

Showing 2 changed files with 82 additions and 46 deletions.
diff --git a/jekyll/_cci2/google-auth.md b/jekyll/_cci2/google-auth.md
@@ -10,6 +10,7 @@ Before you can use the `gcloud` command line tool with CircleCI, you must authen
 
 ## Prerequisites
 
+- A CircleCI 2.0 project.
 - A Google account.
 - A Google Cloud Platform project.
 
@@ -25,7 +26,7 @@ Go to Google's [Getting Started with Authentication][] article and follow the in
 2. In the CircleCI application, go to your project's settings by clicking the gear icon in the top right.
 3. In the **Build Settings** section, click **Environment Variables**, then click the **Add Variable** button.
 4. Name the variable. In this example, the variable is named `$GCLOUD_SERVICE_KEY`.
-5. Paste the contents from Step 2 into the **Value** field.
+5. Paste the contents from Step 1 into the **Value** field.
 6. Click the **Add Variable** button.
 
 ### Decode and Store Service Account

diff --git a/jekyll/_cci2/google-container-engine.md b/jekyll/_cci2/google-container-engine.md
@@ -1,75 +1,110 @@
 ---
 layout: classic-docs
-title: "Deploying to Google Container Engine"
-short-title: "Deploying to Google Container Engine"
+title: "Deploying to Google Kubernetes Engine"
+short-title: "Deploying to Google Kubernetes Engine"
 categories: [containerization]
-description: "Deploying to Google Container Engine with CircleCI 2.0."
+description: "Deploying to Google Kubernetes Engine with CircleCI 2.0."
 order: 60
 ---
 
-*[Deploy]({{ site.baseurl }}/2.0/deployment-integrations/) > Using Google Container Engine*
+*[Deploy]({{ site.baseurl }}/2.0/deployment-integrations/) > Deploying to Google Kubernetes Engine*
 
-In order to use Google Cloud, you will need to ensure that the [Google Cloud SDK](https://cloud.google.com/sdk/) is installed on your primary container as described in the following sections:
-
-* TOC
-{:toc}
+In order to deploy to Google Kubernetes Engine (GKE),
+you must install the [Google Cloud SDK](https://cloud.google.com/sdk/) in your primary container.
 
 ## Prerequisites
 
-This document makes the following assumptions:
+- A CircleCI 2.0 project.
+- A working knowledge of Docker and building Docker images.
+- A registered Google Cloud Platform (GCP) project. Keep the project name handy.
+- A GKE cluster connected to your GCP project. Keep the cluster name handy.
+
+## Steps
+
+### Select a Base Image
 
-1. You have a working knowledge of Docker and building Docker images.
-1. You already have a GCP project registered. Keep the project name handy.
-1. A Container Engine cluster has already been created in your GCP project. Keep the cluster name handy.
-1. Your repository has already been configured as a CircleCI 2.0 project.
+If Debian is an acceptable operating system for your primary container,
+consider using Google's base image.
+You can find this image on DockerHub as [`google/cloud-sdk`](https://hub.docker.com/r/google/cloud-sdk/).
+Otherwise, follow the [SDK installation instructions](https://cloud.google.com/sdk/) for your base image's operating system.
 
-## Selecting a Base Image
-If Debian is acceptable as a base for your custom primary container, Google's [`google/cloud-sdk`](https://hub.docker.com/r/google/cloud-sdk/) image can be a good base image to use.
+### Authenticate `gcloud`
 
-For those with more complicated custom primary containers, follow the [installation instructions](https://cloud.google.com/sdk/) for the operating system of your base image.
+Before you can use the `gcloud` command line tool with CircleCI,
+you must authenticate it.
+To do this,
+follow the instructions in the [Authenticating Google Cloud Platform]({{ site.baseurl }}/2.0/google-auth/) document.
+After completing these steps,
+you should have created an environment variable called `GCLOUD_SERVICE_KEY`.
+Using this particular name is not required,
+but it will be used throughout the examples in this document.
 
-## Setting Up Authentication
+### Add More Environment Variables
 
-### Generating a Service Account Key
-After the Google Cloud SDK has been integrated into your primary container (see above), authentication can be achieved with the use of a [service account](https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow). Ensure that you follow the Google Cloud documentation for generating a service account, or create a new key for an existing service account, saving the credentials as a JSON key.
+For convenience, add three more environment variables to your project:
 
-Paste this into a new environment variable's "Value" field, using the name `GOOGLE_AUTH`. Using this particular name is not required, but will be used throughout the examples in this document.
+- `GOOGLE_PROJECT_ID`: the ID of your GCP project
+- `GOOGLE_COMPUTE_ZONE`: the default [compute zone](https://cloud.google.com/compute/docs/regions-zones/)
+- `GOOGLE_CLUSTER_NAME`: the target cluster for all deployments
 
-Next, simply set up three more environment variables for convenience:
+### Authenticate to Google's Container Registry
 
-* `GOOGLE_PROJECT_ID`: the ID of your GCP project
-* `GOOGLE_CLUSTER_NAME`: the cluster to which deployments will occur
-* `GOOGLE_COMPUTE_ZONE`: which compute zone to use by default, e.g. `us-central1-a`
+If you chose the `google/cloud-sdk` image,
+no authentication is needed since this is a public image.
 
-### Setting Up a Job Step to Decode Credentials
-Once the `GOOGLE_AUTH` environment variable has been saved to your project, it will be readily available for use in the steps of your job's primary container. 
+```yaml
+version: 2
+jobs:
+  deploy-job:
+    docker:
+      - image: google/cloud-sdk
+```
 
-**config.yml**
+If you are using a custom image,
+authenticate to Google's Container Registry (GCR).
+Since you are [using a JSON key file](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file),
+use the `auth` key in `config.yml`
+to specify credentials:
+
+```yaml
+version: 2
+jobs:
+  deploy-job:
+    docker:
+      - image: gcr.io/project/image-name
+        auth:
+          username: _json_key  # default username when using a JSON key file to authenticate
+          password: $GCLOUD_SERVICE_KEY  # encoded service account you created
+```
 
-```yml
-docker: 
-  - image: gcr.io/project/image-name
-    auth:
-    #Put the contents of keyfile.json into an environment variable for the build called GCR_CREDS, which is then passed in.
-      username: _json_key
-      password: $GOOGLE_AUTH 
-  - steps:
-     # ...
-     - run:
-       name: Dump Google Cloud Credentials to file
-       command: echo ${GOOGLE_AUTH} > ${HOME}/gcp-key.json
-     # ...  
+### Add a Job Step to Decode Credentials
+
+To authenticate the `gcloud` tool,
+add a job step to decode the `GCLOUD_SERVICE_KEY` environment variable:
+
+```yaml
+version: 2
+jobs:
+  deploy-job:
+    docker:
+      - image: google/cloud-sdk
+    steps:
+      - run:
+        name: Decode and Store Service Account
+        command: echo $GCLOUD_SERVICE_KEY | base64 --decode --ignore-garbage > ${HOME}/gcloud-service-key.json
 ```
 
-## Configuring `gcloud`
+### Configure `gcloud`
 
-As part of your deployment commands, configure `gcloud` to use the newly-configured service account and set up the appropriate defaults:
+Finally, as part of your deployment commands,
+update `gcloud`, authenticate, and set appropriate defaults for your project:
 
-```sh
-gcloud auth activate-service-account --key-file ${HOME}/gcp-key.json
+```bash
+gcloud --quiet components update
+gcloud auth activate-service-account --key-file=${HOME}/gcloud-service-key.json
 gcloud --quiet config set project ${GOOGLE_PROJECT_ID}
 gcloud --quiet config set compute/zone ${GOOGLE_COMPUTE_ZONE}
 gcloud --quiet container clusters get-credentials ${GOOGLE_CLUSTER_NAME}
 ```
 
-
+Refer to the [Google Cloud](https://circleci.com/docs/2.0/deployment-integrations/#google-cloud) deploy example for further steps.