From a7c242e437dd3119fd1c65cc073537d33f395e51 Mon Sep 17 00:00:00 2001
From: stefanprodan <stefan.prodan@gmail.com>
Date: Fri, 20 Dec 2019 18:26:18 +0200
Subject: [PATCH] Add user agent match examples to Contour docs

---
 .../usage/contour-progressive-delivery.md     | 64 +++++++++++++------
 1 file changed, 46 insertions(+), 18 deletions(-)

diff --git a/docs/gitbook/usage/contour-progressive-delivery.md b/docs/gitbook/usage/contour-progressive-delivery.md
index c82888f2..9ff10c36 100644
--- a/docs/gitbook/usage/contour-progressive-delivery.md
+++ b/docs/gitbook/usage/contour-progressive-delivery.md
@@ -1,6 +1,6 @@
 # Contour Canary Deployments
 
-This guide shows you how to use the Contour ingress controller and Flagger to automate canary releases and A/B testing. 
+This guide shows you how to use [Contour](https://projectcontour.io/) ingress controller and Flagger to automate canary releases and A/B testing. 
 
 ![Flagger Contour Overview](https://raw.githubusercontent.com/weaveworks/flagger/master/docs/diagrams/flagger-contour-overview.png)
 
@@ -16,6 +16,16 @@ kubectl apply -f https://projectcontour.io/quickstart/contour.yaml
 
 The above command will deploy Contour and an Envoy daemonset in the `projectcontour` namespace.
 
+Find the external address of Contour's Envoy load balancer:
+
+```bash
+export ADDRESS="$(kubectl -n projectcontour get svc/envoy -ojson \
+| jq -r ".status.loadBalancer.ingress[].hostname")"
+echo $ADDRESS
+```
+
+Configure your DNS server with a CNAME record (AWS) or A record (GKE) and point a domain e.g. `app.example.com` to the LB address.
+
 Install Flagger using Kustomize (kubectl 1.14) in the `projectcontour` namespace:
 
 ```bash
@@ -26,7 +36,7 @@ The above command will deploy Flagger and Prometheus configured to scrape the Co
 You can also enable Slack or MS Teams notifications,
 see the Kustomize install [docs](https://docs.flagger.app/install/flagger-install-on-kubernetes#install-flagger-with-kustomize).
 
-You can install Flagger using Helm v2 or v3:
+Or you can install Flagger using Helm:
 
 ```sh
 helm repo add flagger https://flagger.app
@@ -64,7 +74,7 @@ Create a deployment and a horizontal pod autoscaler:
 kubectl apply -k github.com/weaveworks/flagger//kustomize/podinfo
 ```
 
-Create a canary custom resource:
+Create a canary custom resource (replace `app.example.com` with your own domain):
 
 ```yaml
 apiVersion: flagger.app/v1alpha3
@@ -114,8 +124,7 @@ spec:
       threshold: 99
       interval: 1m
     - name: request-duration
-      # maximum req duration P99
-      # milliseconds
+      # maximum req duration P99 in milliseconds
       threshold: 500
       interval: 30s
     # testing
@@ -141,7 +150,6 @@ Save the above resource as podinfo-canary.yaml and then apply it:
 kubectl apply -f ./podinfo-canary.yaml
 ```
 
-When the canary analysis starts, Flagger will call the pre-rollout webhooks before routing traffic to the canary.
 The canary analysis will run for five minutes while validating the HTTP metrics and rollout hooks every half a minute.
 
 After a couple of seconds Flagger will create the canary objects:
@@ -166,15 +174,6 @@ to the primary pods. During the canary analysis, the `podinfo-canary.test` addre
 
 ### Expose the app outside the cluster
 
-Find the external address of Contour's Envoy load balancer:
-
-```bash
-export ADDRESS="$(kubectl -n projectcontour get svc/envoy -ojson | jq -r ".status.loadBalancer.ingress[].hostname")"
-echo $ADDRESS
-```
-
-Configure your DNS server with a CNAME record (AWS) or A record (GKE) and point a domain e.g. `app.example.com` to the LB address.
-
 Create a HTTPProxy definition and include the podinfo proxy generated by Flagger (replace `app.example.com` with your own domain):
 
 ```yaml
@@ -209,7 +208,7 @@ podinfo                               valid
 podinfo-ingress   app.example.com     valid
 ```
 
-Now you can access podinfo using your domain address.
+Now you can access podinfo UI using your domain address.
 
 ### Automated canary promotion
 
@@ -319,8 +318,8 @@ Advance podinfo.test canary weight 15
 Halt podinfo.test advancement success rate 69.17% < 99%
 Halt podinfo.test advancement success rate 61.39% < 99%
 Halt podinfo.test advancement success rate 55.06% < 99%
-Halt podinfo.test advancement request duration 1.20s > 0.5s
-Halt podinfo.test advancement request duration 1.45s > 0.5s
+Halt podinfo.test advancement request duration 1.20s > 500ms
+Halt podinfo.test advancement request duration 1.45s > 500ms
 Rolling back podinfo.test failed checks threshold reached 5
 Canary failed! Scaling down podinfo.test
 ```
@@ -400,3 +399,32 @@ Waiting for podinfo-primary.test rollout to finish: 1 of 2 updated replicas are
 Routing all traffic to primary
 Promotion completed! Scaling down podinfo.test
 ```
+
+The web browser user agent header allows user segmentation based on device or OS.
+
+For example, if you want to route all mobile users to the canary instance:
+
+```yaml
+match:
+- headers:
+    user-agent:
+      prefix: "Mobile"
+```
+
+Or if you want to target only Android users:
+
+```yaml
+match:
+- headers:
+    user-agent:
+      prefix: "Android"
+```
+
+Or a specific browser version:
+
+```yaml
+match:
+- headers:
+    user-agent:
+      suffix: "Firefox/71.0"
+```