This document describes how to configure and use canary deployments to deployyour applications to GKE or GKE attached clustersusing Cloud Deploy with service-based networking.

A canary deployment is a progressive rollout of a new version of your application,where you gradually increase the percentage of traffic sent to the new version,while monitoring the application's performance. This helps you to catch potentialproblems early and minimize the impact on your users.

How canary deployments work for GKE and GKE attached clusters with service-based networking

1. You provide the name of the Deployment resource and the Service resource.

2. Cloud Deploy creates an additional Deployment resource, withthe name of your current Deployment plus-canary.

Secrets and ConfigMaps are also copied and renamed with-canary.

1. Cloud Deploy modifies the Service to adjust the selector toselect the pods in the current Deployment and the canary pods.

   Cloud Deploy calculates the number of pods to use for thecanary based on the calculation describedin the pod provisioning section. That calculation differs depending onwhether youenable or disable pod overprovisioning.

   If we'reskipping to thestable phaseCloud Deploy adds the labels to be used to match pods, sothey're available for subsequent canary runs.

   Cloud Deploy creates a Deployment that includes thephase-specific percentage of pods, updating it for each phase. This isdone by calculating the number of pods as a percentage of the originalnumber of pods. This can result in an inexact traffic split. If you needan exact traffic split, you can achieve that usingGateway API.

2. During thestable phase, the-canary Deployment is scaled down tozero, and the original Deployment is replaced with the new Deployment.

   Cloud Deploy doesn't modify the original Deployment until thestable phase, unless you disable overprovisioning.

Cloud Deploy provisions pods to achieve the requested canarypercentage as closely as possible. This is based on the number of pods, nottraffic to the pods. If you want your canary to be based on traffic, youneed to useGateway API.

For GKE network-based canary, you canenable or disable pod overprovisioning.The following sections describe how Cloud Deploy calculates thenumber of pods to provision for the canary deployment for each canary phase.

Pod provisioning with overprovisioning enabled

Enabling overprovisioning (disablePodOverprovisioning: false)allows Cloud Deploy to create enough additional pods to run thecanary percentage you want, based on the number of pods running yourexisting deployment. The following formula shows howCloud Deploy calculates the number of pods to provision for thecanary deployment for each canary phase, when pod overprovisioning isenabled:

math.Ceil( percentage * ReplicaCountOfDeploymentOnCluster / (100-percentage))

With this formula, the current replica count (the number of pods you alreadyhave, before this canary) is multiplied by the canary percentage for the phase, and the result of that is divided by (100 minus the percentage).

For example, if you have 4 pods already, and your canary phase is 50%, thenthe number of canary pods is 4. (The result of100-percentage is used as apercentage:100-50=50, treated as.50.)

You can disable overprovisioning (disablePodOverprovisioning: true),to ensure that Cloud Deploy doesn't increase your replica count.

The following formula shows how Cloud Deploy calculates podprovisioning for the canary deployment for each canary phase, when podoverprovisioning is disabled:

math.Ceil( (ReplicaCountOfDeploymentOnCluster + ReplicaCountOfCanaryDeploymentOnCluster) * percentage)

In this formula,ReplicaCountOfCanaryDeploymentOnCluster only exists ifthere was already a canary phase. If this is the first canary phase, thereis noReplicaCountOfCanaryDeploymentOnCluster.

If you begin with 4 pods, that number is multiplied by the canary percentage(for example, 50%, or.5) to get2. So the original deployment is nowscaled down to 2, and 2 new pods are created for the canary deployment. Ifyou then have a 75% canary stage, you have2 (original deployment)+2(first canary stage),*.75, to get3 canary pods and1 pod running theoriginal deployment.

Using Cloud Deploy, you can configure canary deployments toGKE and GKE attached clusters in a single stage or inmultiple stages.

The instructions here include only what is specific to canary configuration. ThedocumentDeploy to a Google Kubernetes Engine cluster has thegeneral instructions for configuring and executing your deployment pipeline.

Make sure you have the required permissions

In addition to other Identity and Access Management permissions you need for usingCloud Deploy, you need the following permissions in order toperform additional actions that might be needed for a canary deployment:

• clouddeploy.rollouts.advance
• clouddeploy.rollouts.ignoreJob
• clouddeploy.rollouts.cancel
• clouddeploy.rollouts.retryJob
• clouddeploy.jobRuns.get
• clouddeploy.jobRuns.list
• clouddeploy.jobRuns.terminate

SeeIAM roles and permissionsfor more information about what available roles include these permissions.

Prepare yourskaffold.yaml

Yourskaffold.yaml file defines how your Kubernetes manifests are rendered anddeployed. For a canary deployment to GKE orGKE attached clusters, ensure it correctly points to your manifests anddefines any necessary build artifacts. No special canary-specific configurationis required withinskaffold.yaml itself beyond what's needed for astandard deployment. You might use Skaffoldprofiles to manage different manifest variations forcustom canary phases.

Prepare your Kubernetes manifests

Your Kubernetes manifests must include both aDeployment resource and aService resource. TheService must define aselector that matches thelabels of the pods managed by theDeployment. The default labelCloud Deploy looks for isapp, but this can be configured in thepipeline.

Configure an automated canary

