istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add data plane update step (#1403) 

* add data plane update step

* small typo

* fix spelling

* delete not needed space

* another typo

* more lint fix

* Do an editing pass.
This commit is contained in:
Lin Sun 2018-06-02 21:55:25 -04:00 committed by GitHub
parent 4be9f2986a
commit f712e61515
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 95 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
content/docs/setup/kubernetes/upgrading-istio.md
View File

@ -4,29 +4,23 @@ description: This guide demonstrates how to upgrade the Istio control plane and
weight: 70
---
This guide demonstrates how to upgrade the Istio control plane and data plane
for the Kubernetes environment.
This page 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. To minimize downtime, please ensure your Istio control plane components and your applications are highly available
with multiple replicas.
## Overview
In the following steps, we assume that the Istio components are installed and upgraded in the `istio-system` namespace.
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. To minimize the service downtime, please ensure your istio control plane components and your application are highly available with multiple replicas.
## Application setup
In the following steps, we assume that the Istio components are installed and upgraded in the the `istio-system` namespace.
## Tasks
### Control plane upgrade
## Control plane upgrade
The Istio control plane components include: Citadel, Ingress gateway, Egress gateway, Pilot, Policy, Telemetry and
Sidecar injector. We can use Kubernetes’ rolling update mechanism to upgrade the
control plane components.
First, generate the desired istio control plane yaml file, e.g.
First, generate the desired Istio control plane yaml file, e.g.
```command
helm template --namespace istio-system --set global.proxy.image=proxy \
$ helm template --namespace istio-system --set global.proxy.image=proxy \
--values install/kubernetes/helm/istio/values-istio.yaml \
install/kubernetes/helm/istio >> install/kubernetes/istio.yaml
```
@ -34,14 +28,14 @@ helm template --namespace istio-system --set global.proxy.image=proxy \
or
```command
helm template --namespace istio-system --set global.proxy.image=proxy \
$ helm template --namespace istio-system --set global.proxy.image=proxy \
--values install/kubernetes/helm/istio/values-istio-auth.yaml \
install/kubernetes/helm/istio >> install/kubernetes/istio-auth.yaml
```
If using Kubernetes earlier than 1.9, you should add ```--set sidecarInjectorWebhook.enabled=false```.
If using Kubernetes versions prior to 1.9, you should add `--set sidecarInjectorWebhook.enabled=false`.
Second, simply apply the new version of the desired istio control plane yaml file directly, e.g.
Second, simply apply the new version of the desired Istio control plane yaml file directly, e.g.
```command
$ kubectl apply -f install/kubernetes/istio.yaml
@ -53,56 +47,96 @@ or
$ kubectl apply -f install/kubernetes/istio-auth.yaml
```
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, using the Envoy v1 proxy and the v1alpha1 route rules. If there is any critical issue with the new control plane, you can rollback the changes by applying the yaml files from the old version.
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, using the Envoy v1 proxy and the v1alpha1 route rules. If there is any critical issue with the new control plane,
you can rollback the changes by applying the yaml files from the old version.
### Sidecar upgrade
## Sidecar upgrade
The applications already running istio will still using the sidecar from 0.7.1 and will continue to work. After the control plane is upgraded, you will need to re-inject so they run with the new version of sidecar proxy. There are two cases: Manual injection and Automatic injection.
After the control plane upgrade, the applications already running Istio will still be using an older sidecar. To upgrade the sidecar,
you will need to re-inject it.
1. Manual injection:
If you're using automatic sidecar injection, you can upgrade the sidecar
by doing a rolling update for all the pods, so that the new version of the
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.
If automatic sidecar injection is not enabled, you can upgrade the
sidecar manually by running the following command:
```command
$ kubectl replace -f <(istioctl kube-inject -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:
```command
$ kubectl replace -f <(istioctl kube-inject \
--injectConfigFile inject-config.yaml \
--filename $ORIGINAL_DEPLOYMENT_YAML)
```
1. 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.
### Migrating to the new networking APIs
Once you upgrade the control plane, you can gradually move pods to use the new API version by adding:
```yaml
kind: Deployment
...
spec:
template:
annotations:
sidecar.istio.io/proxyImage: istio/proxyv2:0.8.latest
If you're using manual injection, you can upgrade the
sidecar by executing:
```command
$ kubectl replace -f <(istioctl kube-inject -f $ORIGINAL_DEPLOYMENT_YAML)
```
When all your applications have been migrated and tested, you can repeat the istio upgrade process, removing the `--set global.proxy.image=proxy` option.
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 re-inject the sidecar as follows:
```command
$ kubectl replace -f <(istioctl kube-inject \
--injectConfigFile inject-config.yaml \
--filename $ORIGINAL_DEPLOYMENT_YAML)
```
## Migrating to the new networking APIs
Once you've upgraded the control plane and sidecar, you can gradually update your deployment to use the new Envoy sidecar. You can do this by using
one of the options below:
- Add the following to your pod annotation for your deployment:
```yaml
kind: Deployment
...
spec:
template:
annotations:
sidecar.istio.io/proxyImage: docker.io/istio/proxyv2:0.8.0
```
Then replace your deployment with your updated application yaml file:
```command
$ kubectl replace -f $UPDATED_DEPLOYMENT_YAML
```
or
- Use an `injectConfigFile` that has `docker.io/istio/proxyv2:0.8.0` as the proxy image. If you don't have an `injectConfigFile`, you can
[generate one](/docs/setup/kubernetes/sidecar-injection/#manual-sidecar-injection). `injectConfigFile` is recommended if you need to add
the `sidecar.istio.io/proxyImage` annotations in multiple deployment definitions.
```command
$ kubectl replace -f <(istioctl kube-inject --injectConfigFile inject-config.yaml -f $ORIGINAL_DEPLOYMENT_YAML)
```
Next, use `istioctl experimental convert-networking-config` to convert your existing ingress or route rules:
1. If your yaml file contains more than the ingress definition such as deployment or service definition, move the ingress definition out to a separate yaml file for the `
istioctl experimental convert-networking-config` tool to process.
1. Execute the following to generate the new network config file, where replacing FILE*.yaml with your ingress file or deprecated route rule files.
*Tip: Make sure to feed all the files using `-f` for one or more deployments.*
```command
$ istioctl experimental convert-networking-config -f FILE1.yaml -f FILE2.yaml -f FILE3.yaml > UPDATED_NETWORK_CONFIG.yaml
```
1. Edit `UPDATED_NETWORK_CONFIG.yaml` to update all namespace references to your desired namespace.
There is a known issue with the `convert-networking-config` tool where the `istio-system` namespace
is used incorrectly. Further, ensure the `hosts` value is correct.
1. Deploy the updated network config file.
```command
$ kubectl replace -f UPDATED_NETWORK_CONFIG.yaml
```
When all your applications have been migrated and tested, you can repeat the Istio upgrade process, removing the
`--set global.proxy.image=proxy` option. This will set the default proxy to `docker.io/istio/proxyv2` for all
sidecars injected in the future.
### Migrating per-service mutual TLS enablement via annotations to authentication policy
@ -195,4 +229,4 @@ spec:
trafficPolicy:
tls:
mode: DISABLE
```
```