Upgrade with Helm

Follow this guide to upgrade and configure an Istio mesh using Helm for in-depth evaluation. 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 underlying charts used when installing Istio via Istioctl or the Operator.

This feature is currently considered alpha.

Prior to Istio 1.9.0, installations using the Helm charts required hub and tag arguments: --set global.hub="docker.io/istio" and --set global.tag="1.8.2". As of Istio 1.9.0 these are no longer required.

Prerequisites

  1. Download the Istio release.

  2. Perform any necessary platform-specific setup.

  3. Check the Requirements for Pods and Services.

  4. Install a Helm client with a version higher than 3.1.1.

Helm 2 is not supported for installing Istio.

The commands in this guide use the Helm charts that are included in the Istio release package located at manifests/charts.

Upgrade steps

Change directory to the root of the release package and then follow the instructions below.

The default chart configuration uses the secure third party tokens for the service account token projections used by Istio proxies to authenticate with the Istio control plane. Before proceeding to install any of the charts below, you should verify if third party tokens are enabled in your cluster by following the steps describe here. If third party tokens are not enabled, you should add the option --set global.jwtPolicy=first-party-jwt to the Helm install commands. If the jwtPolicy is not set correctly, pods associated with istiod, gateways or workloads with injected Envoy proxies will not get deployed due to the missing istio-token volume.

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

  1. $ istioctl x precheck
  2. ✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
  3. 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.

Create a backup

Before upgrading Istio in your cluster, we recommend creating a backup of your custom configurations, and restoring it from backup if necessary:

  1. $ kubectl get istio-io --all-namespaces -oyaml > "$HOME"/istio_resource_backup.yaml

You can restore your custom configuration like this:

  1. $ kubectl apply -f "$HOME"/istio_resource_backup.yaml

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:

Note that when you install a canary version of the istiod service, the underlying cluster-wide resources from the base chart are shared across your primary and canary installations.

Currently, the support for canary upgrades for Istio ingress and egress gateways is actively in development and is considered experimental.

  1. Upgrade the Kubernetes custom resource definitions (CRDs):

    1. $ kubectl apply -f manifests/charts/base/crds

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

    1. $ helm install istiod-canary manifests/charts/istio-control/istio-discovery \
    2.     --set revision=canary \
    3.     -n istio-system

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

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

  4. Follow the steps here to test or migrate existing workloads to use the canary control plane.

  5. Once you have verified and migrated your workloads to use the canary control plane, you can uninstall your old control plane:

    1. $ helm delete istiod -n istio-system

  6. Upgrade the Istio base chart:

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

In place upgrade

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

This upgrade path is only supported from Istio version 1.8 and above.

Add your override values file or custom options to the commands below to preserve your custom configuration during Helm upgrades.

  1. Upgrade the Kubernetes custom resource definitions (CRDs):

    1. $ kubectl apply -f manifests/charts/base/crds

  2. Upgrade the Istio base chart:

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

  3. Upgrade the Istio discovery chart:

    1. $ helm upgrade istiod manifests/charts/istio-control/istio-discovery \
    2.     -n istio-system

  4. (Optional) Upgrade the Istio ingress or egress gateway charts if installed in your cluster:

    1. $ helm upgrade istio-ingress manifests/charts/gateways/istio-ingress \
    2.     -n istio-system
    3. $ helm upgrade istio-egress manifests/charts/gateways/istio-egress \
    4.     -n istio-system

Uninstall

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