Upgrade Notes

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 PILOT_ENABLE_ISTIO_TAGS=false.

EnvoyFilter XDS v2 removal

Envoy has removed support for the XDS v2 API. EnvoyFilters depending on these APIs must be updated before upgrading.

For example:

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

Both 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 clause:

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.