5.7 KiB
| title | description | weight | owner | test |
|---|---|---|---|---|
| Upgrade Problems | Resolve common problems with Istio upgrades. | 60 | istio/wg-policies-and-telemetry-maintainers | 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,
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.
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.
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 pod proxy configuration annotation:
{{< text yaml >}} metadata: annotations: "proxy.istio.io/config": '{"gatewayTopology" : { "numTrustedProxies": 1 }}' {{< /text >}}
Use gateway topology to enable PROXY protocol on the ingress gateways
The usage of EnvoyFilter to enable PROXY
protocol on the
ingress gateways has been replaced by the
gatewayTopology
field in
ProxyConfig.
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: proxy-protocol spec: configPatches:
- applyTo: LISTENER_FILTER patch: operation: INSERT_FIRST value: name: proxy_protocol typed_config: "@type": "type.googleapis.com/envoy.extensions.filters.listener.proxy_protocol.v3.ProxyProtocol" workloadSelector: labels: istio: ingress-gateway {{< /text >}}
Use the equivalent ingress gateway pod proxy configuration annotation:
{{< text yaml >}} metadata: annotations: "proxy.istio.io/config": '{"gatewayTopology" : { "proxyProtocol": {} }}' {{< /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 >}}