Configure an automated canary directly within your delivery pipeline definitionfor a specific GKE or GKE attached clusters stageusing standard Kubernetes Service networking.

In the pipeline stage, include astrategy property, as follows:

serialPipeline:stages:-targetId:prodprofiles:[]strategy:canary:runtimeConfig:kubernetes:serviceNetworking:service:"SERVICE_NAME"deployment:"DEPLOYMENT_NAME"podSelectorLabel:"LABEL"canaryDeployment:percentages:[PERCENTAGES]verify:true|falsepredeploy:actions:"PREDEPLOY_ACTION"postdeploy:actions:"POSTDEPLOY_ACTION"

In this configuration...

• SERVICE_NAME is the name of the Kubernetes Service,defined in your manifest.

• DEPLOYMENT_NAME is the name of your KubernetesDeployment, defined in your manifest.

• LABEL is a pod selector label. This must match the labelselector in the Kubernetes Service defined in your manifest. This isoptional. The default isapp.

• PERCENTAGES is a comma-separated list of percentagevalues representing your canary increments, for example[5, 25, 50].

  Also, this doesn't include100, because 100% percent deployment isassumed in the canary, and is handled by thestable phase

• You can enabledeployment verification(verify: true). If you do so, averify job is enabled on each phase.

• PREDEPLOY_ACTION

  Is the same as theACTION_NAME that you used in yourskaffold.yaml to define the custom action you want to run beforedeploying.

• POSTDEPLOY_ACTION

  Is the same as theACTION_NAME that you used in yourskaffold.yaml to define the custom action you want to run afterdeploying.

Configure a custom-automated canary

A custom-automated canary combines custom phase definition (names, percentages,profiles, verify, hooks) with Cloud Deploy's automatic trafficmanagement for GKE or GKE attached clusters. Youdefine the phases, but Cloud Deploy handles the underlying resourcemanipulation based on the percentages and the chosenruntimeConfig.

To configure a custom-automated canary, include both aruntimeConfig sectionwithserviceNetworking and thecustomCanaryDeployment section (definingphaseConfigs) within the strategy.canary block. Cloud Deploy usesthe specified Skaffold profiles for rendering but automatically adjusts trafficaccording to theruntimeConfig and phase percentages.

serialPipeline:stages:-targetId:gke-prodprofiles:[]strategy:canary:# Include runtimeConfig for automatic traffic managementruntimeConfig:kubernetes:serviceNetworking:service:"my-app"deployment:"my-deployment"# Include customCanaryDeployment for phase customizationcustomCanaryDeployment:phaseConfigs:-phaseId:"warmup"percentage:10profiles:["profile-a"]# Profile used for rendering this phaseverify:true-phaseId:"scaling"percentage:50profiles:["profile-b"]# Different profile for this phaseverify:true-phaseId:"stable"percentage:100profiles:["profile-b"]# Can reuse profilesverify:true

Execute the GKE or GKE attached clusters canary

1. Register Pipeline and Targets: Apply your delivery pipeline andGKE or GKE attached clusters target configurationfiles.

   gclouddeployapply--file=delivery-pipeline.yaml--region=REGIONgclouddeployapply--file=gke-targets.yaml--region=REGION

   The delivery pipeline includes the automated or custom canary configuration,for your chosen runtime.

2. Create a Release: Start the deployment, providing the image name.

   gclouddeployreleasescreateRELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--region=REGION# e.g., --images=my-cloudrun-service=gcr.io/my-project/my-app:v1.1# Add --skaffold-file or --source if not using default Skaffold config discovery

   The delivery pipeline identified byPIPELINE_NAMEcontains the automated or custom canary configuration described in thisdocument.

3. Advance the canary:

   gcloud CLI

   gclouddeployrolloutsadvanceROLLOUT_NAME\--release=RELEASE_NAME\--delivery-pipeline=PIPELINE_NAME\--region=REGION

   Where:

   ROLLOUT_NAME is the name of the current rolloutwhich you're advancing to the next phase.

   RELEASE_NAME is the name of the release thatthis rollout is part of.

   PIPELINE_NAME is the name of the deliverypipeline you're using to manage deployment of this release.

   REGION is the name of the region in which therelease was created, for exampleus-central1. This is required.

   See the Google Cloud SDK reference for more information about thegcloud deploy rollouts advance command.

   Google Cloud console

   1. Open the Deliverypipelines page.

   2. Click your pipeline shown in the list of delivery pipelines.

      The Delivery pipeline details page shows a graphical representation ofyour delivery pipeline's progress.

   3. On theRollouts tab, underDelivery pipeline details, clickthe name of your rollout.

      The rollout details page is shown, for that rollout.

      

      Notice that in this example, the rollout has acanary-50 phase and astable phase. Your rollout might have more phases or differentphases.

   4. ClickAdvance rollout.

      The rollout is advanced to the next phase.

Skipped phases

If you deploy a canary and your application has not been deployed to thatruntime yet, Cloud Deploy skips the canary phase and runs the stablephase. SeeSkipping phases the first timeto find out why this happens.

What's next

• Try thecanary deployment quickstart.

• Find out how tomanage the lifecycle of your canary's rollouts.

• Learn more aboutparallel deployment.

• Learn more aboutCloud Deploy deployment strategies.