Upgrade with Helm

6 minute read page test

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

The Helm charts used in this guide are the same as those used when installing Istio via Istioctl, with the exception of the gateway chart.

Istioctl uses a different gateway chart than the gateway chart described in this guide

Prerequisites

Perform any necessary platform-specific setup.
Check the Requirements for Pods and Services.
Install the latest Helm client. Helm versions released before the oldest currently-supported Istio release are not tested, supported, or recommended.
Configure the Helm repository:

$ helm repo add istio https://istio-release.storage.googleapis.com/charts
$ helm repo update

Upgrade steps

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

Canary upgrade (recommended)

You can install a canary version of Istio control plane to validate that the new version is compatible with your existing configuration and data plane using the steps below:

If upgrading CRDs via Helm from an Istio release 1.23 or older, you may encounter an error such as the following

Error: rendered manifests contain a resource that already exists. Unable to continue with update: CustomResourceDefinition "wasmplugins.extensions.istio.io" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata

You can resolve this with a one-time migration using the following kubectl commands:

$ for crd in $(kubectl get crds -l chart=istio -o name && kubectl get crds -l app.kubernetes.io/part-of=istio -o name)
$ do
$    kubectl label "$crd" "app.kubernetes.io/managed-by=Helm"
$    kubectl annotate "$crd" "meta.helm.sh/release-name=istio-base" # replace with actual Helm release name, if different from the documentation default
$    kubectl annotate "$crd" "meta.helm.sh/release-namespace=istio-system" # replace with actual istio namespace
$ done

Upgrade the Istio base chart to ensure all cluster-wide resources are up-to-date
```
$ helm upgrade istio-base istio/base -n istio-system
```

Install a canary version of the Istio discovery chart by setting the revision value:

$ helm install istiod-canary istio/istiod \
    --set revision=canary \
    -n istio-system

Verify that you have two versions of istiod installed in your cluster:

$ kubectl get pods -l app=istiod -L istio.io/rev -n istio-system
  NAME                            READY   STATUS    RESTARTS   AGE   REV
  istiod-5649c48ddc-dlkh8         1/1     Running   0          71m   default
  istiod-canary-9cc9fd96f-jpc7n   1/1     Running   0          34m   canary

If you are using Istio gateways, install a canary revision of the Gateway chart by setting the revision value:
```
$ helm install istio-ingress-canary istio/gateway \
    --set revision=canary \
    -n istio-ingress
```

Verify that you have two versions of istio-ingress gateway installed in your cluster:

$ kubectl get pods -L istio.io/rev -n istio-ingress
  NAME                                    READY   STATUS    RESTARTS   AGE     REV
  istio-ingress-754f55f7f6-6zg8n          1/1     Running   0          5m22s   default
  istio-ingress-canary-5d649bd644-4m8lp   1/1     Running   0          3m24s   canary

See Upgrading Gateways for in-depth documentation on gateway canary upgrade.

Follow the steps here to test or migrate existing workloads to use the canary control plane.
Once you have verified and migrated your workloads to use the canary control plane, you can uninstall your old control plane:
```
$ helm delete istiod -n istio-system
```
Upgrade the Istio base chart again, this time making the new canary revision the cluster-wide default.
```
$ helm upgrade istio-base istio/base --set defaultRevision=canary -n istio-system
```

Stable revision labels

Manually relabeling namespaces when moving them to a new revision can be tedious and error-prone. Revision tags solve this problem. Revision tags are stable identifiers that point to revisions and can be used to avoid relabeling namespaces. Rather than relabeling the namespace, a mesh operator can simply change the tag to point to a new revision. All namespaces labeled with that tag will be updated at the same time.

Usage

Consider a cluster with two revisions installed, 1-24-1 and 1-25-0. The cluster operator creates a revision tag prod-stable, pointed at the older, stable 1-24-1 version, and a revision tag prod-canary pointed at the newer 1-25-0 revision. That state could be reached via the following commands:

$ helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags="{prod-stable}" --set revision=1-24-1 -n istio-system | kubectl apply -f -
$ helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags="{prod-canary}" --set revision=1-25-0 -n istio-system | kubectl apply -f -

The resulting mapping between revisions, tags, and namespaces is as shown below:

Two namespaces pointed to prod-stable and one pointed to prod-canary

The cluster operator can view this mapping in addition to tagged namespaces through the istioctl tag list command:

$ istioctl tag list
TAG         REVISION NAMESPACES
default     1-24-1   ...
prod-canary 1-25-0   ...
prod-stable 1-24-1   ...

After the cluster operator is satisfied with the stability of the control plane tagged with prod-canary, namespaces labeled istio.io/rev=prod-stable can be updated with one action by modifying the prod-stable revision tag to point to the newer 1-25-0 revision.

$ helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags="{prod-stable}" --set revision=1-25-0 -n istio-system | kubectl apply -f -

Now, the updated mapping between revisions, tags, and namespaces is as shown below:

Namespace labels unchanged but now all namespaces pointed to {{< istio_full_version_revision >}}

Restarting injected workloads in the namespaces marked prod-stable will now result in those workloads using the 1-25-0 control plane. Notice that no namespace relabeling was required to migrate workloads to the new revision.

Default tag

The revision pointed to by the tag default is considered the default revision and has additional semantic meaning. The default revision performs the following functions:

Injects sidecars for the istio-injection=enabled namespace selector, the sidecar.istio.io/inject=true object selector, and the istio.io/rev=default selectors
Validates Istio resources
Steals the leader lock from non-default revisions and performs singleton mesh responsibilities (such as updating resource statuses)

To make a revision 1-25-0 the default, run:

$ helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags="{default}" --set revision=1-25-0 -n istio-system | kubectl apply -f -

When using the default tag alongside an existing non-revisioned Istio installation it is recommended to remove the old MutatingWebhookConfiguration (typically called istio-sidecar-injector) to avoid having both the older and newer control planes attempt injection.

In place upgrade

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

If upgrading CRDs via Helm from an Istio release 1.23 or older, you may encounter an error such as the following

You can resolve this with a one-time migration using the following kubectl commands:

$ for crd in $(kubectl get crds -l chart=istio -o name && kubectl get crds -l app.kubernetes.io/part-of=istio -o name)
$ do
$    kubectl label "$crd" "app.kubernetes.io/managed-by=Helm"
$    kubectl annotate "$crd" "meta.helm.sh/release-name=istio-base" # replace with actual Helm release name, if different from the documentation default
$    kubectl annotate "$crd" "meta.helm.sh/release-namespace=istio-system" # replace with actual istio namespace
$ done

Upgrade the Istio base chart:

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

Upgrade the Istio discovery chart:

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

(Optional) Upgrade any gateway charts installed in your cluster:
```
$ helm upgrade istio-ingress istio/gateway -n istio-ingress
```

Uninstall

Please refer to the uninstall section in our Helm install guide.