Deployment Knowledge

Deployment Knowledge Base

Quick reference for deployment strategies, zero-downtime patterns, and release management.

Deployment Strategies

Strategy Comparison

┌─────────────────────────────────────────────────────────────────┐
│                    DEPLOYMENT STRATEGIES                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  RECREATE         ROLLING          BLUE-GREEN       CANARY      │
│  ┌───┐           ┌───┬───┐        ┌───┐ ┌───┐     ┌───┐        │
│  │ v1│           │v1 │v1 │        │ v1│ │ v2│     │v1 │ 90%    │
│  └───┘           └───┴───┘        └───┘ └───┘     └───┘        │
│    ↓               ↓  ↓              ↕             ┌───┐        │
│  ┌───┐           ┌───┬───┐        Traffic         │v2 │ 10%    │
│  │ v2│           │v2 │v1 │        Switch          └───┘        │
│  └───┘           └───┴───┘                                      │
│                    ↓  ↓                                         │
│                  ┌───┬───┐                                      │
│                  │v2 │v2 │                                      │
│                  └───┴───┘                                      │
└─────────────────────────────────────────────────────────────────┘

Blue-Green Deployment

Overview

Two identical environments (Blue = current, Green = new). Traffic switches instantly.

# Environment structure
environments:
  blue:
    url: blue.example.com
    version: v1.2.3
    active: true

  green:
    url: green.example.com
    version: v1.2.4
    active: false

# Load balancer config
upstream backend {
    server blue.example.com weight=100;
    server green.example.com weight=0;
}

Deployment Steps

#!/bin/bash
# blue-green-deploy.sh

ACTIVE=$(get_active_environment)
INACTIVE=$(get_inactive_environment)

# 1. Deploy to inactive environment
deploy_to_environment $INACTIVE $VERSION

# 2. Run health checks
if ! health_check $INACTIVE; then
    echo "Health check failed, aborting"
    exit 1
fi

# 3. Run smoke tests
if ! smoke_tests $INACTIVE; then
    echo "Smoke tests failed, aborting"
    exit 1
fi

# 4. Switch traffic
switch_traffic_to $INACTIVE

# 5. Verify
if ! verify_deployment $INACTIVE; then
    echo "Verification failed, rolling back"
    switch_traffic_to $ACTIVE
    exit 1
fi

# 6. Mark as active
set_active_environment $INACTIVE

Rollback

# Instant rollback - just switch traffic back
switch_traffic_to $PREVIOUS_ACTIVE

Canary Deployment

Traffic Distribution

# Canary stages
stages:
  - name: canary-5
    traffic: 5%
    duration: 10m

  - name: canary-25
    traffic: 25%
    duration: 30m

  - name: canary-50
    traffic: 50%
    duration: 1h

  - name: full-rollout
    traffic: 100%

Implementation

# nginx canary config
upstream backend {
    server stable.example.com weight=95;
    server canary.example.com weight=5;
}

# Or with cookie-based routing
map $cookie_canary $backend {
    "true"  canary.example.com;
    default stable.example.com;
}

Canary Analysis

# Automated canary analysis
analysis:
  metrics:
    - name: error_rate
      threshold: 1%
      comparison: less_than

    - name: latency_p99
      threshold: 500ms
      comparison: less_than

    - name: success_rate
      threshold: 99%
      comparison: greater_than

  duration: 10m
  interval: 1m

  on_failure: rollback
  on_success: promote

Rolling Deployment

Configuration

# Kubernetes-style rolling update
deployment:
  replicas: 4
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1

Sequence

Time →
Pod 1: [v1][v1][v1][v2][v2][v2][v2]
Pod 2: [v1][v1][v1][v1][v2][v2][v2]
Pod 3: [v1][v1][v1][v1][v1][v2][v2]
Pod 4: [v1][v1][v1][v1][v1][v1][v2]

Zero-Downtime Checklist

Database Migrations

// WRONG: Destructive migration
Schema::dropColumn('users', 'old_field');

// RIGHT: Backward-compatible migration
// Step 1: Add new column (deploy #1)
Schema::addColumn('users', 'new_field');

