Upgrade with Helm

Upgrade with Helm

Follow this guide to upgrade and configure an ambient mode installation using Helm. This guide assumes you have already performed an ambient mesh installation with Helm with a previous minor or patch version of Istio.

Ambient mode is currently in the Alpha phase.

Please do not use ambient mode in production, and be sure to thoroughly review the feature phase definitions before use.

In particular, there are known performance, stability, and security issues in the alpha release. There are also planned breaking changes, including some that will prevent upgrades. These limitations will be addressed before ambient mode moves to Beta.

In contrast to sidecar mode, ambient mode supports moving application pods to an upgraded data plane without a mandatory restart or reschedule of running application pods. However, upgrading the data plane will briefly disrupt all workload traffic on the upgraded node, and ambient mode does not currently support canary upgrades of the data plane.

Node cordoning and blue/green node pools are recommended to control blast radius of application pod traffic disruption during production upgrades. See your Kubernetes provider documentation for details.

Prerequisites

Update the Helm repository:
```
$ helm repo update istio
```

In-place upgrade

You can perform an in place upgrade of Istio in your cluster using the Helm upgrade workflow.

Before upgrading Istio, it is recommended to run the istioctl x precheck command to make sure the upgrade is compatible with your environment.

$ 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/>

Helm does not upgrade or delete CRDs when performing an upgrade. Because of this restriction, an additional step is required when upgrading Istio with Helm.

Manually upgrade the CRDs and Istio base chart

Upgrade the Kubernetes custom resource definitions (CRDs):
```
$ kubectl apply -f manifests/charts/base/crds
```

Upgrade the Istio base chart:

$ helm upgrade istio-base manifests/charts/base -n istio-system --skip-crds

Upgrade the Istio discovery Component

Istiod is the control plane component that manages and configures the proxies to route traffic within an ambient mesh.

$ helm upgrade istiod istio/istiod -n istio-system

Upgrade the ztunnel component

The ztunnel DaemonSet is the node proxy component.

As ambient mode is not yet Stable, the following statement is not a compatibility guarantee, and is subject to change, or removal. Prior to reaching Stable status, this component and/or the control plane may receive breaking changes that prevent compatibility between minor versions.

The ztunnel at version 1.x is generally compatible with the control plane at version 1.x+1 and 1.x. This means the control plane must be upgraded before ztunnel, as long as their version difference is within one minor version.

Upgrading ztunnel in-place will briefly disrupt all ambient mesh traffic on the node. 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

Upgrade the CNI component

The Istio CNI agent is responsible for detecting pods added to the ambient mesh, informing ztunnel that proxy ports should be established within added pods, and configuring traffic redirection within the pod network namespace. It is not part of the data plane or control plane.

The CNI at version 1.x is generally compatible with the control plane at version 1.x+1 and 1.x. This means the control plane must be upgraded before Istio CNI, as long as their version difference is within one minor version.

Upgrading the Istio CNI agent to a compatible version in-place will not disrupt networking for running pods already successfully added to an ambient mesh, but no ambient-captured pods will be successfully scheduled (or rescheduled) on the node until the upgrade is complete and the upgraded Istio CNI agent on the node passes readiness checks. If this is a significant disruption concern, or stricter blast radius controls are desired for CNI upgrades, node taints and/or node cordons are recommended.

$ helm upgrade istio-cni istio/cni -n istio-system

Upgrade the Gateway component (optional)

Gateway components manage east-west and north-south dataplane traffic between ambient mesh boundaries, as well as some aspects of the L7 dataplane.

$ helm upgrade istio-ingress istio/gateway -n istio-ingress

Configuration

To view supported configuration options and documentation, run:

$ helm show values istio/istiod

Verify the installation

Verify the workload status

After installing all the components, you can check the Helm deployment status with:

$ helm list -n istio-system

You can check the status of the deployed Istio pods with:

$ kubectl get pods -n istio-system

Uninstall

Please refer to the uninstall section in the Helm installation guide.

Upgrade with Helm *