Canary vs Blue-Green: AI Deployment Rules

Two Strategies for Safe Deployments

Canary deployment: deploy the new version alongside the old. Route a small percentage of traffic (1-5%) to the new version. Monitor: error rate, latency, and business metrics. If healthy: increase traffic gradually (5% → 25% → 50% → 100%). If unhealthy: route all traffic back to the old version (instant rollback to 0%). The risk is: contained to the canary percentage at every stage. 5% canary with a bug: 5% of users affected. Detected in minutes, rolled back in seconds.

Blue-green deployment: maintain two identical production environments (blue and green). Blue: the current production (serving all traffic). Green: the new version (deployed, tested, ready). Swap: the load balancer switches all traffic from blue to green at once. If unhealthy: swap back to blue (instant rollback). The risk is: 100% of users see the new version immediately. If a bug exists: all users are affected until the swap back (seconds to minutes). The advantage: the rollback is instant (swap the load balancer pointer, no re-deployment).

Without deployment strategy rules: the AI generates: deployment scripts that do not include health checks, rollback scripts that do not exist, or deployment configurations for the wrong strategy (canary config in a blue-green setup or vice versa). The deployment strategy determines: how traffic is routed, how health is monitored, and how rollback is triggered. One rule in CLAUDE.md: aligns every deployment script and configuration with the team strategy.

Canary Deployment Rules

Canary AI rule: "Deployment: canary. Initial traffic: 5% to new version. Monitoring: error rate < 1%, p99 latency < 500ms, no increase in 5xx responses. Promotion: if healthy for 5 minutes, increase to 25%. Then 50% for 5 minutes. Then 100%. Rollback: if any metric exceeds threshold, route 100% to the old version immediately. Tools: Vercel (automatic canary with traffic splitting), AWS CodeDeploy (canary config), Kubernetes (Istio VirtualService weight, Argo Rollouts)."

Canary health checks: the canary is only as safe as the health checks. AI rule: 'Health checks must verify: HTTP status (200 OK), response time (under target), error rate (under threshold), and optionally: business metrics (conversion rate, order completion). Deploy without health checks: the canary runs blind (no way to detect problems). Health checks are: mandatory for every canary deployment. Configure: in the deployment tool (Argo Rollouts analysis, Vercel checks, AWS CloudWatch alarms).'

The canary rule prevents: the AI generating a deployment script that sends 100% of traffic to the new version immediately (that is blue-green, not canary), deploying without health checks (blind canary), or using a canary percentage that is too high (50% initial canary is: too risky for the first deployment — start at 1-5%). The canary strategy is: gradual, monitored, and automated. Every step: is gated by health metrics.

• Initial: 5% traffic to new version. Monitor error rate, latency, 5xx count
• Promotion: 5% → 25% → 50% → 100%, each gated by 5 minutes of healthy metrics
• Rollback: any metric exceeds threshold = instant 100% to old version
• Health checks: mandatory. HTTP status + response time + error rate + business metrics
• Tools: Vercel (built-in), Argo Rollouts (K8s), AWS CodeDeploy, Istio traffic splitting

Blue-Green Deployment Rules

Blue-green AI rule: "Deployment: blue-green. Two environments: blue (current production) and green (new version). Deploy: to the inactive environment (green). Test: run smoke tests against green (health check, critical path verification). Swap: switch the load balancer from blue to green. Monitor: error rate, latency for 5 minutes after swap. Rollback: swap back to blue (the old version is still running, ready to serve). Cleanup: after stability (1 hour+), the old environment becomes the next deployment target."

Blue-green smoke tests: before swapping traffic, the green environment must pass smoke tests. AI rule: 'Before swap: run automated smoke tests against the green URL (not the production URL). Tests verify: authentication works, the homepage loads, critical API endpoints respond, and the database connection is healthy. If any smoke test fails: do not swap. Fix the issue and re-deploy to green. The swap is: only triggered after all smoke tests pass.'

The blue-green rule prevents: the AI deploying directly to the production environment (deploy to the inactive environment, then swap), swapping without testing (skip smoke tests = potentially broken production), or not maintaining the old environment (the old blue must stay running as the rollback target). Blue-green is: simpler than canary (binary swap, not gradual) but riskier (100% traffic moves at once instead of incrementally).

