Compatibility Versions

2 minute read

With each new version of Istio, there may be some intentional behavioral changes. These can be to improve security, fix incorrect behavior, or otherwise improve Istio for users. Generally, these types of changes impact only edge cases.

While beneficial on the long term, each behavioral change introduces risk during upgrades. Historically, when upgrading users should read the release notes for any behavioral changes and determine if they are impacted; this can be tedious and error prone.

Compatibility versions give users an additional option, allowing release versions to be decoupled from behavioral changes. For instance, you can install Istio 1.25, but configure it to behave like 1.24.

Using compatibility versions

To use a compatibility version, simply set the compatibilityVersion field.

$ istioctl install --set values.compatibilityVersion=1.24

$ helm install ... --set compatibilityVersion=1.24

When should I use compatibility versions?

Compatibility versions should be used only when an incompatibility between releases exists, as a temporary measure. You should plan to migrate to the new behavior as soon as practical.

Compatibility versions for a release will be removed, and will no longer be supported, when the release they refer to reaches end-of-life. Refer to the current Istio release support status chart for the status of specific releases.

To help detect if a compatibility version should be used, istioctl x precheck can be used with the --from-version flag. For instance, if you are upgrading from version 1.24:

$ istioctl x precheck --from-version 1.24
Warning [IST0168] (DestinationRule default/tls) The configuration "ENABLE_AUTO_SNI" changed in release 1.20: previously, no SNI would be set; now it will be automatically set. Or, install with `--set compatibilityVersion=1.20` to retain the old default.
Error: Issues found when checking the cluster. Istio may not be safe to install or upgrade.
See https://istio.io/v1.21/docs/reference/config/analysis for more information about causes and resolutions.