Deploying to Google Kubernetes Engine

Deploy > Deploying to Google Kubernetes Engine

In order to deploy to Google Kubernetes Engine (GKE), you must install the Google Cloud SDK in your primary container.


  • 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.


Select a Base Image

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. Otherwise, follow the SDK installation instructions for your base image’s operating system.

Authenticate gcloud

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 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.

Add More Environment Variables

For convenience, add three more environment variables to your project:

  • GOOGLE_PROJECT_ID: the ID of your GCP project
  • GOOGLE_COMPUTE_ZONE: the default compute zone
  • GOOGLE_CLUSTER_NAME: the target cluster for all deployments

Authenticate to Google’s Container Registry

If you chose the google/cloud-sdk image, no authentication is needed since this is a public image.

version: 2
      - image: google/cloud-sdk

If you are using a custom image, authenticate to Google’s Container Registry (GCR). Since you are using a JSON key file, use the auth key in config.yml to specify credentials:

version: 2
      - image:
          username: _json_key  # default username when using a JSON key file to authenticate
          password: $GCLOUD_SERVICE_KEY  # JSON service account you created

Add a Job Step to Decode Credentials

To authenticate the gcloud tool, add a job step to transfer the contents of GCLOUD_SERVICE_KEY into a local file.

version: 2
      - image: google/cloud-sdk
      - run:
        name: Store Service Account
        command: echo $GCLOUD_SERVICE_KEY > ${HOME}/gcloud-service-key.json

Configure gcloud

Finally, as part of your deployment commands, update gcloud, authenticate, and set appropriate defaults for your project.

gcloud --quiet components update  # remove if using the google/cloud-sdk image
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}

Note: If you are using Google’s official Docker image, the built-in updater is disabled, and gcloud --quiet components update will fail. To use the latest components, use the google/cloud-sdk:latest image.

Refer to the Google Cloud deploy example for further steps.