This page explains how to deploy an application to Kubernetes usingCloud Build.

Cloud Build provides agke-deploy builder that enables you to deploy a containerized application to aGKE cluster.

gke-deploy is a wrapper aroundkubectl, the command-line interface forKubernetes. It applies Google's recommended practices for deploying applicationsto Kubernetes by:

• Updating the application's Kubernetes resource file to use the containerimage's digest instead of a tag.

• Addingrecommended labels to the Kubernetes resource file.

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

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

If you want to deploy your applications usingkubectl directly and do not needadditional functionality, Cloud Build also provides akubectl builder that you can use to deploy your application to aGKE cluster.

Before you begin

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

• Have your containerized application in the form of source code and aDockerfile ready. Your source code needs to be stored in a repository, such asCloud Source Repositories, GitHub, or Bitbucket.

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

  1. Open theKubernetes Engine clusters page in the Google Cloud console.
  2. On the Kubernetes Engine clusters page, clickDeploy.
  3. Select your container and clickContinue. You will see the Configurationsection.
  4. Under Configuration YAML, clickView YAML to get a sample Kubernetesresource file.
  Note: If you already have another form of templated Kubernetes resource filesuch as a Helm chart or a resource in Kustomize format, see thehelm builder orkustomize builder for examples of build configurations you canuse for deployment.

1. In the Google Cloud console, go to thesettings Cloud BuildPermissions page:

   Go toPermissions

2. Set the status of theKubernetes Engine Developer role toEnabled.

Deploying a prebuilt container image

To deploy a particular version of your application withgke-deploy:

1. Make sure your Kubernetes resource file is referring to thecorrect container image tag or digest.

2. Add thegke-deploy step in yourbuild configuration file:

   YAML

   steps:...# deploy container image to GKE-name:"gcr.io/cloud-builders/gke-deploy"args:-run---filename=kubernetes-resource-file---location=location---cluster=cluster

   JSON

   {"steps":[{"name":"gcr.io/cloud-builders/gke-deploy","args":["run","--filename=kubernetes-resource-file","--location=location","--cluster=cluster"]}]}

   Where:

   • kubernetes-resource-file is the file path of your Kubernetes resourcefile or the directory path containing your Kubernetes resource files.
   • cluster is the name of the GKE cluster that the applicationwill be deployed to.
   • location is the region/zone of the cluster.

   For more information on available flags, seegke-deploy run flags.

   Note: When deploying to multiple GKE clusters,Cloud Build persists the home directory across build steps,which means that thekubectl context of the previous step to be used bysubsequent steps by default. To avoid this, add an environment variabledeclaration,KUBECONFIG=/tmp/kubeconfig, to each step of your buildconfig file.

3. Start your build:

   gcloudbuildssubmit--region=REGION--project=project-id--configbuild-config

   Where:

   • project-id is the ID for your project.
   • build-config is the name of your build configuration file.
   • REGION is one of thesupported build regions.

Building and deploying a new container image

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

1. Update your Kubernetes resource file with the new containerimage 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"args:-run---filename=kubernetes-resource-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","args":["run","--filename=kubernetes-resource-file","--image=gcr.io/project-id/image:tag","--location=location","--cluster=cluster"]}]}

   Where:

   • project-id is the ID for your project.
   • image is the desired name of the container image, usually the applicationname.
   • tag is the tag of the container image.
     • If you are building a new container image with each commit, a good practiceis to use the commit short SHA as a tag. Cloud Build makes thisavailable as adefault substitution,$SHORT_SHA.
   • kubernetes-resource-file is the file path of your Kubernetes resourcefile or the directory path containing your Kubernetes resource files.
   • cluster is the name of the GKE cluster that the applicationwill be deployed to.
   • location is the region/zone of the cluster will be deployed to.
   Note:gke-deploy can only reference one image in your build configurationfile. If your Kubernetes resource files contain multiple imagereferences, only the images beginning withgcr/project-id/image willbe updated to reference the specified tag.

2. Start your build:

   gcloudbuildssubmit--region=REGION--project=project-id--configbuild-config

   Where:

   • project-id is the ID for your project.
   • build-config is the name of your build configuration file.
   • REGION is one of thesupported build regions.

Automating deployments

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

To create a build trigger:

1. Open theTriggers page in the Google Cloud console:

   Open the Triggers page

2. Select your project from the project selector drop-down menu at the top of the page.

3. ClickOpen.

4. ClickCreate trigger.

   On theCreate trigger page, enter the following settings:

   1. Enter a name for your trigger.

   2. Select the repository event to start your trigger.

   3. Select the repository that contains your source code and build config file.

   4. Specify the regex for the branch or tag name that will start your trigger.ee

   5. Choose aConfiguration for your trigger.

      If you choose a Cloud Build configuration file, you can specifySubstitution 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"args:-run---filename=kubernetes-resource-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","args":["run","--filename=kubernetes-resource-file","--image=gcr.io/project-id/image:tag","--location=${_CLOUDSDK_COMPUTE_ZONE}","--cluster=${_CLOUDSDK_CONTAINER_CLUSTER}"]}]}

      Where:

      • kubernetes-resource-file is the file path ofyour Kubernetes configuration file or the directory path containingyour Kubernetes resource files.
      • project-id is the ID for your project.
      • image is the desired name of the container image, usually the application name.
      • tag is the tag of the container image.

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

5. ClickCreate to save your build trigger.

When you push code to your repository, Cloud Build will automaticallytrigger a build. To learn more about build triggers, seeCreating and managingbuild triggers.

What's next

• Learn how toconfigure automated deployments for your workloads on GKE.
• Learn how tocreate a GitOps-style CI/CD pipeline deploying toGKE with Cloud Build.
• Learn about additionalgke-deploy options.
• Learn how toperform blue/green deployments on Compute Engine.
• Learn about additionalCloud builders.
• Learn how totroubleshoot build errors.