Canary deployment strategy
Roll out new versions to a small percentage of traffic, then scale up.
Production outages often start small — a bug that only hits a rare edge case, or a resource leak that takes hours to surface. By the time the whole user base is running a new version, it's too late. Canary deployment solves this by rolling out to a tiny percentage of users first, monitoring them closely, and only expanding to everyone if no alarms fire. It's the difference between "one engineer and a customer notice the bug" and "half your user base is down for 40 minutes."
This template shows the traffic ramp: deploy to 5%, then 25%, then 50%, then 100%, with a monitoring gate at each step. At any stage, if error rates spike or latency jumps, you rollback instantly to the old version while you investigate. The whole process typically takes 30 minutes for a healthy release.
When to use this template
- Planning a production rollout — before deploying, align the team on traffic percentages, monitoring thresholds, and the rollback trigger. Visual agreement prevents confusion at 3 AM.
- Onboarding a new environment — when a team is new to production deployments, this diagram teaches the discipline: never put everyone on new code without proving it first.
- Compliance and risk reviews — auditors and security teams expect a gradual rollout story. This diagram shows you have one.
How to adapt it
The traffic percentages are starting points; adjust them to match your risk tolerance and traffic patterns:
- For high-risk changes — use smaller steps: 1%, 5%, 10%, 25%, 50%, 100%. Spend more time at each stage.
- For low-risk changes — consolidate steps: 10%, 50%, 100%. Spend less time between gates.
- Add automated rollback — if your monitoring platform integrates with your deployment tool, add a decision: "Is error rate > 2%? → Auto-rollback." This removes the human reaction time.
- Layer with feature flags — inside the canary version, hide new features behind flags. That way you can deploy code but not activate it, extending control beyond traffic percentages.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[New version ready] --> B[Deploy to canary cluster]
B --> C[Route 5% traffic to canary]
C --> D{Monitor metrics}
D -->|Errors spike| E[Rollback canary]
E --> F[Investigate and fix]
D -->|Healthy| G[Route 25% traffic]
G --> H{Monitor for issues}
H -->|Problems detected| E
H -->|Stable| I[Route 50% traffic]
I --> J{Check critical paths}
J -->|Alert triggered| E
J -->|All green| K[100% production traffic]
K --> L[Retire old version]
Frequently asked questions
- What is canary deployment and why use it instead of big-bang releases?
- A canary deployment sends a new version to a small subset of users first (5–10%), monitors for errors, then gradually increases traffic if everything looks good. This catches bugs affecting real users before they hit everyone. Big-bang releases flip everyone over at once, so bugs affect your entire user base simultaneously. Canary is the safer pattern for production.
- What metrics should I monitor during a canary rollout?
- Watch error rates (4xx, 5xx), latency (p50, p95, p99), custom business metrics (conversion, failed payments), and infrastructure load (CPU, memory, network). If any spike or drop suddenly, the canary version is likely the culprit. Set alerts for each metric so you catch issues before humans notice degradation.
- How long should I run each traffic stage?
- Depends on your traffic volume and confidence. High-traffic systems: 5–15 minutes per stage. Low-traffic systems: hours. Run long enough to see a representative sample of real requests. If you see an error on canary, don't wait for the timer — roll back immediately. The traffic percentages (5%, 25%, 50%) are guidelines; adjust based on your risk tolerance.
- How do I adapt this for multiple services or coordinated rollouts?
- For microservices, deploy each service on its own canary schedule — don't couple them. Use feature flags inside services to toggle new code off instantly if monitoring detects issues. For coordinated multi-service rollouts, sequence them: deploy the most-upstream service first (clients), then work downstream. Each service follows this traffic ramp independently.