// Step 2: Migrate data (deploy #2)
DB::statement('UPDATE users SET new_field = old_field');

// Step 3: Switch code to use new_field (deploy #3)
// Step 4: Drop old column (deploy #4, weeks later)
Schema::dropColumn('users', 'old_field');

Migration Strategies

Health Checks

// Readiness probe - can accept traffic?
public function ready(): JsonResponse
{
    return response()->json([
        'database' => $this->checkDatabase(),
        'cache' => $this->checkCache(),
        'queue' => $this->checkQueue(),
    ]);
}

// Liveness probe - is the app running?
public function live(): JsonResponse
{
    return response()->json(['status' => 'ok']);
}

Feature Flags

Implementation Patterns

// Simple feature flag
if (Feature::enabled('new-checkout')) {
    return $this->newCheckout();
}
return $this->oldCheckout();

// User-based rollout
if (Feature::enabledForUser('new-checkout', $user)) {
    return $this->newCheckout();
}

// Percentage rollout
if (Feature::enabledForPercentage('new-checkout', 10)) {
    return $this->newCheckout();
}

Feature Flag Service

interface FeatureFlagService
{
    public function isEnabled(string $feature): bool;
    public function isEnabledForUser(string $feature, User $user): bool;
    public function isEnabledForPercentage(string $feature, int $percent): bool;
    public function getVariant(string $feature): string;
}

Configuration

# features.yaml
features:
  new-checkout:
    enabled: true
    rollout:
      type: percentage
      value: 25
    users:
      - user-123  # Beta testers
      - user-456

  dark-mode:
    enabled: true
    rollout:
      type: user_attribute
      attribute: plan
      values: [premium, enterprise]

Best Practices

Feature Flag Lifecycle:
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Create  │───▶│  Rollout │───▶│ Full On  │───▶│  Remove  │
│   Flag   │    │  0-100%  │    │   100%   │    │   Flag   │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     1 day         1-2 weeks       2 weeks         Sprint

Rollback Procedures

Automated Rollback Triggers

rollback:
  triggers:
    - metric: error_rate
      threshold: 5%
      window: 5m

    - metric: latency_p95
      threshold: 2s
      window: 5m

    - metric: health_check_failures
      threshold: 3
      window: 1m

  actions:
    - switch_traffic_to_previous
    - notify_oncall
    - create_incident

Manual Rollback

#!/bin/bash
# rollback.sh

# 1. Get previous version
PREVIOUS=$(get_previous_version)

# 2. Switch traffic immediately (blue-green)
switch_traffic_to $PREVIOUS_ENV

# Or redeploy previous version (rolling)
deploy_version $PREVIOUS

# 3. Verify
health_check_all

# 4. Notify
notify_team "Rolled back to $PREVIOUS"

Database Rollback

// Always have down() migration
public function down(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->dropColumn('new_field');
    });
}

Environment Configuration

Environment Matrix

environments:
  development:
    replicas: 1
    resources: minimal
    auto_deploy: true

  staging:
    replicas: 2
    resources: medium
    auto_deploy: true
    feature_flags: all_enabled

  production:
    replicas: 4+
    resources: full
    auto_deploy: false
    requires_approval: true
    deployment_window: "Mon-Thu 09:00-16:00"

Secrets Management

# DO NOT: Hardcode secrets
database_password: "secret123"

# DO: Use environment variables
database_password: ${DATABASE_PASSWORD}

# DO: Use secret managers
database_password:
  vault: production/database
  key: password

Deployment Checklist

Pre-Deployment

• All tests passing
• Code review approved
• Database migrations tested
• Rollback plan documented
• Monitoring alerts configured
• Stakeholders notified

During Deployment

• Health checks passing
• No error spike in metrics
• Latency within SLA
• Smoke tests passing
• Feature flags working

Post-Deployment

• Verify functionality
• Check error rates
• Monitor performance
• Update documentation
• Clean up old versions

References

For detailed information, load these reference files:

• references/blue-green.md — Blue-green implementation details
• references/canary.md — Canary release patterns
• references/feature-flags.md — Feature flag best practices