What Is Canary Deployment?

Canary deployment gradually rolls out a new version to a small subset of users or servers first, monitoring for problems before rolling it out to everyone.

Published November 18, 2026

Canary deployment releases a new version to a small share of users first (say 5%), watches metrics, then gradually increases traffic or rolls back. It limits the impact of bad releases.

The concept

Both versions run side by side; the router sends a small percentage of traffic to the canary. Errors, latency and business metrics decide whether to continue.

Automation (Argo Rollouts, Flagger, service meshes) can promote or abort based on thresholds.

Gradual rollout

step 1: v1 95% | v2 5% watch errors
step 2: v1 75% | v2 25%
step 3: v1 0% | v2 100%
on errors → back to v1 100%

Practical examples

Nginx split by weight

split_clients $request_id $upstream {
  5%  canary;
  *   stable;
}

Kubernetes replica ratio

kubectl scale deploy web-stable --replicas=19
kubectl scale deploy web-canary --replicas=1

Abort rule

If 5xx rate > 1% or p95 latency +30% → roll back automatically

Common mistakes

  • Canary traffic too small to reveal problems.
  • No metrics to judge the canary.
  • Incompatible database changes.

Key takeaways

  • Release to a small slice first.
  • Decide with metrics.
  • Roll back automatically.

FAQ

Where does the name come from?

Canaries in coal mines warned miners of danger early.

Feature flags vs canary?

Flags control features per user; canary controls which version runs.

More General articles