Canary Deployment Skill

This skill provides comprehensive canary deployment capabilities for Vercel and Cloudflare platforms, enabling gradual traffic shifting, deployment validation, and automated rollback strategies.

Overview

Canary deployment is a progressive rollout strategy that reduces deployment risk by gradually shifting traffic from the stable version to the new version. This skill covers:

1. Traffic Splitting - Configure percentage-based traffic routing between versions
2. Gradual Rollout - Automated progressive traffic increase (5% → 25% → 50% → 100%)
3. Health Monitoring - Real-time metrics and error rate tracking during rollout
4. Automated Rollback - Instant reversion if error thresholds are exceeded
5. A/B Testing Integration - Use canary deployments for controlled experiments

Supported Platforms

Vercel

• Edge Config for traffic splitting rules
• Deployment Protection for staged rollouts
• Analytics Integration for real-time monitoring
• Instant Rollback via deployment promotion/demotion

Cloudflare

• Workers for traffic splitting logic
• KV Storage for deployment state
• Analytics Engine for metrics collection
• Gradual Rollout via route weight configuration

Available Scripts

1. Canary Deploy to Vercel

Script: scripts/canary-deploy-vercel.sh <project-path> <canary-percentage>

Purpose: Deploy new version to Vercel and configure canary traffic split

Actions:

• Validates Vercel CLI authentication
• Deploys new version to preview environment
• Creates Edge Config for traffic splitting
• Configures percentage-based routing rules
• Monitors deployment health metrics
• Provides rollback command if needed

Usage:

# Deploy with 10% canary traffic
./scripts/canary-deploy-vercel.sh /path/to/app 10

# Deploy with 25% canary traffic
./scripts/canary-deploy-vercel.sh /path/to/app 25

# Skip health check (for testing)
SKIP_HEALTH_CHECK=true ./scripts/canary-deploy-vercel.sh /path/to/app 10

# Use custom project name
PROJECT_NAME=my-app ./scripts/canary-deploy-vercel.sh /path/to/app 10

Environment Variables:

• VERCEL_TOKEN: Vercel authentication token (required)
• VERCEL_ORG_ID: Organization ID (optional for personal accounts)
• PROJECT_NAME: Custom project name (auto-detected if not set)
• SKIP_HEALTH_CHECK: Set to true to skip initial health validation

Exit Codes:

• 0: Canary deployment successful
• 1: Deployment failed or validation errors

2. Canary Deploy to Cloudflare

Script: scripts/canary-deploy-cloudflare.sh <project-path> <canary-percentage>

Purpose: Deploy new version to Cloudflare Workers and configure traffic split

Actions:

• Validates Cloudflare credentials (API token, account ID)
• Deploys new Worker version
• Updates KV storage with deployment metadata
• Configures route weights for traffic splitting
• Sets up analytics tracking
• Monitors error rates and latency

Usage:

# Deploy with 10% canary traffic
./scripts/canary-deploy-cloudflare.sh /path/to/worker 10

# Deploy with custom worker name
WORKER_NAME=my-worker ./scripts/canary-deploy-cloudflare.sh /path/to/worker 15

# Skip route update (manual routing)
SKIP_ROUTES=true ./scripts/canary-deploy-cloudflare.sh /path/to/worker 20

Environment Variables:

• CLOUDFLARE_API_TOKEN: Cloudflare API token (required)
• CLOUDFLARE_ACCOUNT_ID: Account ID (required)
• WORKER_NAME: Custom worker name (auto-detected from wrangler.toml)
• SKIP_ROUTES: Set to true to skip automatic route configuration

Exit Codes:

• 0: Canary deployment successful
• 1: Deployment failed or credential errors

3. Gradual Rollout

Script: scripts/gradual-rollout.sh <platform> <project-name> <schedule>

Purpose: Automate progressive traffic increase according to schedule

Actions:

• Executes multi-stage rollout plan (e.g., 5% → 25% → 50% → 100%)
• Monitors health metrics at each stage
• Automatic rollback if error rate exceeds threshold
• Configurable wait time between stages
• Sends notifications at each stage

Rollout Schedules:

• fast: 10% → 50% → 100% (5 min intervals)
• standard: 5% → 25% → 50% → 100% (15 min intervals)
• safe: 5% → 10% → 25% → 50% → 75% → 100% (30 min intervals)
• custom: Custom stages via environment variable

Usage:

# Standard rollout to Vercel
./scripts/gradual-rollout.sh vercel my-app standard

# Fast rollout to Cloudflare
./scripts/gradual-rollout.sh cloudflare my-worker fast

