Custom Canary Deployments

This document describes how to configure and use custom canary deployments to deploy your applications to all target types using Cloud Deploy.

How custom canary deployments work

When you deploy using a custom canary deployment strategy, Cloud Deploy does not modify your manifests in order to facilitate the chosen traffic-balancing configuration. Instead you are responsible for providing manifests that are applied to your target runtime for each canary phase.

Make sure you have the required permissions

In addition to other Identity and Access Management permissions you need for using Cloud Deploy, you need the following permissions in order to perform 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

See IAM roles and permissions for more information about what available roles include these permissions.

Prepare your skaffold.yaml

Your skaffold.yaml file defines how your manifests are rendered and deployed. For a custom canary deployment you are responsible for defining profiles that are associated with each canary phase in order to facilitate the chosen traffic-balancing configuration. These profiles are mapped to phases in the delivery pipeline strategy configuration.

The following is an example skaffold.yaml configuration used by a custom canary:

apiVersion: skaffold/v4beta7
kind: Config
profiles:
- name: canary-25
  manifests:
    rawYaml:
    - canary-25-resources.yaml
- name: canary-50
  manifests:
    rawYaml:
    - canary-50-resources.yaml
- name: stable
  manifests:
    rawYaml:
    - stable-resources.yaml

Configure a custom canary

With custom canary configuration, you specify the following, in your delivery pipeline definition:

  • Rollout phase names

    In a fully-automated canary, Cloud Deploy names the phases for you (canary-25, canary-75, stable, for example). With a custom canary, however, you can give each phase any name, as long as it's unique among all phases for this canary stage, and it honors resource ID restrictions. But the final (100%) phase name must be stable.

  • Percentage goals for each phase

    Specify the percentages separately, per phase.

  • Skaffold profiles to use for the phase

    You can use a separate Skaffold profile for each phase, or the same profile, or any combination. And each profile can use a different Cloud Run service definition. You can also use more than one profile for a given phase. Cloud Deploy combines them.

  • Whether there is a verify job for the phase

  • Whether there are predeploy or postdeploy jobs for the phase

Custom canary configuration elements

The following YAML shows the configuration for the phases of fully custom canary deployment:

strategy:
  canary:
    # Custom configuration for each canary phase
    customCanaryDeployment:
      phaseConfigs:
      - phaseId: "PHASE1_NAME"
        percentage: PERCENTAGE1
        profiles: [ "PROFILE_NAME" ]
        verify:
          tasks: [TASKS]
        predeploy:
          tasks: [TASKS]
        postdeploy:
          tasks: [TASKS]
      - …
      - phaseId: "stable"
        percentage: 100
        profiles: [ "LAST_PROFILE_NAME" ]
        verify:
          tasks: [TASKS]
        predeploy:
          tasks: [TASKS]
        postdeploy:
          tasks: [TASKS]

In this YAML

  • PHASE1_NAME

    Is the name of the phase. Each phase name must be unique.

  • [ "PROFILE_NAME" ]

    Is the name of the profile to use for the phase. You can use the same profile for each phase, or a different one for each, or any combination. Also, you can specify more than one profile. Cloud Deploy uses all of the profiles you specify, plus the profile or manifest used by the overall stage.

  • stable

    The final phase must be named stable.

  • PERCENTAGE1

    Is the percentage to deploy for the first phase. Each phase must have a unique percentage value, and that value must be a whole percentage (not 10.5, for example), and the phases must be in ascending order.

  • You can enable deployment verification by configuring the verify stanza. If you do so, a verify job is added to the phase.

  • You can enable predeploy hooks by configuring the predeploy stanza. If you do so, a predeploy job is added to the phase.

  • You can enable postdeploy hooks by configuring the postdeploy stanza. If you do so, a postdeploy job is added to the phase.

  • The tasks property under verify, predeploy and postdeploy consists of one or more tasks to run as part of that job. Any configured tasks will run sequentially in the order they are defined.

The percentage for the last phase must be 100. Phases are executed according in the order you configure them in this customCanaryDeployment stanza, but if the percentage values are not in ascending order, the command to register the delivery pipeline fails with an error.

Note that the configuration for a custom canary doesn't include a runtimeConfig stanza. If you include runtimeConfig, it's considered a custom-automated canary.

What's next