Deploying to GKE

This page explains how to deploy an application to Kubernetes using Cloud Build.

Cloud Build provides a gke-deploy builder that enables you to deploy a containerized application to a GKE cluster.

gke-deploy is a wrapper around kubectl, the command-line interface for Kubernetes. It applies Google's recommended practices for deploying applications to Kubernetes by:

  • Updating the application's Kubernetes configuration to use the container image's digest instead of a tag.

  • Adding recommended labels to the Kubernetes configuration.

  • Retrieving credentials for the GKE clusters to which you're deploying the image.

  • Waiting for the Kubernetes configuration that was submitted to be ready.

If you want to deploy your applications using kubectl directly and do not need additional functionality, Cloud Build also provides a kubectl builder that you can use to deploy your application to a GKE cluster.

Before you begin

  • Create a GKE cluster, if you do not have one yet.

  • Have your containerized application in the form of source code and a Dockerfile ready.

  • You'll need at least one Kubernetes configuration file describing the Kubernetes resources used to run your application. If you do not have Kubernetes configuration files, use the following steps to generate one for your application:

    1. Open the Kubernetes Engine clusters page in the Google Cloud console.
    2. On the Kubernetes Engine clusters page, click Deploy.
    3. Select your container and click Continue. You will see the Configuration section.
    4. Under Configuration YAML, click View YAML to get a sample Kubernetes config file.

Required IAM permissions

Add the Google Kubernetes Engine Developer role to your account:

  1. Open the Cloud Build Settings page:

    Open the Cloud Build Settings page

    You'll see the Service account permissions page:

    Screenshot of the Service account permissions page

  2. Set the status of the Kubernetes Engine Developer role to Enabled.

Deploying a pre-built container image

To deploy a particular version of your application with gke-deploy:

  1. Make sure your Kubernetes configuration file is referring to the correct container image tag or digest.

  2. Add the gke-deploy step in your build configuration file:

    YAML

    steps:
    ...
    # deploy container image to GKE
    - name: "gcr.io/cloud-builders/gke-deploy:stable"
      args:
      - run
      - --filename=[KUBERNETES_CONFIG_FILE]
      - --location=[LOCATION]
      - --cluster=[CLUSTER]
    

    JSON

    {
      "steps": [
        {
          "name": "gcr.io/cloud-builders/gke-deploy:stable",
          "args": [
            "run",
            "--filename=[KUBERNETES_CONFIG_FILE]",
            "--location=[LOCATION]",
            "--cluster=[CLUSTER]"
          ]
        }
      ]
    }
    

    Where:

    • [KUBERNETES_CONFIG_FILE], the file path of your Kuberentes configuration file or the directory path containing your Kubernetes configuration files.
    • [CLUSTER], the name of the GKE cluster that the application will be deployed to.
    • [LOCATION], the region/zone of the cluster.
  3. Start your build:

    gcloud builds submit --project=[PROJECT_ID] --config [BUILD_CONFIG]
    

    Where:

    • [PROJECT_ID], the ID for your project.
    • [BUILD_CONFIG], the name of your build configuration file.

Building and deploying a new container image

To build a new container image and deploy the new container image:

  1. Update your Kubernetes configuration file with the new container image using the --image attribute:

    YAML

    steps:
      # build the container image
    - name: "gcr.io/cloud-builders/docker"
      args: ["build", "-t", "gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]", "."]
      # push container image
    - name: "gcr.io/cloud-builders/docker"
      args: ["push", "gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]"]
      # deploy container image to GKE
    - name: "gcr.io/cloud-builders/gke-deploy:stable"
      args:
      - run
      - --filename=[KUBERNETES_CONFIG_FILE]
      - --image=gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]
      - --location=[LOCATION]
      - --cluster=[CLUSTER]
    

    JSON

    {
      "steps": [
        {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
            "build",
            "-t",
            "gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]",
            "."
          ]
        },
        {
          "name": "gcr.io/cloud-builders/docker",
          "args": [
            "push",
            "gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]"
          ]
        },
        {
          "name": "gcr.io/cloud-builders/gke-deploy:stable",
          "args": [
            "run",
            "--filename=[KUBERNETES_CONFIG_FILE]",
            "--image=gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]",
            "--location=[LOCATION]",
            "--cluster=[CLUSTER]"
          ]
        }
      ]
    }
    

    Where:

    • [PROJECT_ID], the ID for your project.
    • [IMAGE], the desired name of the container image, usually the application name.
    • [TAG], the tag of the container image.
      • If you are building a new container image with each commit, a good practice is to use the commit short SHA as a tag. Cloud Build makes this available as a default substitution, $SHORT_SHA.
    • [KUBERNETES_CONFIG_FILE], the file path of your Kuberentes configuration file or the directory path containing your Kubernetes configuration files.
    • [CLUSTER], the name of the GKE cluster that the application.
    • [LOCATION], the region/zone of the cluster will be deployed to.
  2. Start your build:

    gcloud builds submit --project=[PROJECT_ID] --config [BUILD_CONFIG]
    

    Where:

    • [PROJECT_ID], the ID for your project.
    • [BUILD_CONFIG], the name of your build configuration file.

Automating deployments

You can automate the deployment of your application to GKE by creating a trigger in Cloud Build. You can configure triggers to build and deploy images whenever you push changes to your code.

To create a build trigger:

  1. Open the build triggers page:

    Open the Build triggers page

  2. Select your project and click Open.

  3. Click Create trigger.

  4. Select the repository that contains your source code and build configuration file.

  5. Enter a name and description for your trigger.

  6. Select a Trigger type.

  7. Choose a Build configuration for your trigger.

    1. If you choose a Cloud Build configuration file, you can specify Substitution variables by providing a variable name and the value you want to associate with that variable. In the example below, the user-defined substitution variable _CLOUDSDK_CONTAINER_CLUSTER specifies the cluster to deploy to, and the user-defined substitution variable _CLOUDSDK_COMPUTE_ZONE specifies its location. If you want to deploy to a different cluster, you can use the same build configuration and only need to change the values of the substitution variables:

      YAML

      steps:
      ...
      # deploy container image to GKE
      - name: "gcr.io/cloud-builders/gke-deploy:stable"
        args:
        - run
        - --filename=[KUBERNETES_CONFIG_FILE]
        - --image=gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]
        - --location=${_CLOUDSDK_COMPUTE_ZONE}
        - --cluster=${_CLOUDSDK_CONTAINER_CLUSTER}
      

      JSON

      {
        "steps": [
          {
            "name": "gcr.io/cloud-builders/gke-deploy:stable",
            "args": [
              "run",
              "--filename=[KUBERNETES_CONFIG_FILE]",
              "--image=gcr.io/[PROJECT_ID]/[IMAGE]:[TAG]",
              "--location=${_CLOUDSDK_COMPUTE_ZONE}",
              "--cluster=${_CLOUDSDK_CONTAINER_CLUSTER}"
            ]
          }
        ]
      }
      

      To learn more about how to define substitutions for build configuration files, see Using user-defined substitutions.

  8. Click Create trigger to save your build trigger.

When you push code to your repository, Cloud Build will automatically trigger a build. To learn more about build triggers, see Creating and managing build triggers.

What's next