Add documentation for upgrade

_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.