add recipes for envoyfilter migration (#13360)

* add recipes Signed-off-by: Kuat Yessenov <kuat@google.com> * lint Signed-off-by: Kuat Yessenov <kuat@google.com> * lint Signed-off-by: Kuat Yessenov <kuat@google.com> * lint Signed-off-by: Kuat Yessenov <kuat@google.com> * spelling Signed-off-by: Kuat Yessenov <kuat@google.com> * review Signed-off-by: Kuat Yessenov <kuat@google.com> * update link Signed-off-by: Kuat Yessenov <kuat@google.com> * fix lint Signed-off-by: Kuat Yessenov <kuat@google.com> * review Signed-off-by: Kuat Yessenov <kuat@google.com> * add spelling Signed-off-by: Kuat Yessenov <kuat@google.com> * review Signed-off-by: Kuat Yessenov <kuat@google.com> * review Signed-off-by: Kuat Yessenov <kuat@google.com> --------- Signed-off-by: Kuat Yessenov <kuat@google.com>
2023-06-27 13:56:30 -07:00 · 2023-06-27 13:56:30 -07:00 · c2af091e64
parent 73afe3395d
commit c2af091e64
2 changed files with 150 additions and 0 deletions
--- a/.spelling
+++ b/.spelling
@ -405,6 +405,7 @@ enablement
 endUser-to-Service
 enum
 env
+EnvoyFilter
 envoyproxy
 etcd
 events.istio.io
--- a/content/en/docs/ops/common-problems/upgrade-issues/index.md
+++ b/content/en/docs/ops/common-problems/upgrade-issues/index.md
@ -0,0 +1,149 @@
+---
+title: Upgrade Problems
+description: Resolve common problems with Istio upgrades.
+weight: 60
+owner: istio/wg-policies-and-telemetry-maintainers
+test: n/a
+---
+
+## EnvoyFilter migration
+
+`EnvoyFilter` is an alpha API that is tightly coupled to the implementation
+details of Istio xDS configuration generation. Production use of the
+`EnvoyFilter` alpha API must be carefully curated during the upgrade of Istio's
+control or data plane. In many instances, `EnvoyFilter` can be replaced with a
+first-class Istio API which carries substantially lower upgrade risks.
+
+### Use Telemetry API for metrics customization
+
+The usage of `IstioOperator` to customize Prometheus metrics generation has been
+replaced by the [Telemetry API](/docs/tasks/observability/metrics/customize-metrics/),
+because `IstioOperator` relies on a template `EnvoyFilter` to change the
+metrics filter configuration. Note that the two methods are incompatible, and
+the Telemetry API does not work with `EnvoyFilter` or `IstioOperator` metric
+customization configuration.
+
+As an example, the following `IstioOperator` configuration adds a `destination_port` tag:
+
+{{< text yaml >}}
+apiVersion: install.istio.io/v1alpha1
+kind: IstioOperator
+spec:
+  values:
+    telemetry:
+      v2:
+        prometheus:
+          configOverride:
+            inboundSidecar:
+              metrics:
+                - name: requests_total
+                  dimensions:
+                    destination_port: string(destination.port)
+{{< /text >}}
+
+The following `Telemetry` configuration replaces the above:
+
+{{< text yaml >}}
+apiVersion: telemetry.istio.io/v1alpha1
+kind: Telemetry
+metadata:
+  name: namespace-metrics
+spec:
+  metrics:
+  - providers:
+    - name: prometheus
+    overrides:
+    - match:
+        metric: REQUEST_COUNT
+      mode: SERVER
+      tagOverrides:
+        destination_port:
+          value: "string(destination.port)"
+{{< /text >}}
+
+### Use the WasmPlugin API for Wasm data plane extensibility
+
+The usage of `EnvoyFilter` to inject Wasm filters has been replaced by the
+[WasmPlugin API](/docs/tasks/extensibility/wasm-module-distribution).
+WasmPlugin API allows dynamic loading of the plugins from artifact registries,
+URLs, or local files. The "Null" plugin runtime is no longer a recommended option
+for deployment of Wasm code.
+
+### Use gateway topology to set the number of the trusted hops
+
+The usage of `EnvoyFilter` to configure the number of the trusted hops in the
+HTTP connection manager has been replaced by the `gatewayTopology` field in
+[`ProxyConfig`](/docs/ops/configuration/traffic-management/network-topologies).
+For example, the following `EnvoyFilter` configuration should use an annotation
+on the pod or the mesh default. Instead of:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: EnvoyFilter
+metadata:
+  name: ingressgateway-redirect-config
+spec:
+  configPatches:
+  - applyTo: NETWORK_FILTER
+    match:
+      context: GATEWAY
+      listener:
+        filterChain:
+          filter:
+            name: envoy.filters.network.http_connection_manager
+    patch:
+      operation: MERGE
+      value:
+        typed_config:
+          '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          xff_num_trusted_hops: 1
+  workloadSelector:
+    labels:
+      istio: ingress-gateway
+{{< /text >}}
+
+Use the equivalent ingress gateway proxy configuration annotation:
+
+{{< text yaml >}}
+metadata:
+  annotations:
+    "proxy.istio.io/config": '{"gatewayTopology" : { "numTrustedProxies": 1 }}'
+{{< /text >}}
+
+### Use a proxy annotation to customize the histogram bucket sizes
+
+The usage of `EnvoyFilter` and the experimental bootstrap discovery service to
+configure the bucket sizes for the histogram metrics has been replaced by the
+proxy annotation `sidecar.istio.io/statsHistogramBuckets`. For example, the
+following `EnvoyFilter` configuration should use an annotation on the pod.
+Instead of:
+
+{{< text yaml >}}
+apiVersion: networking.istio.io/v1alpha3
+kind: EnvoyFilter
+metadata:
+  name: envoy-stats-1
+  namespace: istio-system
+spec:
+  workloadSelector:
+    labels:
+      istio: ingressgateway
+  configPatches:
+  - applyTo: BOOTSTRAP
+    patch:
+      operation: MERGE
+      value:
+        stats_config:
+          histogram_bucket_settings:
+            - match:
+                prefix: istiocustom
+              buckets: [1,5,50,500,5000,10000]
+{{< /text >}}
+
+Use the equivalent pod annotation:
+
+{{< text yaml >}}
+metadata:
+  annotations:
+    "sidecar.istio.io/statsHistogramBuckets": '{"istiocustom":[1,5,50,500,5000,10000]}'
+{{< /text >}}