Canary Deployment and Canary Release: How the Strategy Works

What is a canary deployment?

A canary deployment is a release strategy that sends a small slice of live traffic to the new version of your application while everyone else stays on the current one. You watch the errors and latency for that slice, and only widen it if the numbers hold. If they do not, you route the slice back and almost nobody noticed.

It is one of five common approaches, compared side by side in our guide to deployment strategies. The name comes from the canary carried into coal mines as an early warning. The point is the same: expose something small and observable to the danger first, so the blast radius of a bad release is a few percent of users instead of all of them.

How does a canary deployment work?

Both versions run at the same time behind whatever splits your traffic, usually a load balancer or reverse proxy. You move the dial in stages and check the metrics between each one.

The stages matter less than the rule between them: every step needs a defined metric, a threshold and an automatic way back. A canary with no automated rollback is just a slower deployment with extra steps.

Canary deployment vs blue green deployment

Both keep two versions alive, but they differ in how traffic moves and what it costs.

Blue green is the cleaner switch and the more expensive one, because you pay for a duplicate environment. Canary is cheaper and more informative, because real users generate signals a staging environment never will. Our longer comparison of blue green and rolling deployments covers where each one fits.

Canary deployment vs rolling deployment

A rolling deployment replaces instances in batches until every one runs the new version. It is a delivery mechanism, not a decision mechanism: the rollout continues unless something fails outright. A canary adds a deliberate pause and a judgement call, where you look at real metrics and decide whether to continue.

The practical difference is what happens with a bug that does not crash anything. A memory leak, a slow query or a subtly wrong calculation will roll all the way out unnoticed, but a canary with a latency threshold catches it while only a few percent of users are affected.

Canary deployment vs A/B testing

They look identical from the outside and answer completely different questions. A canary asks whether the new version is broken, runs for minutes or hours, and is judged on error rate and latency. An A/B test asks whether a change is better, runs long enough to reach statistical significance, and is judged on conversion or engagement.

Using one as the other is a common mistake. A canary that runs for two weeks is an expensive way to maintain two code paths, and an A/B test cut short after twenty minutes has not measured anything. Error rate and latency tell you the canary is not broken, but they say nothing about whether the change actually helped, which is where product analytics that unify usage, feedback and revenue signals do the work instead.

What metrics should you watch during a canary?

Compare the canary against the stable version over the same window, not against yesterday. Traffic patterns move, and an absolute threshold will page you at every lunchtime peak.

Averages are the trap here. A change that breaks one endpoint badly can leave the mean response time almost unchanged, which is why percentiles belong in the abort rule and averages do not.

How long should a canary run?

Long enough to see the traffic that matters, which is a property of your application rather than a fixed number. If a bug only appears when the hourly cron fires, a ten minute canary will miss it. A useful floor is one full cycle of your slowest scheduled work, and a useful ceiling is the point where maintaining two versions costs more than the risk it removes.

For most web applications that lands somewhere between fifteen minutes and a few hours per stage. Anything measured in days is usually a sign the team does not trust its metrics, and the fix is better instrumentation rather than a longer wait.

How do you handle database changes during a canary?

This is the part that breaks real canary rollouts, because both versions share one database. The old code and the new code have to work against the same schema for the entire rollout, which rules out any migration that removes or renames something in a single step.

The standard approach is expand and contract. Add the new column, deploy code that writes to both and reads the old one, backfill, switch reads to the new column, and only drop the old one in a later release once no running version references it. We cover the mechanics in detail in zero downtime database migrations.

The rollback consequence is easy to miss. Your code can go back to the previous version in seconds, but a dropped column cannot, so any migration that is not reversible turns a fast rollback into a restore from backup.

What are the disadvantages of canary deployment?

It is not free, and the costs are worth naming before you commit to it.

• Two versions in production at once. Shared state, caches, queues and database schemas all have to tolerate both, which constrains what a single release can change.
• It needs real observability. Without per version metrics there is nothing to judge, and the canary becomes theatre.
• Low traffic sites learn little. Five percent of a hundred requests an hour is not a sample, it is an anecdote.
• Session affinity gets awkward. Users bouncing between versions mid session can see inconsistent behaviour unless the split is sticky.
• Someone has to own the abort rule. A canary without an automatic trigger depends on a human watching a dashboard, which does not survive contact with a Friday afternoon.

Do you need Kubernetes for canary deployments?

No. Kubernetes and service meshes make weighted routing convenient, but any reverse proxy that can split traffic will do the job. On a plain Linux server, nginx can send a fixed share of requests to a second upstream:

split_clients "${remote_addr}${http_user_agent}" $pool {
    5%      canary;
    *       stable;
}

upstream stable { server 127.0.0.1:8000; }
upstream canary { server 127.0.0.1:8001; }

server {
    location / {
        proxy_pass http://$pool;
        proxy_set_header Host $host;
    }
}

Hashing on the client address keeps a given visitor on one side of the split, which avoids the session inconsistency described above. Raising the share is an edit and a reload, and dropping back to zero percent is the rollback. The same idea applies with containers, where the split lives in the proxy in front of them rather than in the Docker deployment itself.

Canary deployment best practices

The teams that get real value from canaries tend to do the same handful of things.

• Define the abort rule before the rollout, not during it. Pick the metric, the threshold and the window while nobody is under pressure.
• Automate the rollback. The value of a canary is proportional to how fast it reverses without a human deciding.
• Compare canary against stable, in the same window. Absolute thresholds page you for normal traffic peaks.
• Keep releases small. When a canary aborts, a small release tells you exactly what caused it.
• Make migrations backward compatible. Otherwise the code rolls back and the schema does not.
• Watch background work too. Queue workers and scheduled jobs fail silently while every page still returns 200.

Where canary fits in the rest of your release process

A canary is one strategy among several, and it sits on top of a pipeline that already has to be sound. The release has to be atomic so a half copied deploy never serves traffic, the previous version has to stay on disk so rollback is a symlink switch rather than a redeploy, and the whole thing has to run without dropping requests in the first place. That foundation is what zero downtime deployment provides, and canary routing is the layer you add once it is in place.

For most teams running a handful of servers, the honest sequence is: get atomic releases and instant rollback working first, add real per version metrics second, and introduce traffic splitting last. Done in that order each step pays for itself. Done in reverse, you get a traffic splitter pointed at a deployment process that cannot reverse.