From 2e54ef4a31f2f184705085186152115ee27472cc Mon Sep 17 00:00:00 2001
From: stefanprodan <stefan.prodan@gmail.com>
Date: Mon, 9 Mar 2020 12:11:56 +0200
Subject: [PATCH] docs: Add Istio telemetry v2 to upgrade guide

---
 docs/gitbook/dev/upgrade-guide.md             | 46 +++++++++++++++++++
 docs/gitbook/tutorials/istio-ab-testing.md    |  3 ++
 .../tutorials/istio-progressive-delivery.md   |  3 ++
 3 files changed, 52 insertions(+)

diff --git a/docs/gitbook/dev/upgrade-guide.md b/docs/gitbook/dev/upgrade-guide.md
index c5f2b503d..2700bd463 100644
--- a/docs/gitbook/dev/upgrade-guide.md
+++ b/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
+```
diff --git a/docs/gitbook/tutorials/istio-ab-testing.md b/docs/gitbook/tutorials/istio-ab-testing.md
index e47afce8c..353c3b5b8 100644
--- a/docs/gitbook/tutorials/istio-ab-testing.md
+++ b/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:
diff --git a/docs/gitbook/tutorials/istio-progressive-delivery.md b/docs/gitbook/tutorials/istio-progressive-delivery.md
index 413f4b40b..9cc930d65 100644
--- a/docs/gitbook/tutorials/istio-progressive-delivery.md
+++ b/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