Istio 1.8 Upgrade Notes
Important changes to consider when upgrading to Istio 1.8.
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.
Multicluster .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 .global
stub
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-policy
or 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
In 1.7, 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 ServiceEntries
using
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 EnvoyFilter
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
instead resemble inbound|80||
.
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 meshExpansion
and meshExpansionPorts
installation flags have been deprecated, and port 15012 has been added to the default list of ports for the istio-ingressgateway
Service.
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@
This removes 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.
- If
components.ingressGateways[name=istio-ingressgateway].k8s.service.ports
is overridden, add port 15012 to the list of ports:
- port: 15012
targetPort: 15012
name: tcp-istiod
If
values.gateways.istio-ingressgateway.meshExpansionPorts
is set, move all ports tocomponents.ingressGateways[name=istio-ingressgateway].k8s.service.ports
if they’re not already present. Then, unset this value.Unset
values.global.meshExpansion.enabled
.
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 remoteIpBlocks
/notRemoteIpBlocks
instead of ipBlocks
/notIpBlocks
if using the Proxy Protocol
If using the Proxy Protocol on a load balancer in front an ingress gateway in conjunction with ipBlocks
/notIpBlocks
on an AuthorizationPolicy to perform IP-based access control, then please update the AuthorizationPolicy to use remoteIpBlocks
/notRemoteIpBlocks
instead after upgrading. The ipBlocks
/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 Gateway
or 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
on the istio-ingressgateway
and istio-egressgateway
.
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
).
This eastwest-gateway
will automatically be configured to support AUTO_PASSTHROUGH
.
- Modify your installation of the gateway deployment to include this configuration. This is controlled by the
ISTIO_META_ROUTER_MODE
environment variable. Setting this tosni-dnat
enables these clusters, whilestandard
(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)