Istio 1.21 Upgrade Notes

Important changes to consider when upgrading to Istio 1.21.x.

Mar 13, 2024

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 Services allow users to create new DNS entries. For example, you can create an example service that points to 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:

ExternalName support has been revamped to fix these problems. ExternalNames 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:

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 to 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.