When you upgrade from Istio 1.8 to Istio 1.9.x, you need to consider the changes on this page. These notes detail the changes which purposefully break backwards compatibility with Istio 1.8. The notes also mention changes which preserve backwards compatibility while introducing new behavior. Changes are only included if the new behavior would be unexpected to a user of Istio 1.8.
PeerAuthentication per-port-level configuration will now also apply to pass through filter chains
Previously the PeerAuthentication per-port-level configuration is ignored if the port number is not defined in a service and the traffic will be handled by a pass through filter chain. Now the per-port-level setting will be supported even if the port number is not defined in a service, a special pass through filter chain will be added to respect the corresponding per-port-level mTLS specification. Please check your PeerAuthentication to make sure you are not using the per-port-level configuration on pass through filter chains, it was not a supported feature and you should update your PeerAuthentication accordingly if you are currently relying on the unsupported behavior before the upgrade. You don’t need to do anything if you are not using per-port-level PeerAuthentication on pass through filter chains.
Service Tags added to trace spans
Istio now configures Envoy to include tags identifying the canonical service for a workload in generated trace spans.
This will lead to a small increase in storage per span for tracing backends.
To disable these additional tags, modify the ‘istiod’ deployment to set an environment variable of
EnvoyFilter XDS v2 removal
Envoy has removed support for the XDS v2 API.
EnvoyFilters depending on these APIs must be updated before upgrading.
apiVersion: networking.istio.io/v1alpha3 kind: EnvoyFilter metadata: name: add-header spec: configPatches: - applyTo: HTTP_FILTER match: context: SIDECAR_OUTBOUND listener: filterChain: filter: name: envoy.http_connection_manager subFilter: name: envoy.router patch: operation: INSERT_BEFORE value: name: envoy.lua typed_config: "@type": type.googleapis.com/envoy.config.filter.http.lua.v2.Lua inlineCode: | function envoy_on_request(handle) handle:headers():add("foo", "bar") end
Should be updated to:
apiVersion: networking.istio.io/v1alpha3 kind: EnvoyFilter metadata: name: add-header spec: configPatches: - applyTo: HTTP_FILTER match: context: SIDECAR_OUTBOUND listener: filterChain: filter: name: envoy.filters.network.http_connection_manager subFilter: name: envoy.filters.http.router patch: operation: INSERT_BEFORE value: name: envoy.lua typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua inlineCode: | function envoy_on_request(handle) handle:headers():add("foo", "bar") end
istioctl analyze and the validating webhook (run during
kubectl apply) will warn about deprecated usage:
$ kubectl apply -f envoyfilter.yaml Warning: using deprecated filter name "envoy.http_connection_manager"; use "envoy.filters.network.http_connection_manager" instead Warning: using deprecated filter name "envoy.router"; use "envoy.filters.http.router" instead Warning: using deprecated type_url(s); type.googleapis.com/envoy.config.filter.http.lua.v2.Lua envoyfilter.networking.istio.io/add-header configured
If these filters are applied, the Envoy proxy will reject the configuration (
The v2 xDS major version is deprecated and disabled by default.) and be unable to receive updated configurations.
In general, we recommend that
EnvoyFilters are applied to a specific version to ensure Envoy changes do not break them during upgrade. This can be done with a
match: proxy: proxyVersion: ^1\.9.*
However, since Istio 1.8 supports both v2 and v3 XDS versions, your
EnvoyFilters may also be updated before upgrading Istio.