# Safe rollout with monitoring
./scripts/gradual-rollout.sh vercel my-app safe

# Custom rollout schedule
ROLLOUT_STAGES="5,15,35,65,100" ./scripts/gradual-rollout.sh vercel my-app custom

# Custom error threshold (default: 5%)
ERROR_THRESHOLD=3 ./scripts/gradual-rollout.sh vercel my-app standard

Environment Variables:

• ROLLOUT_STAGES: Comma-separated percentage stages for custom schedule
• STAGE_WAIT_TIME: Minutes to wait between stages (default varies by schedule)
• ERROR_THRESHOLD: Error rate percentage triggering automatic rollback (default: 5)
• SLACK_WEBHOOK: Slack webhook URL for notifications (optional)

Exit Codes:

• 0: Rollout completed successfully
• 1: Rollout failed or rollback triggered
• 2: Health check failure during rollout

4. Rollback Canary

Script: scripts/rollback-canary.sh <platform> <project-name>

Purpose: Instantly rollback canary deployment to previous stable version

Actions:

• Identifies current canary and stable deployments
• Routes 100% traffic back to stable version
• Updates Edge Config or Worker routes
• Captures rollback event for audit trail
• Preserves canary deployment for investigation

Usage:

# Rollback Vercel deployment
./scripts/rollback-canary.sh vercel my-app

# Rollback Cloudflare Worker
./scripts/rollback-canary.sh cloudflare my-worker

# Rollback and delete canary
DELETE_CANARY=true ./scripts/rollback-canary.sh vercel my-app

# Rollback with notification
SLACK_WEBHOOK=your_webhook_url_here ./scripts/rollback-canary.sh vercel my-app

Environment Variables:

• DELETE_CANARY: Set to true to delete canary deployment after rollback
• SLACK_WEBHOOK: Slack webhook URL for rollback notifications

Exit Codes:

• 0: Rollback successful
• 1: Rollback failed
• 2: Unable to identify stable version

5. Monitor Canary

Script: scripts/monitor-canary.sh <platform> <project-name>

Purpose: Real-time monitoring of canary deployment health metrics

Actions:

• Fetches error rates, latency, and request volume
• Compares canary metrics vs stable version
• Alerts if metrics exceed threshold
• Logs metrics history for analysis
• Provides rollback recommendation if needed

Usage:

# Monitor Vercel deployment (runs continuously)
./scripts/monitor-canary.sh vercel my-app

# Monitor with custom interval
MONITOR_INTERVAL=30 ./scripts/monitor-canary.sh cloudflare my-worker

# One-time health check
ONE_SHOT=true ./scripts/monitor-canary.sh vercel my-app

# Monitor with custom error threshold
ERROR_THRESHOLD=3 ./scripts/monitor-canary.sh vercel my-app

Environment Variables:

• MONITOR_INTERVAL: Seconds between health checks (default: 60)
• ERROR_THRESHOLD: Error rate percentage triggering alert (default: 5)
• ONE_SHOT: Set to true for single health check instead of continuous monitoring

Exit Codes:

• 0: Metrics within acceptable range
• 1: Metrics exceed threshold (rollback recommended)

Available Templates

1. Vercel Edge Config

File: templates/vercel-edge-config.json

Purpose: Edge Config template for traffic splitting rules

Features:

• Percentage-based traffic routing
• Deployment version tracking
• Rollout state management
• Feature flag integration

Template Variables:

• {{CANARY_PERCENTAGE}}: Traffic percentage for canary (0-100)
• {{CANARY_DEPLOYMENT_URL}}: Canary deployment URL
• {{STABLE_DEPLOYMENT_URL}}: Stable deployment URL
• {{ROLLOUT_STAGE}}: Current rollout stage identifier

2. Cloudflare Worker Canary Logic

File: templates/cloudflare-worker-canary.js

Purpose: Cloudflare Worker with traffic splitting logic

Features:

• Request-based routing algorithm
• Sticky sessions with cookies
• A/B testing support
• Analytics integration
• Automatic failover

Template Variables:

• {{CANARY_PERCENTAGE}}: Traffic percentage for canary
• {{CANARY_WORKER_NAME}}: Name of canary worker
• {{STABLE_WORKER_NAME}}: Name of stable worker
• {{KV_NAMESPACE}}: KV namespace for state storage

3. Vercel Middleware Canary

File: templates/vercel-middleware-canary.ts

Purpose: Next.js middleware for canary traffic splitting

Features:

