From 6750f10ffa8ade87d2e26bcb64ccfd74a33388c8 Mon Sep 17 00:00:00 2001
From: stefanprodan <stefan.prodan@gmail.com>
Date: Mon, 25 Feb 2019 03:07:39 +0200
Subject: [PATCH] Add HTTP match and rewrite docs

---
 README.md                      |   7 ++
 artifacts/canaries/canary.yaml |   7 ++
 docs/gitbook/how-it-works.md   | 129 ++++++++++++++++++++++++++++++++-
 3 files changed, 142 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 74b7ad1e..95c078a4 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,13 @@ spec:
     # Istio virtual service host names (optional)
     hosts:
     - podinfo.example.com
+    # Istio virtual service HTTP match conditions (optional)
+    match:
+      - uri:
+          prefix: /
+    # Istio virtual service HTTP rewrite (optional)
+    rewrite:
+      uri: /
   # for emergency cases when you want to ship changes
   # in production without analysing the canary
   skipAnalysis: false
diff --git a/artifacts/canaries/canary.yaml b/artifacts/canaries/canary.yaml
index cb1cdfbf..74206c3c 100644
--- a/artifacts/canaries/canary.yaml
+++ b/artifacts/canaries/canary.yaml
@@ -26,6 +26,13 @@ spec:
     # Istio virtual service host names (optional)
     hosts:
     - app.istio.weavedx.com
+    # Istio virtual service HTTP match conditions (optional)
+    match:
+      - uri:
+          prefix: /
+    # Istio virtual service HTTP rewrite (optional)
+    rewrite:
+      uri: /
   # for emergency cases when you want to ship changes
   # in production without analysing the canary
   skipAnalysis: false
diff --git a/docs/gitbook/how-it-works.md b/docs/gitbook/how-it-works.md
index edf35f08..a0353900 100644
--- a/docs/gitbook/how-it-works.md
+++ b/docs/gitbook/how-it-works.md
@@ -39,6 +39,13 @@ spec:
     # Istio virtual service host names (optional)
     hosts:
     - podinfo.example.com
+    # Istio virtual service HTTP match conditions (optional)
+    match:
+      - uri:
+          prefix: /
+    # Istio virtual service HTTP rewrite (optional)
+    rewrite:
+      uri: /
   # for emergency cases when you want to ship changes
   # in production without analysing the canary
   skipAnalysis: false
@@ -96,7 +103,124 @@ spec:
 The target deployment should expose a TCP port that will be used by Flagger to create the ClusterIP Service and 
 the Istio Virtual Service. The container port from the target deployment should match the `service.port` value.
 
-### Canary Deployment
+### Virtual Service
+
+Flagger creates an Istio Virtual Service based on the Canary service spec.
+
+The following spec exposes the `frontend` workload inside the mesh on `frontend.test.svc.cluster.local:9898` 
+and outside the mesh on `frontend.example.com`. You'll have to specify an Istio ingress gateway for external hosts.
+
+```yaml
+apiVersion: flagger.app/v1alpha3
+kind: Canary
+metadata:
+  name: frontend
+  namespace: test
+  service:
+    # container port
+    port: 9898
+    # Istio gateways (optional)
+    gateways:
+    - public-gateway.istio-system.svc.cluster.local
+    # Istio virtual service host names (optional)
+    hosts:
+    - frontend.example.com
+    # Istio virtual service HTTP match conditions (optional)
+    match:
+      - uri:
+          prefix: /
+    # Istio virtual service HTTP rewrite (optional)
+    rewrite:
+      uri: /
+```
+
+For the above spec Flagger will generate the following virtual service:
+
+```yaml
+apiVersion: networking.istio.io/v1alpha3
+kind: VirtualService
+metadata:
+  name: frontend
+  namespace: test
+  ownerReferences:
+    - apiVersion: flagger.app/v1alpha3
+      blockOwnerDeletion: true
+      controller: true
+      kind: Canary
+      name: podinfo
+      uid: 3a4a40dd-3875-11e9-8e1d-42010a9c0fd1
+spec:
+  gateways:
+    - public-gateway.istio-system.svc.cluster.local
+    - mesh
+  hosts:
+    - frontend.example.com
+    - frontend
+  http:
+    - match:
+        - uri:
+            prefix: /
+      rewrite:
+        uri: /
+      route:
+        - destination:
+            host: frontend-primary
+            port:
+              number: 9898
+          weight: 100
+        - destination:
+            host: frontend-canary
+            port:
+              number: 9898
+          weight: 0
+```
+
+Flagger keeps in sync the virtual service with the canary service spec. Any direct modification of the virtual 
+service spec will be overwritten.
+
+To expose a workload inside the mesh on `http://backend.test.svc.cluster.local:9898`,
+the service spec can contain only the container port:
+
+```yaml
+apiVersion: flagger.app/v1alpha3
+kind: Canary
+metadata:
+  name: backend
+  namespace: test
+spec:
+  service:
+    port: 9898
+```
+
+Based on the above spec, Flagger will create several ClusterIP services like:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: backend-primary
+  ownerReferences:
+  - apiVersion: flagger.app/v1alpha3
+    blockOwnerDeletion: true
+    controller: true
+    kind: Canary
+    name: backend
+    uid: 2ca1a9c7-2ef6-11e9-bd01-42010a9c0145
+spec:
+  type: ClusterIP
+  ports:
+  - name: http
+    port: 9898
+    protocol: TCP
+    targetPort: 9898
+  selector:
+    app: backend-primary
+```
+
+Flagger works for user facing apps exposed outside the cluster via an ingress gateway
+and for backend HTTP APIs that are accessible only from inside the mesh.
+
+### Canary Stages
 
 ![Flagger Canary Stages](https://raw.githubusercontent.com/stefanprodan/flagger/master/docs/diagrams/flagger-canary-steps.png)
 
@@ -155,6 +279,9 @@ Spec:
     # canary increment step
     # percentage (0-100)
     stepWeight: 2
+  # deploy straight to production without
+  # the metrics and webhook checks
+  skipAnalysis: false
 ```
 
 The above analysis, if it succeeds, will run for 25 minutes while validating the HTTP metrics and webhooks every minute.