Versioning & Traffic Management

# URL path versioning — gateway routes to different services
services:
  - name: users-v1
    url: http://user-service-v1:8080
    routes:
      - name: users-v1-route
        paths:
          - /api/v1/users
        strip_path: true

  - name: users-v2
    url: http://user-service-v2:8080
    routes:
      - name: users-v2-route
        paths:
          - /api/v2/users
        strip_path: true

# Header-based versioning — single path, route by header
  - name: users-v2-header
    url: http://user-service-v2:8080
    routes:
      - name: users-header-route
        paths:
          - /api/users
        headers:
          X-API-Version:
            - "2"
        strip_path: true

# Envoy weighted cluster routing
route_config:
  virtual_hosts:
    - name: api
      domains: ["api.example.com"]
      routes:
        - match:
            prefix: "/api/orders"
          route:
            weighted_clusters:
              clusters:
                - name: order-service-v1
                  weight: 90
                - name: order-service-v2
                  weight: 10
              total_weight: 100

# Shadow traffic — mirror to v2 without affecting clients
        - match:
            prefix: "/api/products"
          route:
            cluster: product-service-v1
            request_mirror_policies:
              - cluster: product-service-v2
                runtime_fraction:
                  default_value:
                    numerator: 100  # Mirror 100% of traffic
                    denominator: HUNDRED

# Gateway canary configuration
routes:
  - name: order-api
    path: /api/v1/orders
    canary:
      enabled: true
      target: order-service-v2
      stable: order-service-v1
      weight: 5  # 5% to canary

      # Header override — developers can force canary
      header_override:
        name: X-Canary
        value: "true"

      # Automatic rollback conditions
      rollback:
        error_rate_threshold: 5.0    # Rollback if > 5% errors
        latency_p99_threshold: 2000  # Rollback if p99 > 2 seconds
        evaluation_window: 300       # Evaluate over 5 minutes
        min_requests: 100            # Need 100 requests before evaluating

# Blue-green deployment at the gateway
upstreams:
  blue:
    targets:
      - blue-cluster-1:8080
      - blue-cluster-2:8080
      - blue-cluster-3:8080

  green:
    targets:
      - green-cluster-1:8080
      - green-cluster-2:8080
      - green-cluster-3:8080

routes:
  - name: all-traffic
    path: /api/
    upstream: blue  # Currently serving from blue

# Deployment process:
# 1. Deploy new version to green cluster
# 2. Run smoke tests against green directly
# 3. Switch: upstream: blue → upstream: green
# 4. Monitor for 5 minutes
# 5. If issues: switch back to blue (instant rollback)
# 6. If stable: blue becomes the next deployment target

# RFC 8594 — Sunset header
# Gateway injects these headers on deprecated endpoints

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jun 2025 00:00:00 GMT
Link: <https://docs.example.com/migration/v1-to-v2>; rel="successor-version"
Link: <https://docs.example.com/deprecation-policy>; rel="deprecation"

# After sunset date — gateway blocks with 410 Gone
HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "API_VERSION_SUNSET",
  "message": "API v1 was sunset on 2025-06-01. Please migrate to v2.",
  "migration_guide": "https://docs.example.com/migration/v1-to-v2",
  "successor": "https://api.example.com/v2/"
}

{
  "v1": {
    "POST /users": {
      "type": "object",
      "required": ["name", "email"],
      "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"}
      }
    }
  },
  "v2": {
    "POST /users": {
      "type": "object",
      "required": ["first_name", "last_name", "email"],
      "properties": {
        "first_name": {"type": "string", "minLength": 1},
        "last_name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "phone": {"type": "string", "pattern": "^\+[1-9]\d{1,14}$"}
      }
    }
  }
}

# A/B test configuration at the gateway
ab_tests:
  - name: checkout-flow-v2
    enabled: true
    routes:
      - /api/v1/checkout
      - /api/v1/cart

    # Consistent assignment — same user always gets same variant
    assignment:
      method: hash        # Hash user ID for consistent assignment
      key: X-User-ID     # Header containing user identifier
      salt: "checkout-v2-2024"  # Change salt to re-randomize

    variants:
      - name: control
        weight: 50
        upstream: checkout-service-v1
      - name: treatment
        weight: 50
        upstream: checkout-service-v2

    # Gateway adds variant header for downstream tracking
    response_headers:
      X-AB-Test: checkout-flow-v2
      X-AB-Variant: "{{variant_name}}"

    # Segment targeting — only test on specific users
    targeting:
      include:
        - header: X-User-Plan
          values: ["pro", "enterprise"]
      exclude:
        - header: X-User-Country
          values: ["CN", "RU"]  # Exclude due to latency differences