• Two environments: blue (production) and green (new version, inactive)
• Deploy to green, smoke test green, swap load balancer from blue to green
• Rollback: swap back to blue (instant, blue is still running, no re-deployment)
• Smoke tests: mandatory before swap. Auth, homepage, API, database connection
• Simpler than canary: binary swap. Riskier: 100% traffic moves at once

When to Choose Each Strategy

Choose canary when: you want gradual risk exposure (5% then 25% then 50% then 100% — problems are caught at low traffic), you have: metric-driven deployment automation (Argo Rollouts, Flagger, or Vercel's built-in canary), the change is: large or risky (new feature, major refactor, dependency upgrade — the gradual rollout catches issues at low blast radius), or you want: the safest possible deployment (canary + automated rollback = the gold standard for zero-downtime deployments).

Choose blue-green when: you want instant cutover (the new version serves all traffic the moment you are ready — useful for: coordinated launches, marketing campaigns, time-sensitive features), the infrastructure supports: two full environments (the green environment is a complete replica of blue — doubles the infrastructure cost during deployment), rollback must be instant (swap the load balancer pointer — the old environment is already running), or the change is: small and well-tested (smoke tests give sufficient confidence for full traffic swap).

For most web applications in 2026: canary is the default. Vercel and similar platforms: implement canary automatically (deploy, route a percentage, promote based on metrics). Blue-green is: more common in: enterprise environments with load balancers they control, mobile backend APIs with coordinated app releases, and environments where: the deployment tool supports blue-green natively (AWS Elastic Beanstalk, Azure App Service deployment slots).

• Canary: gradual risk, metric-driven, safest for large/risky changes. 2026 web default
• Blue-green: instant cutover, two environments, instant rollback. Enterprise and coordinated launches
• Canary risk: contained to percentage (5% of users). Blue-green risk: 100% of users on swap
• Canary cost: one environment + small percentage of new version. Blue-green cost: two full environments
• Vercel/Netlify: canary built-in (automatic). Blue-green: needs load balancer you control

AI-Generated Deployment Scripts

AI deployment script rule: "When generating deployment scripts or CI/CD configuration: follow the team deployment strategy (canary or blue-green as specified in CLAUDE.md). Include: health checks (mandatory), rollback steps (documented and automated), monitoring integration (alert on threshold breach), and environment-specific configuration (staging vs production). Never: deploy directly to production without a health check gate. Never: skip the rollback configuration."

The deployment rule for Claude Code: "When asked to deploy or create deployment configuration: verify the deployment strategy from CLAUDE.md. Generate: CI/CD pipeline steps that match the strategy. Canary: deploy, set traffic weight, monitor, promote or rollback. Blue-green: deploy to inactive, smoke test, swap, monitor, rollback if needed. Always include: the rollback step. A deployment without rollback: is a one-way trip. Every deployment must be: two-way (deploy + verified rollback path)."

The deployment script rule prevents: the AI generating a deployment that goes straight to 100% production without staging or canary (the most dangerous deployment pattern), omitting health checks (deploy blind), omitting rollback steps (no way back if the deployment is bad), or configuring the wrong strategy (canary weights in a blue-green setup, or single-deployment in a canary setup). Every AI-generated deployment: must include the safety mechanisms.

Deployment Strategy Summary

Summary of canary vs blue-green deployment AI rules.

• Canary: 5% → 25% → 50% → 100%, metric-gated promotion, rollback = set to 0%
• Blue-green: deploy to inactive, smoke test, swap 100%, rollback = swap back instantly
• Canary risk: contained to percentage. Blue-green risk: 100% on swap
• Canary: needs metric-driven automation. Blue-green: needs two full environments
• Health checks: mandatory for both. Canary: continuous monitoring. Blue-green: smoke test before swap
• 2026 web default: canary (Vercel built-in, Argo Rollouts for K8s). Blue-green for enterprise/coordinated
• AI rule: always include health checks + rollback steps. Never deploy to 100% without a gate
• Every deployment must be two-way: deploy path + verified rollback path