Add migration guide for mtls annotation. (#1414)

content/docs/setup/kubernetes/upgrading-istio.md

@@ -103,3 +103,96 @@ spec:
 ```
 
 When all your applications have been migrated and tested, you can repeat the istio upgrade process, removing the `--set global.proxy.image=proxy` option.
+
+### Migrating per-service mutual TLS enablement via annotations to authentication policy
+
+If you use service annotations to override global mutual TLS enablement for a service, you need to replace it with [authentication policy](/docs/concepts/security/authn-policy/) and [destination rules](/docs/concepts/traffic-management/rules-configuration/#destination-rules).
+
+For example, if you install Istio with mutual TLS enabled, and disable it for service `foo` using a service annotation like below:
+
+```yaml
+kind: Service
+metadata:
+  name: foo
+  namespace: bar
+  annotations:
+    auth.istio.io/8000: NONE
+```
+
+You need to replace this with this authentication policy and destination rule (deleting the old annotation is optional)
+
+```yaml
+apiVersion: "authentication.istio.io/v1alpha1"
+kind: "Policy"
+metadata:
+  name: "disable-mTLS-foo"
+  namespace: bar
+spec:
+  targets:
+  - name: foo
+    ports:
+    - number: 8000
+  peers:
+---
+apiVersion: "networking.istio.io/v1alpha3"
+kind: "DestinationRule"
+metadata:
+  name: "disable-mTLS-foo"
+  namespace: "bar"
+spec:
+  host: "foo"
+  trafficPolicy:
+    tls:
+      mode: ISTIO_MUTUAL
+    portLevelSettings:
+    - port:
+        number: 8000
+      tls:
+        mode: DISABLE
+```
+
+If you already have destination rules for `foo`, you must edit that rule instead of creating a new one.
+When create a new destination rule, make sure to include other settings, i.e `load balancer`, `connection pool` and `outlier detection` if necessary.
+Finally, If `foo` doesn't have sidecar, you can skip authentication policy, but still need to add destination rule.
+
+If 8000 is the only port that service `foo` provides (or you want to disable mutual TLS for all ports), the policies can be simplified as:
+
+```yaml
+apiVersion: "authentication.istio.io/v1alpha1"
+kind: "Policy"
+metadata:
+  name: "disable-mTLS-foo"
+    namespace: bar
+  spec:
+    targets:
+    - name: foo
+    peers:
+---
+apiVersion: "networking.istio.io/v1alpha3"
+kind: "DestinationRule"
+metadata:
+  name: "disable-mTLS-foo"
+  namespace: "bar"
+spec:
+  host: "foo"
+trafficPolicy:
+  tls:
+    mode: DISABLE
+```
+
+### Migrating `mtls_excluded_services` config to destination rules
+
+If you installed Istio with mutual TLS enabled, and used mesh config `mtls_excluded_services` to disable mutual TLS when connecting to these services (e.g kubernetes API server), you need to replace this by adding a destination rule. For example:
+
+```yaml
+apiVersion: networking.istio.io/v1alpha3
+kind: DestinationRule
+metadata:
+  name: "kubernetes-master"
+  namespace: "default"
+spec:
+  host: "kubernetes.default.svc.cluster.local"
+  trafficPolicy:
+    tls:
+      mode: DISABLE
+```