Upgrade
Upgrading Istio in ambient mode involves upgrading the control plane and data plane separately. Because the data plane does not run as a sidecar, upgrading an ambient mesh does not require restarting user workloads. In most cases, the upgrade will cause only minimal interruption to traffic.
Considerations for upgrade
Availability during upgrades
Istio’s ambient mode supports moving application pods to an upgraded ztunnel proxy without a mandatory restart or reschedule of running application pods. However, upgrading ztunnel will cause any long-lived TCP connections on the upgraded node to reset, after a grace period. Because of this, it is possible to upgrade in-place with minimal downtime.
For more control over the upgrade process, you can use tags and revisions, or drain and cordon nodes before upgrading ztunnel on them.
Supported versions
The CNI node agent and ztunnel components are compatible with a control plane at the same version, or one version higher. This means you can only upgrade from one version to the next, and should upgrade the istiod chart before either.
Upgrading an ambient mesh
Check readiness for upgrade
Before upgrading Istio, download the corresponding new version of istioctl, and run istioctl x precheck to make sure the upgrade is compatible with your environment. The output should looks something like this:
$ istioctl x precheck✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
To get started, check out <https://istio.io/latest/docs/setup/getting-started/>
Update the Helm repository
Get the latest version of the Helm charts:
$ helm repo update istioUpgrade the control plane
The base chart, which contains cluster-wide CRDs and roles, must be upgraded prior to upgrading the control plane.
$ helm upgrade istio-base istio/base -n istio-systemThe istiod chart should be upgraded next. If you have customized your istiod installation, reuse the values.yaml file.
$ helm upgrade istiod istio/istiod -n istio-system --waitFinally, the CNI node agent chart should be upgraded. Upgrading the Istio CNI node agent will not disrupt networking for running pods already in an ambient mesh, but no pods that are set to be added to the mesh will be successfully scheduled (or rescheduled) on the node until the upgrade is complete and the upgraded CNI node agent on the passes readiness checks.
$ helm upgrade istio-cni istio/cni -n istio-systemUpgrade the data plane
Upgrading ztunnel in-place will briefly disrupt all ambient mesh traffic on the node. In practice, the disruption period is a very small window, primarily affecting long-running connections. During the upgrade, new connections will go to the new ztunnel instance. After a grace period, any connections active on the old instance will be terminated with a TCP RST.
Node cordoning and blue/green node pools are recommended to mitigate blast radius risk during production upgrades. See your Kubernetes provider documentation for details.
$ helm upgrade ztunnel istio/ztunnel -n istio-system --waitWaypoints and gateways are workloads in the cluster, managed by istiod, and they will be upgraded automatically.