Upgrade

Upgrade Istio in ambient mode by updating the control plane and data plane separately, with minimal traffic interruption.

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

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.
```
helm repo update istio
```
Set hub and tag parameters. If you’re using the Solo builds of Istio, set the global.hub and global.tag parameters in each of the following steps. See that page for the correct values.
Upgrade the control plane.
1. 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-system
2. The 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 --wait
3. Finally, 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-system
Upgrade 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.
- Waypoints and gateways are workloads in the cluster, managed by istiod, and they will be upgraded automatically.
```
helm upgrade ztunnel istio/ztunnel -n istio-system --wait
```

Uninstall