• Edge runtime execution
• Cookie-based sticky sessions
• Geographic routing support
• Custom routing rules

Template Variables:

• {{CANARY_PERCENTAGE}}: Traffic percentage for canary
• {{CANARY_REWRITE_URL}}: URL to rewrite canary traffic to
• {{ENABLE_STICKY_SESSIONS}}: Enable/disable sticky sessions

4. Health Check Configuration

File: templates/health-check-config.json

Purpose: Health check thresholds and monitoring configuration

Features:

• Error rate thresholds
• Latency limits
• Request volume requirements
• Rollback trigger rules

Template Variables:

• {{ERROR_RATE_THRESHOLD}}: Max error rate percentage (default: 5)
• {{LATENCY_P95_THRESHOLD}}: Max P95 latency in ms (default: 1000)
• {{MIN_REQUEST_VOLUME}}: Minimum requests before validation (default: 100)

5. Rollout Schedule Configuration

File: templates/rollout-schedule.json

Purpose: Predefined and custom rollout schedule templates

Schedules:

• Fast: 10% → 50% → 100% (5 min intervals)
• Standard: 5% → 25% → 50% → 100% (15 min intervals)
• Safe: 5% → 10% → 25% → 50% → 75% → 100% (30 min intervals)

Template Variables:

• {{SCHEDULE_NAME}}: Schedule identifier (fast/standard/safe/custom)
• {{STAGES}}: Array of percentage stages
• {{WAIT_TIMES}}: Array of wait times between stages

6. Cloudflare KV Schema

File: templates/cloudflare-kv-schema.json

Purpose: KV storage schema for deployment state

Data Structure:

• Deployment metadata (versions, URLs, timestamps)
• Traffic split configuration
• Health check results
• Rollback history

Available Examples

1. Basic Canary Deployment

File: examples/vercel-basic-canary.md

Purpose: Simple canary deployment to Vercel with 10% traffic

Demonstrates:

• Initial canary deployment
• Health monitoring
• Manual traffic adjustment
• Rollback procedure

2. Automated Gradual Rollout

File: examples/cloudflare-gradual-rollout.md

Purpose: Automated multi-stage rollout to Cloudflare Workers

Demonstrates:

• Configuring rollout schedule
• Automated stage progression
• Health check integration
• Automatic rollback on errors

3. A/B Testing with Canary

File: examples/ab-testing-canary.md

Purpose: Using canary deployments for A/B experiments

Demonstrates:

• Feature flag integration
• User segmentation
• Metrics collection
• Experiment analysis

4. Multi-Region Canary

File: examples/multi-region-rollout.md

Purpose: Progressive rollout across geographic regions

Demonstrates:

• Region-based traffic splitting
• Staged regional rollout
• Cross-region failover
• Global traffic management

Deployment Workflows

Initial Canary Deployment

# Step 1: Deploy canary with 10% traffic
./scripts/canary-deploy-vercel.sh /path/to/app 10

# Step 2: Monitor health for 15 minutes
./scripts/monitor-canary.sh vercel my-app

# Step 3: If healthy, proceed with gradual rollout
./scripts/gradual-rollout.sh vercel my-app standard

# Step 4: If issues detected, rollback immediately
./scripts/rollback-canary.sh vercel my-app

Automated Gradual Rollout

# Deploy canary and execute automated rollout
./scripts/canary-deploy-vercel.sh /path/to/app 5 && \
./scripts/gradual-rollout.sh vercel my-app standard

# Rollout proceeds automatically:
# - 5% → wait 15 min → health check
# - 25% → wait 15 min → health check
# - 50% → wait 15 min → health check
# - 100% → complete

# Automatic rollback if error rate > 5% at any stage

Emergency Rollback

# Instant rollback to stable version
./scripts/rollback-canary.sh vercel my-app

# Rollback completes in seconds:
# - Traffic routed 100% to stable
# - Canary deployment preserved for debugging
# - Audit trail logged

Best Practices

Traffic Split Strategy

1. Start Small: Begin with 5-10% canary traffic
2. Progressive Increase: Double traffic at each stage (5% → 10% → 25% → 50% → 100%)
3. Minimum Dwell Time: Wait at least 15 minutes at each stage
4. Monitor Continuously: Track error rates, latency, and request volume

Health Check Thresholds

1. Error Rate: Rollback if > 5% above baseline
2. Latency P95: Rollback if > 2x baseline
3. Request Volume: Require minimum 100 requests for validation
4. Comparison Window: Compare last 5 minutes canary vs last 15 minutes stable

Rollback Triggers

