diff --git a/_docs/setup/kubernetes/upgrading-istio.md b/_docs/setup/kubernetes/upgrading-istio.md new file mode 100644 index 0000000000..b069a6782d --- /dev/null +++ b/_docs/setup/kubernetes/upgrading-istio.md @@ -0,0 +1,76 @@ +--- +title: Upgrading Istio +overview: This guide demonstrates how to upgrade the Istio control plane and data plane independently. + +order: 70 + +layout: docs +type: markdown +--- +{% include home.html %} + +This guide demonstrates how to upgrade the Istio control plane and data plane +for the Kubernetes environment. + +## Overview + +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. + +## Tasks + +### 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. + +```bash +kubectl apply -f istio.yaml (or istio-auth.yaml) +``` + +Note: If you have used [Helm](https://istio.io/docs/setup/kubernetes/helm.html) +to generate a customized Istio deployment, please use the customized yaml files +generated by Helm instead of the standard installtion 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: + + ```bash + 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: + + ```bash + 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](https://gist.github.com/jmound/ff6fa539385d1a057c82fa9fa739492e) + which triggers the rolling update by patching the grace termination period.