Helm Canary Deploy
The Helm Canary Deploy step installs a separate Helm release alongside the stable release and waits for canary workloads to reach steady state. Harness derives the canary release name by appending -canary to the stable release name. Insert verification or approval steps after this step before promoting with a Helm Basic Deploy step.
Before you begin
Before you configure the step, make sure you have the following in place:
- A Helm service: Go Helm services to set up a service with a chart source and values files.
- A Helm infrastructure: Go Helm infrastructure to connect a cluster and namespace.
- A Harness delegate in the target cluster: The delegate runs deployment steps in the cluster.
- Runtime configuration: Every Helm stage requires a
runtimeblock specifying a connector and namespace. Go Helm runtime configuration to understand the required fields.
Configure the step
The following parameters are available on the Helm Canary Deploy step.
| Parameter | Description | Required |
|---|---|---|
| Name | Display name for this step in the stage canvas. Default: Helm Canary Deploy. | Required |
| Instance Count | Whether the Instances value represents a pod count or a percentage of the total replicas. | Required |
| Instances | The number of instances (count) or fraction of instances (percentage) to include in the canary release. When set to percentage, enter a value between 1 and 100. | Required |
| Ignore Failed Release History | When enabled, proceeds with deployment even if the previous Helm release has a failed status. Use this to recover from a broken release without manual cleanup. Default: false. | Optional |
| Skip Steady State Check | When enabled, skips waiting for canary workloads to reach ready status after deployment. Default: false. | Optional |
| Run Chart Tests | When enabled, runs helm test against the canary release after a successful deployment. Default: false. | Optional |
| Skip Cleanup | When enabled, skips cleanup of a failed first canary release. Use this to inspect resources left behind after a failed initial install. Default: false. | Optional |
| Print Manifests | When enabled, logs the full rendered chart manifest to the step output with secrets redacted. Default: false. | Optional |
| Server-Side Rendering | When enabled, passes --server to helm template so manifests are rendered against the live cluster rather than locally. Default: false. | Optional |
| Environment Variables | Additional environment variables to pass into the Helm plugin execution. | Optional |
| Command Flags | Additional flags to append to the helm upgrade command, for example --atomic or --cleanup-on-fail. | Optional |
How the step works
When the step runs, it performs the following actions in order:
-
Canary release name generation: Harness derives the canary release name by appending
-canaryto the stable release name. For example, if the stable release isrelease-50fd6a, the canary release isrelease-50fd6a-canary. The canary release name is emitted as an output variable for use in downstream steps. -
Release history check: Runs
helm historyon the canary release name. If no canary release exists, Harness proceeds with a fresh install. If Ignore Failed Release History is enabled and the canary has a failed status, Harness clears it before upgrading. -
Helm upgrade: Runs
helm upgrade --install <canary-release-name> <chart-path>with the resolved instance count or percentage applied. Helm tracks the canary as a separate release with its own revision history. -
Steady state check: Polls the cluster until all canary workloads reach ready status. Skipped if Skip Steady State Check is enabled.
Step outputs
The following output variable is available for use in downstream steps.
| Output variable | Description |
|---|---|
canaryRelease | The name of the canary Helm release. Auto-populates the Release Name field of the Helm Canary Delete step as <+stage.steps.helmCanaryDeployStep.output.outputVariables.canaryRelease>. |
Advanced settings
- Timeout duration: Maximum time the step is allowed to run before being terminated.
- On failure: Define what happens if the step fails, such as retry, mark as success, or abort.
- Strategy: Configure a looping strategy to run this step over a list of values.
- Conditional execution: Run this step only when a specified condition is true.
Next steps
- Go Helm canary deployment to understand the full canary deployment flow.
- Go Helm Canary Delete to configure the step that removes the canary release after validation.
- Go Helm Rollback to review the rollback step reference.