How to implement blue-green deployments in an API Gateway

• Blue-green deployment – runs two complete production environments simultaneously, blue (current) and green (new), and switches traffic between them.
• Weighted routing – the gateway sends a configurable percentage of traffic to each environment (e.g., 90% blue, 10% green).
• Instant rollback – shift weight back to blue, which never stopped running; no rebuild or redeploy needed.
• Data compatibility – during overlap, both versions must read and write compatible data (expand-and-contract migrations).
• Release as traffic decision – because both environments are already deployed, the release is just a route change, not a deployment.

What is blue-green deployment?

Both versions are fully deployed and healthy at the same time. Blue is the current version serving all traffic. Green is the new version, running but receiving no traffic yet. The "release" is just a traffic decision.

// Before release:
// Blue (v1.0): 100% traffic → serving all customers
// Green (v2.0): 0% traffic → deployed, healthy, idle

// Release is NOT a deployment; it's a route change:
// Blue: 90% → 50% → 0%
// Green: 10% → 50% → 100%

How does weighted routing work in Spring Cloud Gateway?

The gateway holds two routes for the same path, each with a weight. The Weight predicate splits traffic proportionally.

# Blue-green weighted routing
spring:
  cloud:
    gateway:
      routes:
        - id: payment-blue
          uri: lb://payment-service-v1
          predicates:
            - Path=/api/v1/payments/**
            - Weight=payment-group, 90
        - id: payment-green
          uri: lb://payment-service-v2
          predicates:
            - Path=/api/v1/payments/**
            - Weight=payment-group, 10

// 90% of payment requests → payment-service-v1 (blue)
// 10% of payment requests → payment-service-v2 (green)
// Both routes in the same weight group "payment-group"

What is the rollout sequence?

The rollout is a series of weight changes, each monitored before the next step.

// Step 1: Blue 100, Green 0   → all traffic to blue (starting state)
// Step 2: Blue 90, Green 10   → canary slice to green
//   Monitor: error rate, p99 latency, business metrics
//   If healthy → continue
// Step 3: Blue 50, Green 50   → half traffic to each
//   Monitor: compare blue vs green metrics side by side
// Step 4: Blue 0, Green 100   → full cutover to green
//   Blue remains running as rollback target
// Step 5: Retire blue (optional, or keep as standby)

How does instant rollback work?

If green shows errors at any weight, shift back to blue immediately. Blue never stopped running, so the fix is a route change, not a deployment.

// Green shows elevated error rate at 10% weight:
// Immediately: shift to Blue 100, Green 0
// Total rollback time: seconds (one config change + route refresh)
// No rebuild, no redeploy, no outage

// This is the key safety property of blue-green:
// The rollback path is always one weight change away

What about database schema compatibility?

During the overlap, blue and green both read and write the shared database. Schema changes must be backward compatible using expand-and-contract migrations.

// Expand-and-contract migration:
// Phase 1 (expand): Add new column "beneficiary_name" (nullable)
//   Both v1 (blue) and v2 (green) can read/write
//   v1 ignores the new column, v2 uses it
// Phase 2 (contract): After full cutover to v2:
//   Remove old column "beneficiary_id" (no longer used)
//   Only v2 is running, safe to remove

// NEVER: rename a column while both versions are live
// v1 expects "beneficiary_id", v2 expects "beneficiary_name"
// Both break when they can't find their expected column

How is blue-green different from canary and rolling update?

| Aspect | Blue-Green | Canary | Rolling Update |
|---|---|---|---|
| Environments | Two complete (blue + green) | One + small new slice | One (in-place) |
| Traffic control | Weight-based split | Weight-based, small % | Instance-by-instance |
| Rollback speed | Instant (weight shift) | Instant (weight shift) | Slow (redeploy old) |
| Resource cost | Double capacity briefly | Slightly over capacity | Normal capacity |
| Observation | Compare metrics side by side | Focus on canary metrics | Monitor instance by instance |
| Best for | Fast cutover + instant rollback | Validating with real users | Resource-constrained |

How do you automate the weight changes safely?

Weight changes should run through an audited, automated pipeline, especially for banking where an accidental shift could send payment traffic to a broken version.

// Automated release pipeline:
// 1. Deploy green version (not receiving traffic)
// 2. Health check green → confirm healthy
// 3. Shift to 90/10 → automated metric check for 10 minutes
// 4. If metrics OK → shift to 50/50 → check for 10 minutes
// 5. If metrics OK → shift to 0/100 → full cutover
// 6. If ANY step fails → automatic rollback to 100/0

// Every weight change is:
// - Authenticated (only pipeline service account)
// - Validated (weights must sum to 100)
// - Audited (logged with timestamp, user, reason)

What are common mistakes? (wrong vs correct)

// WRONG: deploying green and immediately shifting to 100%
// No observation window → if green has bugs, all customers are affected

// CORRECT: gradual shift with monitoring at each step
// 10% → monitor → 50% → monitor → 100%

// WRONG: schema change that breaks blue during overlap
// ALTER TABLE DROP COLUMN beneficiary_id → blue crashes

// CORRECT: expand-and-contract migration
// ADD COLUMN → shift traffic → DROP old column after full cutover

What should a senior engineer know?

A senior engineer runs blue-green through an automated pipeline with automated metric gates. They understand that the double-capacity cost is brief and is the price for instant rollback. They also maintain blue as a standby for at least one release cycle.

// Senior blue-green checklist:
// 1. Both environments share the same database (compatible schema)
// 2. Expand-and-contract migrations for schema changes
// 3. Automated metric gates at each weight step
// 4. Automatic rollback on metric degradation
// 5. Audited, authenticated weight changes
// 6. Keep blue as standby for at least one release cycle
// 7. Test green with synthetic traffic before shifting real users