Istio 1.21 Upgrade Notes
Important changes to consider when upgrading to Istio 1.21.x.
When you upgrade from Istio 1.20.x to Istio 1.21.0, you need to consider the changes on this page. These notes detail the changes which purposefully break backwards compatibility with Istio 1.20.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.20.x.
Default value of the feature flag ENABLE_AUTO_SNI
to true
auto-sni
is enabled by default. This means SNI will be set automatically based on the downstream HTTP host/authority header if DestinationRule
does not explicitly set the same.
If this is not desired, use the new compatibilityVersion
feature to fallback to old behavior.
Default value of the feature flag VERIFY_CERT_AT_CLIENT
is set to true
This means server certificates will be automatically verified using the OS CA certificates when not using a DestinationRule caCertificates
field.
If this is not desired, use the new compatibilityVersion
feature to fallback to old behavior, or use the insecureSkipVerify
field in DestinationRule to skip the verification.
ExternalName
support changes
Kubernetes ExternalName
Service
s allow users to create new DNS entries. For example, you can create an example
service
that points to example.com
. This is implemented by a DNS CNAME
redirect.
In Istio, the implementation of ExternalName
, historically, was substantially different. Each ExternalName
represented its own
service, and traffic matching the service was sent to the configured DNS name.
This caused a few issues:
- Ports are required in Istio, but not in Kubernetes. This can result in broken traffic if ports are not configured as Istio expects, despite them working without Istio.
- Ports not declared as
HTTP
would match all traffic on that port, making it easy to accidentally send all traffic on a port to the wrong place. - Because the destination DNS name is treated as opaque, we cannot apply Istio policies to it as expected. For example, if I point
an external name at another in-cluster Service (for example,
example.default.svc.cluster.local
), mTLS would not be used.
ExternalName
support has been revamped to fix these problems. ExternalName
s are now simply treated as aliases.
Wherever we would match Host: <concrete service>
we additionally will match Host: <external name service>
.
Note that the primary implementation of ExternalName
– DNS – is handled outside of Istio in the Kubernetes DNS implementation, and remains unchanged.
If you are using ExternalName
with Istio, please be advised of the following behavioral changes:
- The
ports
field is no longer needed, matching Kubernetes behavior. If it is set, it will have no impact. VirtualServices
that route to anExternalName
service will no longer work unless the referenced service exists (as a Service or ServiceEntry).DestinationRule
can no longer apply toExternalName
services. Instead, create rules where thehost
references service.
To opt-out, the ENABLE_EXTERNAL_NAME_ALIAS=false
environment variable can be set.
Note: the same change was introduced in the previous release, but off by default. This release turns the flag on by default.
Gateway Name label modified
If you are using the Kubernetes Gateway
to manage your Istio gateways, the label key used to identify the
gateway name is changing from istio.io/gateway-name
to
gateway.networking.k8s.io/gateway-name
.
The old label will continue to be appended to the relevant label sets
for backwards compatibility, but it will be removed in a future
release.
Furthermore, istiod’s gateway controller will automatically detect
and continue to use the old label for label selectors belonging
to existing Deployment
and Service
resources.
Therefore, once you’ve completed your Istio upgrade, you can change the label selector in Deployment
and Service
resources whenever you are ready to use the new label.
Additionally, please upgrade any other policies, resources, or scripts that rely on the old label.