Canary Deployment

Updated September 30, 20262 min read

In short

A canary deployment releases a new software version to a small share of users first, checks its health, and then gradually rolls it out to everyone.

What is a canary deployment?

A canary deployment is a release strategy where a new version of an application runs alongside the current one but receives only a small slice of real traffic, such as 5% of users. If the new version behaves well, its share is increased step by step until it handles all traffic. If problems appear, traffic is sent back to the old version, and only a small group of users was affected.

It works by splitting traffic with a load balancer, an ingress controller, or a service mesh. During each step, teams compare the canary with the stable version using metrics such as error rate, latency, and CPU usage, and many pipelines promote or roll back the canary automatically based on those numbers. This automated comparison is often called canary analysis.

The name comes from the canaries that coal miners once carried underground: the birds reacted to toxic gas before humans did, giving an early warning. In the same way, the first small group of users acts as an early warning system for a bad release. Canary deployments are common for large web services and APIs, where a bug reaching every user at once would be costly.

Canary deployment is often confused with blue-green deployment. Blue-green runs two full environments and switches all traffic from old to new at once, while a canary shifts traffic gradually and exposes only part of the user base at first. It also differs from a feature flag, which hides a feature inside the same deployed version rather than routing users to different versions.

Key takeaways

A canary sends a small percentage of traffic to the new version first.
Traffic is increased in steps while metrics are watched.
A bad release affects only a few users and can be rolled back quickly.
Automated canary analysis compares error rates and latency with the stable version.
Unlike blue-green deployment, the switch is gradual rather than all at once.

Example

Sending 10% of traffic to a canary with the Kubernetes Gateway APIyaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-app
spec:
  parentRefs:
    - name: main-gateway
  rules:
    - backendRefs:
        - name: web-app-stable
          port: 80
          weight: 90
        - name: web-app-canary
          port: 80
          weight: 10

Readers ask

What is the difference between canary and blue-green deployment?

Blue-green deployment switches all traffic from the old environment to the new one in a single step, while a canary deployment moves traffic gradually, starting with a small percentage. Canaries limit how many users see a bug, while blue-green makes the switch and the rollback simple and instant.

What percentage of traffic should a canary get?

Teams often start with 1% to 10% of traffic, then increase in steps such as 25%, 50%, and 100%. The right starting point depends on how much traffic you have, since the canary needs enough requests to produce meaningful metrics.

Why is it called a canary deployment?

It is named after the canaries coal miners carried to detect dangerous gas early. The small group of users who get the new version first acts as an early warning for problems.

Often compared

Blue-Green vs Canary DeploymentBlue-green runs two full environments and switches all traffic to the new one at once, while canary sends a small share to the new version first and grows it.