Caching & Service Discovery

# Kong proxy-cache plugin configuration
plugins:
  - name: proxy-cache
    config:
      strategy: redis
      redis:
        host: redis-cache
        port: 6379
      content_type:
        - application/json
      request_method:
        - GET
        - HEAD
      response_code:
        - 200
        - 301
      cache_ttl: 300  # 5 minutes default
      vary_headers:
        - Accept
        - Accept-Language
      vary_query_params:
        - page
        - size
        - sort

# Cache key formula:
# SHA256(method + path + sorted_query_params + vary_header_values)
# Example: SHA256("GET:/api/products:page=1&size=20:accept=application/json")

# First request — gateway caches response with ETag
GET /api/products/123
Response:
  200 OK
  ETag: "abc123hash"
  Cache-Control: max-age=60
  Last-Modified: Fri, 01 Mar 2024 12:00:00 GMT
  Body: {"id": 123, "name": "Widget", "price": 9.99}

# After max-age expires — gateway revalidates
GET /api/products/123
If-None-Match: "abc123hash"
If-Modified-Since: Fri, 01 Mar 2024 12:00:00 GMT

# If unchanged — upstream returns 304 (no body transfer)
Response:
  304 Not Modified
  ETag: "abc123hash"

# Gateway serves cached body — saves bandwidth and backend processing

# Explicit purge — delete specific cached response
curl -X PURGE https://gateway.internal/cache/api/products/123

# Tag-based purge — invalidate all product-related cache entries
curl -X POST https://gateway.internal/cache/purge   -H "Content-Type: application/json"   -d '{"tags": ["products", "catalog"]}'

# Surrogate key approach — backend includes keys in response
# Response from upstream:
#   Surrogate-Key: product-123 category-electronics all-products
#
# When product 123 changes:
curl -X POST https://gateway.internal/cache/purge   -d '{"surrogate_key": "product-123"}'
# Purges all cached responses tagged with "product-123"

# Static configuration — hardcoded upstreams
upstreams:
  - name: order-service
    targets:
      - target: 10.0.1.10:8080
        weight: 100
      - target: 10.0.1.11:8080
        weight: 100
      - target: 10.0.1.12:8080
        weight: 100
    # Problem: when order-service scales to 5 instances,
    # you must manually update this config and reload

---
# Dynamic configuration — DNS-based
upstreams:
  - name: order-service
    host: order-service.internal  # DNS resolves to current IPs
    dns_resolver: 10.0.0.2
    dns_ttl: 30  # Re-resolve every 30 seconds
    # Automatically picks up new instances when DNS updates

# Kong with Consul service discovery
upstreams:
  - name: order-service
    algorithm: round-robin
    healthchecks:
      active:
        http_path: /health
        healthy:
          interval: 5
          successes: 2
        unhealthy:
          interval: 5
          http_failures: 3

# Kong queries Consul for healthy instances:
# GET /v1/health/service/order-service?passing=true
#
# Returns:
# [
#   {"Service": {"Address": "10.0.1.10", "Port": 8080}},
#   {"Service": {"Address": "10.0.1.11", "Port": 8080}}
# ]
#
# Gateway updates upstream targets automatically

# Envoy with Kubernetes Endpoint Discovery Service (EDS)
clusters:
  - name: order-service
    type: EDS
    eds_cluster_config:
      eds_config:
        api_config_source:
          api_type: GRPC
          grpc_services:
            - envoy_grpc:
                cluster_name: xds-cluster
    # Envoy watches Kubernetes Endpoints via xDS API
    # New pods automatically added, terminated pods removed
    # Zero config changes needed for scaling events

# Combined active + passive health checking
upstreams:
  - name: payment-service
    healthchecks:
      active:
        type: http
        http_path: /health
        healthy:
          interval: 5          # Check every 5 seconds
          successes: 2         # Mark healthy after 2 consecutive successes
          http_statuses: [200]
        unhealthy:
          interval: 2          # Check more frequently when unhealthy
          http_failures: 3     # Mark unhealthy after 3 consecutive failures
          tcp_failures: 2
          timeouts: 3
          http_statuses: [500, 502, 503]
      passive:
        healthy:
          successes: 5         # Mark healthy after 5 successful real requests
          http_statuses: [200, 201, 204]
        unhealthy:
          http_failures: 5     # Mark unhealthy after 5 failed real requests
          tcp_failures: 2
          timeouts: 3
          http_statuses: [500, 502, 503]