Canary Release

Also Known As

TL;DR

Explanation

A canary release deploys a new version to a small subset of users or servers first — typically 1–5% — and monitors error rates, latency, and business metrics before progressively increasing traffic. If metrics degrade, the release is rolled back with minimal user impact. Named after the canary in a coal mine. Canary releases require feature-flag infrastructure or a smart load balancer (Nginx, AWS ALB, Kubernetes rollout strategies). Combined with observability tooling, they make production the final test environment without risking the entire user base.

Diagram

flowchart LR
    LB[Load Balancer] -->|95 pct traffic| STABLE[Stable v1.2]
    LB -->|5 pct traffic| CANARY[Canary v1.3]
    CANARY --> MON{Monitor<br/>Errors/Latency}
    MON -->|Healthy| EXPAND[Increase to 20 pct<br/>then 50 pct then 100 pct]
    MON -->|Problems| ROLLBACK[Route 0 pct to Canary<br/>Rollback complete]
style STABLE fill:#238636,color:#fff
style CANARY fill:#d29922,color:#fff
style EXPAND fill:#238636,color:#fff
style ROLLBACK fill:#f85149,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Not defining success metrics before the canary — you need to know what "healthy" looks like to decide when to proceed.
• Running the canary for too short a time — some bugs only appear under specific conditions or traffic patterns.
• Sending the same users to the canary every time — cookie-based routing biases the sample.
• Forgetting that database schema changes must be backward-compatible during a canary — old and new code run simultaneously.

Code Examples

// Full deploy to all users at once — no canary:
// v2 deployed to 100% of servers simultaneously
// Bug in v2 affects 100% of users immediately

// Canary:
// v2 deployed to 5% of servers
// Monitor error rate, latency for 30 minutes
// Gradually increase: 5% → 25% → 50% → 100%
// Roll back instantly if metrics degrade

# nginx — route 5% of traffic to canary
upstream app {
    server stable-app:9000 weight=95;
    server canary-app:9000 weight=5;
}

# Monitor error rate and latency on canary before increasing weight
# Rollback: set canary weight=0, redeploy nginx config

# Feature-flag approach (no infra change needed)
if ($this->featureFlags->isEnabled('new_checkout', $user)) {
    return $this->newCheckoutService->process($cart);
}
return $this->legacyCheckoutService->process($cart);

References

• ↗ https://martinfowler.com/bliki/CanaryRelease.html

Tags

Related Terms