Canary Release
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note that automated detection is 'no' and the code_pattern describes symptoms like all-or-nothing deployments and rollback taking 30+ minutes — none of the listed tools (kubernetes, nginx, aws-alb, istio) automatically flag the absence of a canary strategy. A developer must deliberately audit deployment pipelines or observe production incidents to recognize the gap.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix describes a traffic-splitting rollout strategy, but implementing canary releases from scratch requires changes across CI/CD pipelines, load balancer or service mesh configuration (nginx, istio, aws-alb), observability/monitoring setup for success metrics, and database migration strategy for backward compatibility — this spans multiple infrastructure components and teams, not a single-file fix.
Closest to 'strong gravitational pull' (b7). Once adopted, canary release infrastructure shapes every subsequent deployment: all future schema changes must be backward-compatible, success metrics must be defined per release, traffic routing rules must be maintained, and rollback procedures become a standing concern. The applies_to scope covers web and API contexts broadly, meaning the operational overhead persists across all deployments.
Closest to 'notable trap' (t5). The misconception field identifies a well-documented gotcha: developers conflate canary releases with A/B testing because both split traffic between versions. The common_mistakes add further traps — running canaries too briefly, biasing the sample with cookie-based routing, and forgetting that database schema changes must be backward-compatible while old and new code coexist. These are documented pitfalls that experienced developers eventually learn but frequently miss initially.
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);