canary-deployment

What this skill does

# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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_DEPLOYM