Upgrade with Helm
Follow this guide to upgrade and configure an Istio mesh using Helm5. This guide assumes you have already performed an installation with Helm6 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 Istioctl7, with the exception of the gateway
chart.
Istioctl uses a different gateway chart8 than the gateway chart9 described in this guide
Prerequisites
Perform any necessary platform-specific setup10.
Check the Requirements for Pods and Services11.
Install the latest Helm client12. Helm versions released before the oldest currently-supported Istio release are not tested, supported, or recommended.
Configure the Helm repository:
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.
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:
Upgrade the Istio base chart to ensure all cluster-wide resources are up-to-date
Install a canary version of the Istio discovery chart by setting the revision value:
Verify that you have two versions of
istiod
installed in your cluster:If you are using Istio gateways, install a canary revision of the Gateway chart by setting the revision value:
Verify that you have two versions of
istio-ingress gateway
installed in your cluster: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:
Upgrade the Istio base chart again, this time making the new
canary
revision the cluster-wide default.
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-26-1
and 1-27-0
. The cluster operator creates a revision tag prod-stable
,
pointed at the older, stable 1-26-1
version, and a revision tag prod-canary
pointed at the newer 1-27-0
revision. That
state could be reached via the following commands:The resulting mapping between revisions, tags, and namespaces is as shown below:
The cluster operator can view this mapping in addition to tagged namespaces through the istioctl tag list
command:
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-27-0
revision.
Now, the updated mapping between revisions, tags, and namespaces is as shown below:
Restarting injected workloads in the namespaces marked prod-stable
will now result in those workloads using the 1-27-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, thesidecar.istio.io/inject=true
object selector, and theistio.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-27-0
the default, run:
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.
Upgrade the Istio base chart:
Upgrade the Istio discovery chart:
(Optional) Upgrade any gateway charts installed in your cluster:
Uninstall
Please refer to the uninstall section in our Helm install guide.