Traffic Mirroring

Traffic mirroring (also known as shadow traffic) allows the API Gateway to duplicate incoming requests and send copies to a secondary service without affecting the original request-response flow. This is useful for testing new service versions, validating behavior under production traffic, or populating caches in a new environment.

Mirror Configuration

MirrorConfig Properties

Configure Traffic Mirroring

Endpoint: POST /api/v1/gateway/routes/:routeName/mirror

curl -X POST http://localhost:8080/api/v1/gateway/routes/ai-service-route/mirror \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "mirrorHost": "ai-service-v2-staging.internal",
    "mirrorPort": 8000,
    "percentage": 50,
    "synchronous": false,
    "logResponses": true
  }'

This mirrors 50% of traffic hitting the ai-service-route to the staging instance of the v2 service.

How It Works

When configureTrafficMirroring is called, the service enables the traffic-mirror Kong plugin on the specified route with the provided configuration:

1. The original request is processed normally and the response is returned to the client
2. A copy of the request is sent to the mirror host asynchronously (by default)
3. If synchronous is set to true, the gateway waits for the mirror response before returning
4. If logResponses is enabled, mirror responses are logged for comparison

Traffic Flow

Client Request
      |
      v
  Kong Route (ai-service-route)
      |
      +---> Primary Backend (ai-service:8000) --> Response to Client
      |
      +---> Mirror Backend (ai-service-v2:8000) --> Response logged/discarded
           (async, no impact on client)

Use Cases

Pre-Production Validation

Mirror production traffic to a staging environment to validate that a new version handles real traffic correctly before promotion:

{
  "mirrorHost": "ai-service-staging.internal",
  "mirrorPort": 8000,
  "percentage": 100,
  "synchronous": false,
  "logResponses": true
}

Performance Benchmarking

Mirror a subset of traffic to a performance testing instance to measure how a new version handles load:

{
  "mirrorHost": "ai-service-perf.internal",
  "mirrorPort": 8000,
  "percentage": 25,
  "synchronous": false,
  "logResponses": false
}

Cache Warming

Mirror traffic to a new instance to warm its caches before it starts receiving direct traffic:

{
  "mirrorHost": "ai-service-new-replica.internal",
  "mirrorPort": 8000,
  "percentage": 100,
  "synchronous": false,
  "logResponses": false
}

Disabling Mirroring

To disable traffic mirroring, remove the mirror plugin from the route by disabling the associated plugin. Use the plugin management endpoints described in the Plugins page.