Upgrading Istio

This guide demonstrates how to upgrade the Istio control plane and data plane for the Kubernetes environment.


This guide describes how to upgrade an existing Istio deployment (including both control plane and sidecar proxy) to a new release of Istio. The upgrade process could involve new binaries as well as other changes like configuration and API schemas. The upgrade process may involve some service downtime.

Application setup

In the following steps, we assume that the Istio components are installed and upgraded in the same namespace ISTIO_NAMESPACE.


Control plane upgrade

The Istio control plane components include: CA, Ingress, Pilot, Mixer, and Sidecar injector. We can use Kubernetes’ rolling update mechanism to upgrade the control plance components. It can be done by simply applying the new version yaml file directly, e.g.

kubectl apply -f istio.yaml (or istio-auth.yaml)

Note: If you have used Helm to generate a customized Istio deployment, please use the customized yaml files generated by Helm instead of the standard installation yamls.

The rolling update process will upgrade all deployments and configmaps to the new version. If there is any issue with the new control plane, you can rollback the changes either by applying the old version yaml files.

Sidecar upgrade

After the control plane is upgraded, you will need to re-inject the new version of sidecar proxy. There are two cases: Manual injection and Automatic injection.

  1. Manual injection:

    If automatic sidecar injection is not enabled, you can upgrade the sidecar manually by running the following command:

      kubectl apply -f <(istioctl kube-inject -i $ISTIO_NAMESPACE -f $ORIGINAL_DEPLOYMENT_YAML)

    If the sidecar was previously injected with some customized inject config files, you will need to change the version tag in the config files to the new version and reinject the sidecar as follows:

      kubectl apply -f <(istioctl kube-inject \
           --injectConfigFile inject-config.yaml \
           --filename $ORIGINAL_DEPLOYMENT_YAML)
  2. Automatic injection:

    If automatic sidecar injection is enabled, you can upgrade the sidecar by doing a rolling update for all the pods, so that the new version of sidecar will be automatically re-injected

    There are some tricks to reload all pods. E.g. There is a bash script which triggers the rolling update by patching the grace termination period.