Upgrade using Helm

Follow this guide to upgrade the Istio control plane and sidecar proxies of anexisting Istio deployment that was previously installed using Helm. The upgradeprocess may install new binaries and may change configuration and API schemas.The upgrade process may result in service downtime. To minimize downtime,please ensure your Istio control plane components and your applications arehighly available with multiple replicas.

Be sure to check out the upgrade notesfor a concise list of things you should know before upgrading your deployment to Istio 1.4.

Istio does NOT support skip level upgrades. Only upgrades from 1.3 to 1.4are supported. If you are on an older version, please upgrade to 1.3 first.

Upgrade steps

Download the new Istio releaseand change directory to the new release directory.

Istio CNI upgrade

If you have installed or are planning to install Istio CNI,choose one of the following mutually exclusive options to check whetherIstio CNI is already installed and to upgrade it:

You can use Kubernetes’ rolling update mechanism to upgrade the Istio CNI components.This is suitable for cases where kubectl apply was used to deploy Istio CNI.

  • To check whether istio-cni is installed, search for istio-cni-node podsand in which namespace they are running (typically, kube-system or istio-system):
  1. $ kubectl get pods -l k8s-app=istio-cni-node --all-namespaces
  2. $ NAMESPACE=$(kubectl get pods -l k8s-app=istio-cni-node --all-namespaces --output='jsonpath={.items[0].metadata.namespace}')
  • If istio-cni is currently installed in a namespace other than kube-system(for example, istio-system), delete istio-cni:
  1. $ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=$NAMESPACE | kubectl delete -f -
  • Install or upgrade istio-cni in the kube-system namespace:
  1. $ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=kube-system | kubectl apply -f -

If you installed Istio CNI using Helm and Tiller,the preferred upgrade option is to let Helm take care of the upgrade.

  • Check whether istio-cni is installed, and in which namespace:
  1. $ helm status istio-cni
  • (Re-)install or upgrade istio-cni depending on the status:

    • If istio-cni is not currently installed and you decide to install it:
  1. $ helm install install/kubernetes/helm/istio-cni --name istio-cni --namespace kube-system
  • If istio-cni is currently installed in a namespace other than kube-system(for example, istio-system), delete it:
  1. $ helm delete --purge istio-cni

Then install it again in the kube-system namespace:

  1. $ helm install install/kubernetes/helm/istio-cni --name istio-cni --namespace kube-system
  • If istio-cni is currently installed in the kube-system namespace, upgrade it:
  1. $ helm upgrade istio-cni install/kubernetes/helm/istio-cni --namespace kube-system

Control plane upgrade

Pilot, Galley, Policy, Telemetry and Sidecar injector.Choose one of the following mutually exclusive optionsto update the control plane:

You can use Kubernetes’ rolling update mechanism to upgrade the control plane components.This is suitable for cases where kubectl apply was used to deploy the Istio components,including configurations generated usinghelm template.

  • Use kubectl apply to upgrade all of Istio’s CRDs. Wait a few seconds for the KubernetesAPI server to commit the upgraded CRDs:
  1. $ kubectl apply -f install/kubernetes/helm/istio-init/files/
  • Wait for all Istio CRDs to be created:
  1. $ kubectl -n istio-system wait --for=condition=complete job --all
  • Apply the update templates:
  1. $ helm template install/kubernetes/helm/istio --name istio \
  2. --namespace istio-system | kubectl apply -f -

You must pass the same settings as when you first installed Istio.

The rolling update process will upgrade all deployments and configmaps to the new version.After this process finishes, your Istio control plane should be updated to the new version.Your existing application should continue to work without any change. If there is anycritical issue with the new control plane, you can rollback the changes by applying theyaml files from the old version.

If you installed Istio using Helm and Tiller,the preferred upgrade option is to let Helm take care of the upgrade.

  1. $ helm upgrade --install istio-init install/kubernetes/helm/istio-init --namespace istio-system
  • Wait for all Istio CRDs to be created:
  1. $ kubectl -n istio-system wait --for=condition=complete job --all
  • Upgrade the istio chart:
  1. $ helm upgrade istio install/kubernetes/helm/istio --namespace istio-system

If Istio CNI is installed, enable it by adding the —set istio_cni.enabled=true setting.

Sidecar upgrade

After the control plane upgrade, the applications already running Istio willstill be using an older sidecar. To upgrade the sidecar, you will need to re-inject it.

If you’re using automatic sidecar injection, you can upgrade the sidecarby doing a rolling update for all the pods, so that the new version of thesidecar will be automatically re-injected.

Your kubectl version must be >= 1.15 to run the following command. Upgrade if necessary.

  1. $ kubectl rollout restart deployment --namespace default

If you’re using manual injection, you can upgrade the sidecar by executing:

  1. $ kubectl apply -f <(istioctl kube-inject -f $ORIGINAL_DEPLOYMENT_YAML)

If the sidecar was previously injected with some customized inject configurationfiles, you will need to change the version tag in the configuration files to the newversion and re-inject the sidecar as follows:

  1. $ kubectl apply -f <(istioctl kube-inject \
  2. --injectConfigFile inject-config.yaml \
  3. --filename $ORIGINAL_DEPLOYMENT_YAML)

See also

Upgrade Istio using istioctl [Experimental]

Upgrade or downgrade Istio using the istioctl upgrade command.

DNS Certificate Management

Provision and manage DNS certificates in Istio.

Secure Webhook Management

A more secure way to manage Istio webhooks.

Demystifying Istio's Sidecar Injection Model

De-mystify how Istio manages to plugin its data-plane components into an existing deployment.

Customizable Install with Helm

Install and configure Istio for in-depth evaluation or production use.

Customizable Install with Istioctl

Install and customize any Istio configuration profile for in-depth evaluation or production use.