From a21e53fa31dea1a3c124252809ec2a303c12dfba Mon Sep 17 00:00:00 2001
From: Andrew Jenkins <andrew@aspenmesh.io>
Date: Tue, 24 Sep 2019 17:16:41 -0600
Subject: [PATCH] Document traffic mirroring in the FAQ

---
 docs/gitbook/faq.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/gitbook/faq.md b/docs/gitbook/faq.md
index 1ae56485..9bf2e75b 100644
--- a/docs/gitbook/faq.md
+++ b/docs/gitbook/faq.md
@@ -102,6 +102,50 @@ The above configuration will run an analysis for five minutes.
 Flagger starts the load test for the canary service (green version) and checks the Prometheus metrics every 30 seconds.
 If the analysis result is positive, Flagger will promote the canary (green version) to primary (blue version).
 
+**When can I use traffic mirroring?**
+
+Traffic Mirroring is a pre-stage in a Canary (progressive traffic shifting) or
+Blue/Green deployment strategy.  Traffic mirroring will copy each incoming
+request, sending one request to the primary and one to the canary service.  The
+response from the primary is sent back to the user.  The response from the canary
+is discarded.  Metrics are collected on both requests so that the deployment will
+only proceed if the canary metrics are healthy.
+
+Mirroring is supported by Istio only.
+
+In Istio, mirrored requests have `-shadow` appended to the `Host` (HTTP) or
+`Authority` (HTTP/2) header; for example requests to `podinfo.test` that are
+mirrored will be reported in telemetry with a destination host
+`podinfo.test-shadow`.
+
+Mirroring must only be used for requests that are **idempotent** or capable of
+being processed twice (once by the primary and once by the canary).  Reads are
+idempotent.  Before using mirroring on requests that may be writes, you should
+consider what will happen if a write is duplicated and handled by the primary
+and canary.
+
+To use mirroring, set `spec.canaryAnalysis.mirror` to `true`.  Example for
+traffic shifting:
+
+```yaml
+apiVersion: flagger.app/v1alpha3
+kind: Canary
+spec:
+  provider: istio
+  canaryAnalysis:
+    interval: 30s
+    mirror: true
+    stepWeight: 20
+    maxWeight: 50
+    metrics:
+    - interval: 29s
+      name: request-success-rate
+      threshold: 99
+    - interval: 29s
+      name: request-duration
+      threshold: 500
+```
+
 ### Kubernetes services
 
 **How is an application exposed inside the cluster?**