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

    Remember that if you're enabling verify, you need to configure your skaffold.yaml for verification also.

  • Whether there are predeploy or postdeploy jobs for the phase

    If you're enabling predeploy or postdeploy jobs, you need to configure your skaffold.yaml for those jobs.

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: true | false
        predeploy:
          actions: "PREDEPLOY_ACTION"
        postdeploy:
          actions: "POSTDEPLOY_ACTION"
      - …
      - phaseId: "stable"
        percentage: 100
        profiles: [ "LAST_PROFILE_NAME" ]
        verify: true|false
        predeploy:
          actions: "PREDEPLOY_ACTION"
        postdeploy:
          actions: "POSTDEPLOY_ACTION"

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.

  • verify: true|false

    Tells Cloud Deploy whether to include a verify job for the phase. Note that for each phase to use verify, Skaffold uses the same profile for verify that is specified for render and deploy for that phase.

  • PREDEPLOY_ACTION

    Is the same as the ACTION_NAME that you used in your skaffold.yaml to define the custom action you want to run before deploying.

  • POSTDEPLOY_ACTION

    Is the same as the ACTION_NAME that you used in your skaffold.yaml to define the custom action you want to run after deploying.

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