When you upgrade from Istio 1.7.x to Istio 1.8.x, you need to consider the changes on this page. These notes detail the changes which purposefully break backwards compatibility with Istio 1.7.x. 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.7.x.
.global Stub Domain Deprecation
As part of this release, Istio has switched to a new configuration for
multi-primary (formerly “replicated control planes”). The new
configuration is simpler, has fewer limitations, and has been thoroughly
tested in a variety of environments. As a result, the
domain is now deprecated and no longer guaranteed to work going forward.
Mixer is no longer supported in Istio
If you are using the
istio-telemetry services, or any
related Mixer configuration, you will not be able to upgrade without taking
action to either (a) convert your existing configuration and code to the new
extension model for Istio or (b) use the gRPC shim developed to bridge
transition to the new model. For more details, please refer to the developer wiki.
The semantics of revision for gateways in
IstioOperator has changed from 1.7 to 1.8
revision means you are creating a new gateway with a different revision so it would
not conflict with the default gateway. In 1.8, it means the revision of istiod the gateway
is configuring with. If you are using revision for gateways in
IstioOperator in 1.7,
before moving to 1.8, you must upgrade it to the revision of the Istiod (or delete
the revision if you don’t use revision). See Issue #28849.
Istio CoreDNS Plugin Deprecation
The Istio sidecar now provides native support for DNS resolution with
meshConfig.defaultConfig.proxyMetadata.ISTIO_META_DNS_CAPTURE="true". Previously, this support
was provided by the third party Istio CoreDNS plugin.
As a result, the
istio-coredns-plugin is now deprecated and will be removed in a future release.
Use the new filter names for
If you are using
EnvoyFilter API, it is recommended to change to the new filter names as described in Envoy’s deprecation notice
The deprecated filter names will be supported in this release for backward compatibility but will be removed in future releases.
Inbound Cluster Name Format
The format of inbound Envoy cluster names has changed. Previously, they included the Service hostname
and port name, such as
inbound|80|http|httpbin.default.svc.cluster.local. This lead to issues when multiple
Services select the same pod. As a result, we have removed the port name and hostname - the new format will
For most users, this is an implementation detail, and will only impact debugging or tooling that directly interacts with Envoy configuration.
Avoid use of mesh expansion installation flags
To ease setup for multicluster and virtual machines while giving more control to users, the
meshExpansionPorts installation flags have been deprecated, and port 15012 has been added to the default list of ports for the
For users with
values.global.meshExpansion.enabled=true, perform the following steps before upgrading Istio:
- Apply the code sample for exposing Istiod through ingress.
$ kubectl apply -f @samples/multicluster/expose-istiod.yaml@
operator.istio.io/managed labels from the associated Istio networking resources so that the Istio installer won’t delete them. After this step, you can modify these resources freely.
components.ingressGateways[name=istio-ingressgateway].k8s.service.portsis overridden, add port 15012 to the list of ports:
- port: 15012 targetPort: 15012 name: tcp-istiod
values.gateways.istio-ingressgateway.meshExpansionPortsis set, move all ports to
components.ingressGateways[name=istio-ingressgateway].k8s.service.portsif they’re not already present. Then, unset this value.
Protocol Detection Timeout Changes
In order to support permissive mTLS traffic as well as automatic protocol detection,
the proxy will sniff the first few bytes of traffic to determine the protocol used. For certain “server first” protocols, such
as the protocol used by
MySQL, there will be no initial bytes to sniff. To mitigate this issue in the past, Istio introduced
a detection timeout. However, we found this caused frequent telemetry and traffic failures during slow connections, while increasing latency
for misconfigured server first protocols rather than failing fast.
This timeout has been disabled by default. This has the following impacts:
- Non “server first” protocols will no longer have a risk of telemetry or traffic failures during slow connections
- Properly configured “server first” protocols will no longer have an extra 5 seconds latency on each connection
- Improperly configured “server first” protocols will experience connection timeouts. Please ensure you follow the steps listed in Server First Protocols to ensure you do not run into traffic issues.
Update AuthorizationPolicy resources to use
notRemoteIpBlocks instead of
notIpBlocks if using the Proxy Protocol
If using the Proxy Protocol on a load balancer in front an ingress gateway in conjunction with
notIpBlocks on an AuthorizationPolicy to perform IP-based access control, then please update the AuthorizationPolicy to use
notRemoteIpBlocks instead after upgrading. The
notIpBlocks fields now strictly refer to the source IP address of the packet that arrives at the sidecar.
AUTO_PASSTHROUGH Gateway mode
Previously, gateways were configured with multiple Envoy
cluster configurations for each Service in the cluster, even those
not referenced by any
VirtualService. This was added to support the
AUTO_PASSTHROUGH mode on Gateway, generally used for exposing Services across networks.
However, this came at an increased CPU and memory cost in the gateway and Istiod. As a result, we have disabled these by default
If you are relying on this feature for multi-network support, please ensure you apply one of the following changes:
- Follow our new Multicluster Installation documentation.
This documentation will guide you through running a dedicate gateway deployment for this type of traffic (generally referred to as the
eastwest-gateway will automatically be configured to support
- Modify your installation of the gateway deployment to include this configuration. This is controlled by the
ISTIO_META_ROUTER_MODEenvironment variable. Setting this to
sni-dnatenables these clusters, while
standard(the new default) disables them.
ingressGateways: - name: istio-ingressgateway enabled: true k8s: env: - name: ISTIO_META_ROUTER_MODE value: "sni-dnat"
Connectivity issues among your proxies when updating from 1.7.x (where x < 5)
When upgrading your Istio data plane from 1.7.x (where x < 5) to 1.8, you may observe connectivity issues between your gateway and your sidecars or among your sidecars with 503 errors in the log. This happens when 1.7.5+ proxies send HTTP 1xx or 204 response codes with headers that 1.7.x proxies reject. To fix this, upgrade all your proxies (gateways and sidecars) to 1.7.5+ as soon as possible. (Issue 29427, More information)