Automatic Rollback When:

• Error rate exceeds threshold for 2 consecutive checks
• P95 latency > 2x baseline for 3 consecutive checks
• Critical alert from monitoring system
• Manual trigger via rollback script

Preserve Canary After Rollback:

• Keep deployment for investigation
• Analyze logs and metrics
• Identify root cause before re-deploying

Monitoring and Alerting

1. Real-Time Dashboards: Vercel Analytics or Cloudflare Analytics
2. Alert Channels: Slack, PagerDuty, or email notifications
3. Metric Collection: Log all health checks to external system
4. Audit Trail: Record all deployment and rollback events

Platform-Specific Features

Vercel

Edge Config Advantages:

• Ultra-low latency routing decisions (<1ms)
• Global propagation in seconds
• No code deployment required for traffic changes
• Native Next.js middleware integration

Deployment Protection:

• Preview deployments isolated from production
• Instant promotion/demotion
• Automatic HTTPS and DNS management

Analytics Integration:

• Real-time request metrics
• Error tracking by deployment
• Custom event tracking

Cloudflare

Workers Advantages:

• Edge compute in 300+ locations
• Sub-millisecond routing logic
• KV storage for persistent state
• Analytics Engine for detailed metrics

Gradual Rollout:

• Route weight configuration
• Version-based routing
• A/B testing support

Durable Objects (Advanced):

• Stateful canary coordination
• Cross-region synchronization
• Consistent traffic splitting

Security Considerations

1. API Token Storage: Always use environment variables, never hardcode
2. Access Control: Limit deployment permissions to authorized users
3. Audit Logging: Record all deployment and rollback actions
4. Secrets Management: Use platform secret stores (Vercel Secrets, Cloudflare Secrets)
5. Preview Protection: Password-protect canary deployments if needed

Troubleshooting

Vercel Edge Config Not Updating

# Check Edge Config status
vercel env ls

# Verify Edge Config connection
# Check middleware.ts has correct Edge Config import

# Force refresh
vercel env pull

Cloudflare Worker Routing Issues

# Check Worker routes
wrangler routes list

# Verify KV namespace binding
wrangler kv:namespace list

# Test Worker directly
curl https://my-worker.workers.dev

Gradual Rollout Stuck

# Check monitor process status
ps aux | grep monitor-canary

# View rollout logs
tail -f /tmp/gradual-rollout-*.log

# Manual stage progression
./scripts/canary-deploy-vercel.sh /path/to/app 50

Health Check False Positives

# Increase error threshold temporarily
ERROR_THRESHOLD=8 ./scripts/monitor-canary.sh vercel my-app

# Adjust latency threshold
LATENCY_THRESHOLD=2000 ./scripts/monitor-canary.sh vercel my-app

# Require more requests before validation
MIN_REQUESTS=500 ./scripts/monitor-canary.sh vercel my-app

Cost Considerations

Vercel

• Free Tier: 100GB bandwidth, sufficient for small canaries
• Pro Tier: $20/month, required for Edge Config in production
• Edge Config: Included in Pro tier
• Additional Bandwidth: $40/TB

Cloudflare

• Free Tier: 100k requests/day on Workers
• Paid Tier: $5/month for 10M requests
• KV Storage: $0.50/GB/month
• Analytics Engine: Included in paid tier

Integration with Dev Lifecycle

This skill integrates with:

• /deployment:deploy - Execute canary deployment strategy
• /deployment:validate - Pre-deployment health check validation
• /deployment:rollback - Emergency rollback orchestration
• Deployment agents for automated canary management

Platform CLI Commands Reference

Vercel

# Edge Config management
vercel env add EDGE_CONFIG
vercel env pull

# Deployment management
vercel list
vercel inspect <url>
vercel promote <url>
vercel rollback

Cloudflare

# Worker deployment
wrangler publish
wrangler tail

# KV management
wrangler kv:namespace create <name>
wrangler kv:key put <key> <value>
wrangler kv:key get <key>

# Route management
wrangler routes list
wrangler routes add <route> <worker>

Requirements

• Vercel CLI (npm install -g vercel) for Vercel deployments
• Cloudflare Wrangler CLI (npm install -g wrangler) for Cloudflare deployments
• Valid authentication tokens stored as environment variables
• Project must be deployed at least once before canary rollout
• Monitoring tools or analytics configured for health checks

---

Skill Location: /home/gotime2022/.claude/plugins/marketplaces/dev-lifecycle-marketplace/plugins/deployment/skills/canary-deployment/ Version: 1.0.0