What Is a Canary Deployment?

Quick answer
A canary deployment sends a small percentage of traffic to the new version and watches for errors before expanding.
If the canary misbehaves, you roll it back with only a small fraction of users affected.
The technique gets its name from canaries carried into coal mines as early warnings of danger.

What is a canary deployment?

A canary deployment gradually shifts traffic from the current version of a service to a new version, starting with a tiny slice — say 1–5% of users — and increasing only while error rates and latency stay healthy. Because a bad release affects only the canary slice before it affects everyone, it is a core technique of progressive delivery.

How does it work?

Deploy the new version alongside the old. Configure routing so a small, representative share of traffic hits the new version. Compare the canary’s error rate, latency, and business metrics against the baseline for a defined period. If it holds, increase the percentage step by step until 100%; if it degrades, route traffic back to the old version. Tools like Argo Rollouts automate this analysis.

Why does it matter?

A canary bounds the damage of a bad release to a small fraction of users instead of everyone at once. It also surfaces problems that only appear under real traffic — a configuration, capacity, or data issue that tests missed — before they become a full outage.

Where this bites vibecoders
AI assistants often ship “deploy to all users” as the only mode, because a one-shot deploy is simpler to generate than a graduated rollout with analysis. The lesson is that real-user traffic is itself a test environment: route a slice first, and let your metrics — not your confidence — decide when to expand.

Where AI coding assistants get this wrong

Emitting a full-traffic switch with no graduated percentage steps.
Expanding the canary on a timer instead of on error-rate and latency analysis.
Using a non-representative canary slice (e.g., only internal users) that misses real problems.
Skipping the rollback path so a bad canary still has to be reverted by hand.

Checklist

Start with a small, representative slice of traffic.
Compare canary error rate, latency, and business metrics against baseline.
Expand only when metrics are healthy, in gradual steps.
Automate rollback to the previous version on degradation.
Keep both versions running until the rollout completes.

FAQ

What is the difference between canary and blue-green?

Blue-green switches all traffic at once between two environments; canary shifts a small share first and grows it. Canary limits blast radius, while blue-green optimizes for instant, all-or-nothing rollback. See Rolling vs Blue-Green vs Canary Deployments.

What metrics should I watch during a canary?

Error rate and latency are the essentials, plus whatever business metric matters — signups, checkout completions, successful requests. The canary must look as healthy as the baseline on all of them before expanding.

How is a canary different from a feature flag?

A feature flag turns a feature on or off for selected users at the code level. A canary controls which version of the service receives traffic. They’re complementary: flags change behavior, canaries change deployments. See What Is a Feature Flag?.