Roll Out with a Canary
Move traffic to a new version in steps, and let each step continue only after it has stayed ready for a bake time and its tests have passed. Use it for user-facing services where problems show only under real traffic.
On this page
Works with: OpenKruise Rollout and the Kuberik openkruise-controller. Install it with the Helm chart’s integrations.openkruise.enabled, or on its own:
kubectl apply --server-side -f https://github.com/kuberik/openkruise-controller/releases/latest/download/install.yamlInstall OpenKruise Rollout itself from the OpenKruise installation guide.
Define the canary steps
An OpenKruise Rollout splits a Deployment into steps; each step sets the canary’s replicas and share of traffic. Set a bake time per step with an annotation:
apiVersion: rollouts.kruise.io/v1beta1
kind: Rollout
metadata:
name: hello-world
namespace: hello-world
annotations:
rollout.kuberik.io/step-1-bake-time: "5m"
rollout.kuberik.io/step-1-ready-timeout: "10m"
spec:
workloadRef:
apiVersion: apps/v1
kind: Deployment
name: hello-world
strategy:
canary:
steps:
- replicas: 1
traffic: 10%
- replicas: 5
traffic: 50%
trafficRoutings:
- service: hello-world
gateway:
httpRouteName: hello-world| Annotation | Effect |
|---|---|
rollout.kuberik.io/step-<N>-bake-time | How long step N must stay ready before it continues |
rollout.kuberik.io/step-<N>-ready-timeout | How long step N may take to become ready before the rollout stops and waits for you |
N is 1-based and counts the steps in order. A step with neither a bake time nor a RolloutTest is never approved by Kuberik: it stays paused until you approve it in OpenKruise. A step with tests and no bake time continues when its tests pass. When Flux applies this Rollout from a Kustomization that a Kuberik Rollout drives, a failed bake on the Kuberik Rollout also stops the canary at its current step. See the OpenKruise canary strategy for every step option.
Run tests at a step
A RolloutTest runs a Job when the canary reaches a step. The step continues only if the Job succeeds; if it fails, the step stays paused until you retry or skip the test.
apiVersion: rollout.kuberik.com/v1alpha1
kind: RolloutTest
metadata:
name: smoke-test
namespace: hello-world
spec:
rolloutName: hello-world # the OpenKruise Rollout
stepIndex: 1
jobTemplate:
backoffLimit: 0
template:
spec:
restartPolicy: Never
containers:
- name: test
image: curlimages/curl
command: ["curl", "--fail", "http://hello-world-canary"]jobTemplate is a Kubernetes Job spec, and stepIndex is 1-based like the annotations. Create one RolloutTest per step you want to test.
Retry or skip a failed test
A failed test stops the step and sets Stalled=True with reason RolloutTestFailed on the OpenKruise Rollout, but that alone does not fail the Kuberik deploy, and a retry does nothing until the deploy has failed. Retry and skip therefore need two things: the Kuberik Rollout drives the Flux Kustomization that applies the OpenKruise Rollout, and it selects a kustomization HealthCheck for that Kustomization. With wait: false, that check reads the stalled OpenKruise Rollout as failed, so the deploy fails.
Retry the failed deploy from the dashboard’s Retry button, or with the rollout.kuberik.com/retry annotation on the Kuberik Rollout, and the failed tests at the current step run again. To let the step continue without them, also set rollouttest.kuberik.com/retry-mode: skip; the failed tests are marked Skipped and count as passed.
kubectl -n hello-world annotate rollouts.kuberik.com hello-world \
rollouttest.kuberik.com/retry-mode=skip rollout.kuberik.com/retry=true --overwriteCheck the result
Each test reports its phase: WaitingForStep, Pending, Running, Succeeded, Failed, Cancelled or Skipped.
kubectl -n hello-world get rollouttests -o custom-columns=NAME:.metadata.name,STEP:.spec.stepIndex,PHASE:.status.phaseIn the dashboard, each canary step is a stage of the deploy:


Troubleshoot
| Symptom | Cause | Fix |
|---|---|---|
The canary stops at a step and the OpenKruise Rollout shows Stalled with reason StepReadyTimeoutExceeded | The step was not ready within step-<N>-ready-timeout | Fix the canary pods, then retry the failed deploy on the Kuberik Rollout: a retry restarts the step’s timeout |
A test never leaves WaitingForStep | Its stepIndex is the last step | Move the test to an earlier step |
A test failed (Stalled, reason RolloutTestFailed), and Retry or rollout.kuberik.com/ does nothing | The Kuberik deploy has not failed: no kustomization HealthCheck sees the stalled OpenKruise Rollout | Select a kustomization HealthCheck for the Kustomization that applies the OpenKruise Rollout |
| A step stays paused with no test and no failure | The step has no step-<N>-bake-time and no RolloutTest | Add a bake time or a test for that step, or approve it in OpenKruise |