Merge pull request #486 from weaveworks/docs-istio-telemetry-v2

docs: Add Istio telemetry v2 to upgrade guide

docs/gitbook/dev/upgrade-guide.md

@@ -39,3 +39,49 @@ metrics:
     max: 500
   interval: 1m
 ```
+
+### Istio telemetry v2
+
+Istio 1.5 comes with a breaking change for Flagger uses. In Istio telemetry v2 the metric 
+`istio_request_duration_seconds_bucket` has been removed and replaced with `istio_request_duration_milliseconds_bucket`
+and this breaks the `request-duration` metric check.
+
+You can create a metric template using the new duration metric like this:
+
+```yaml
+apiVersion: flagger.app/v1beta1
+kind: MetricTemplate
+metadata:
+  name: latency
+  namespace: istio-system
+spec:
+  provider:
+    type: prometheus
+    address: http://prometheus.istio-system:9090
+  query: |
+    histogram_quantile(
+        0.99,
+        sum(
+            rate(
+                istio_request_duration_milliseconds_bucket{
+                    reporter="destination",
+                    destination_workload_namespace="{{ namespace }}",
+                    destination_workload=~"{{ target }}"
+                }[{{ interval }}]
+            )
+        ) by (le)
+    )
+```
+
+In the canary manifests, replace the `request-duration` metric with `latency`:
+
+```yaml
+metrics:
+- name: latency
+  templateRef:
+    name: latency
+    namespace: istio-system
+  thresholdRange:
+    max: 500
+  interval: 1m
+```

docs/gitbook/tutorials/istio-ab-testing.md

@@ -138,6 +138,9 @@ spec:
           cmd: "hey -z 1m -q 10 -c 2 -H 'Cookie: type=insider' http://podinfo.test:9898/"
 ```
 
+**Note** that when using Istio 1.5 you have to replace the `request-duration`
+with a [metric template](https://docs.flagger.app/dev/upgrade-guide#istio-telemetry-v2).
+
 The above configuration will run an analysis for ten minutes targeting Safari users and those that have an insider cookie.
 
 Save the above resource as podinfo-abtest.yaml and then apply it:

docs/gitbook/tutorials/istio-progressive-delivery.md

@@ -149,6 +149,9 @@ spec:
           cmd: "hey -z 1m -q 10 -c 2 http://podinfo-canary.test:9898/"
 ```
 
+**Note** that when using Istio 1.5 you have to replace the `request-duration`
+with a [metric template](https://docs.flagger.app/dev/upgrade-guide#istio-telemetry-v2).
+
 Save the above resource as podinfo-canary.yaml and then apply it:
 
 ```bash