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

Enhance docs for revision tags and add tests (#12496) 

* Enhance docs for revision tags and add tests

Signed-off-by: Faseela K <faseela.k@est.tech>

* Fix test failures

Signed-off-by: Faseela K <faseela.k@est.tech>

* Fix lint failure

Signed-off-by: Faseela K <faseela.k@est.tech>

* Fix test failures

Signed-off-by: Faseela K <faseela.k@est.tech>

* Fix cleanup test failures

Signed-off-by: Faseela K <faseela.k@est.tech>

* Fix cleanup for canary upgrade tests

Signed-off-by: Faseela K <faseela.k@est.tech>

* add profile none

Signed-off-by: Faseela K <faseela.k@est.tech>

* review comments

Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>

* make gen

Signed-off-by: Faseela K <faseela.k@est.tech>

Signed-off-by: Faseela K <faseela.k@est.tech>
Co-authored-by: Eric Van Norman <ericvn@us.ibm.com>
This commit is contained in:
Faseela K 2023-01-25 20:09:21 +01:00 committed by GitHub
parent 5bf14ed2b4
commit 87f6b9f5ec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 376 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
content/en/boilerplates/revision-tags-middle.md
View File

@ -12,6 +12,7 @@ The cluster operator can view this mapping in addition to tagged namespaces thro
{{< text bash >}}
$ istioctl tag list
TAG REVISION NAMESPACES
default 1-9-5 ...
prod-canary 1-10-0 ...
prod-stable 1-9-5 ...
{{< /text >}}

2
content/en/boilerplates/revision-tags-prologue.md
View File

@ -1,6 +1,6 @@
---
---
Now, the situation is as below:
Now, the updated mapping between revisions, tags, and namespaces is as shown below:
{{< image width="70%"
link="/docs/setup/upgrade/canary/tags-updated.png"

2
content/en/boilerplates/revision-tags-usage.md
View File

@ -2,4 +2,4 @@
---
Consider a cluster with two revisions installed, `1-9-5` and `1-10-0`. The cluster operator creates a revision tag `prod-stable`,
pointed at the older, stable `1-9-5` version, and a revision tag `prod-canary` pointed at the newer `1-10-0` revision. That
state could be reached via these commands:
state could be reached via the following commands:

1
content/en/boilerplates/snips/revision-tags-middle.sh
View File

@ -26,6 +26,7 @@ istioctl tag list
! read -r -d '' bpsnip_revision_tags_middle__1_out <<\ENDSNIP
TAG REVISION NAMESPACES
default 1-9-5 ...
prod-canary 1-10-0 ...
prod-stable 1-9-5 ...
ENDSNIP

53
content/en/docs/setup/upgrade/canary/canary_upgrade_test.sh Normal file
View File

@ -0,0 +1,53 @@
#!/usr/bin/env bash
# Copyright Istio Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
source "content/en/docs/setup/upgrade/canary/snips.sh"
source "tests/util/samples.sh"
set -e
set -u
set -o pipefail
# @setup profile=none
# setup initial control plane
istioctl install --set profile=default --revision=1-9-5 -y
# Deploy a test namespace with an application pod
kubectl create ns test-ns
kubectl label namespace test-ns istio-injection=enabled
kubectl -n test-ns apply -f samples/sleep/sleep.yaml
_wait_for_deployment test-ns sleep
# precheck before upgrade
_verify_lines snip_before_you_upgrade_1 "$snip_before_you_upgrade_1_out"
# install canary revision
echo y | snip_control_plane_1
_wait_for_deployment istio-system istiod-canary
_verify_like snip_control_plane_2 "$snip_control_plane_2_out"
_verify_like snip_control_plane_3 "$snip_control_plane_3_out"
_verify_contains snip_data_plane_1 "istiod-canary"
# Migrate the dataplane to new revision
snip_data_plane_2
snip_data_plane_3
_verify_contains snip_data_plane_4 "test-ns"
# Uninstall canary control plane
snip_uninstall_old_control_plane_1
_verify_like snip_uninstall_old_control_plane_3 "$snip_uninstall_old_control_plane_3_out"
# @cleanup
snip_uninstall_canary_control_plane_1
snip_cleanup_1

109
content/en/docs/setup/upgrade/canary/index.md
View File

@ -4,7 +4,7 @@ description: Upgrade Istio by first running a canary deployment of a new control
weight: 10
keywords: [kubernetes,upgrading,canary]
owner: istio/wg-environments-maintainers
test: no
test: yes
---
Upgrading Istio can be done by first running a canary deployment of the new control plane, allowing you
@ -53,16 +53,16 @@ After running the command, you will have two control plane deployments and servi
{{< text bash >}}
$ kubectl get pods -n istio-system -l app=istiod
NAME READY STATUS RESTARTS AGE
istiod-786779888b-p9s5n 1/1 Running 0 114m
istiod-canary-6956db645c-vwhsk 1/1 Running 0 1m
NAME READY STATUS RESTARTS AGE
istiod-1-9-5-bdf5948d5-htddg 1/1 Running 0 47s
istiod-canary-84c8d4dcfb-skcfv 1/1 Running 0 25s
{{< /text >}}
{{< text bash >}}
$ kubectl get svc -n istio-system -l app=istiod
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istiod ClusterIP 10.32.5.247 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 33d
istiod-canary ClusterIP 10.32.6.58 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP,53/UDP,853/TCP 12m
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istiod-1-9-5 ClusterIP 10.96.93.151 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 109s
istiod-canary ClusterIP 10.104.186.250 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 87s
{{< /text >}}
You will also see that there are two sidecar injector configurations including the new revision.
@ -70,8 +70,8 @@ You will also see that there are two sidecar injector configurations including t
{{< text bash >}}
$ kubectl get mutatingwebhookconfigurations
NAME WEBHOOKS AGE
istio-sidecar-injector 1 7m56s
istio-sidecar-injector-canary 1 3m18s
istio-sidecar-injector-1-9-5 2 2m16s
istio-sidecar-injector-canary 2 114s
{{< /text >}}
## Data plane
@ -80,7 +80,7 @@ Unlike istiod, Istio gateways do not run revision-specific instances, but are in
You can verify that the `istio-ingress` gateway is using the `canary` revision by running the following command:
{{< text bash >}}
$ istioctl proxy-status | grep $(kubectl -n istio-system get pod -l app=istio-ingressgateway -o jsonpath='{.items..metadata.name}') | awk '{print $7}'
$ istioctl proxy-status | grep "$(kubectl -n istio-system get pod -l app=istio-ingressgateway -o jsonpath='{.items..metadata.name}')" | awk '{print $10}'
istiod-canary-6956db645c-vwhsk
{{< /text >}}
@ -109,7 +109,7 @@ $ istioctl proxy-status | grep "\.test-ns "
The output will show all pods under the namespace that are using the canary revision.
## Stable revision labels (Alpha)
## Stable revision labels
{{< tip >}}
If you're using Helm, refer to the [Helm upgrade documentation](/docs/setup/upgrade/helm).
@ -121,19 +121,72 @@ If you're using Helm, refer to the [Helm upgrade documentation](/docs/setup/upgr
{{< boilerplate revision-tags-usage >}}
{{< text bash >}}
$ istioctl tag set prod-stable --revision 1-9-5
$ istioctl tag set prod-canary --revision 1-10-0
{{< /text >}}
1. Install two revisions of control plane:
{{< text bash >}}
$ istioctl install --revision=1-9-5 --set profile=minimal --skip-confirmation
$ istioctl install --revision=1-10-0 --set profile=minimal --skip-confirmation
{{< /text >}}
1. Create `stable` and `canary` revision tags and associate them to the respective revisions:
{{< text bash >}}
$ istioctl tag set prod-stable --revision 1-9-5
$ istioctl tag set prod-canary --revision 1-10-0
{{< /text >}}
1. Label application namespaces to map to the respective revision tags:
{{< text bash >}}
$ kubectl create ns app-ns-1
$ kubectl label ns app-ns-1 istio.io/rev=prod-stable
$ kubectl create ns app-ns-2
$ kubectl label ns app-ns-2 istio.io/rev=prod-stable
$ kubectl create ns app-ns-3
$ kubectl label ns app-ns-3 istio.io/rev=prod-canary
{{< /text >}}
1. Bring up a sample sleep pod in each namespace:
{{< text bash >}}
$ kubectl apply -n app-ns-1 -f samples/sleep/sleep.yaml
$ kubectl apply -n app-ns-2 -f samples/sleep/sleep.yaml
$ kubectl apply -n app-ns-3 -f samples/sleep/sleep.yaml
{{< /text >}}
1. Verify application to control plane mapping using `istioctl proxy-status` command:
{{< text bash >}}
$ istioctl ps
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
sleep-78ff5975c6-62pzf.app-ns-3 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-s8zfg 1.16.1
sleep-78ff5975c6-8kxpl.app-ns-1 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-9-5-bdf5948d5-n72r2 1.16.1
sleep-78ff5975c6-8q7m6.app-ns-2 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-9-5-bdf5948d5-n72r2 1.16.1
{{< /text >}}
{{< boilerplate revision-tags-middle >}}
{{< text bash >}}
$ istioctl tag set prod-stable --revision 1-10-0
$ istioctl tag set prod-stable --revision 1-10-0 --overwrite
{{< /text >}}
{{< boilerplate revision-tags-prologue >}}
{{< text bash >}}
$ kubectl rollout restart deployment -n app-ns-1
$ kubectl rollout restart deployment -n app-ns-2
{{< /text >}}
Verify the application to control plane mapping using `istioctl proxy-status` command:
{{< text bash >}}
$ istioctl ps
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
sleep-5984f48bc7-kmj6x.app-ns-1 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-jsktb 1.16.1
sleep-78ff5975c6-jldk4.app-ns-3 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-jsktb 1.16.1
sleep-7cdd8dccb9-5bq5n.app-ns-2 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-jsktb 1.16.1
{{< /text >}}
### Default tag
{{< boilerplate revision-tags-default-intro >}}
@ -146,10 +199,10 @@ $ istioctl tag set default --revision 1-10-0
## Uninstall old control plane
After upgrading both the control plane and data plane, you can uninstall the old control plane. For example, the following command uninstalls a control plane of revision `1-6-5`:
After upgrading both the control plane and data plane, you can uninstall the old control plane. For example, the following command uninstalls a control plane of revision `1-9-5`:
{{< text bash >}}
$ istioctl uninstall --revision 1-6-5 -y
$ istioctl uninstall --revision 1-9-5 -y
{{< /text >}}
If the old control plane does not have a revision label, uninstall it using its original installation options, for example:
@ -171,7 +224,11 @@ Note that the above instructions only removed the resources for the specified co
## Uninstall canary control plane
If you decide to rollback to the old control plane, instead of completing the canary upgrade,
you can uninstall the canary revision using `istioctl uninstall --revision=canary`.
you can uninstall the canary revision using:
{{< text bash >}}
$ istioctl uninstall --revision=canary -y
{{< /text >}}
However, in this case you must first reinstall the gateway(s) for the previous revision manually,
because the uninstall command will not automatically revert the previously in-place upgraded ones.
@ -181,3 +238,17 @@ Make sure to use the `istioctl` version corresponding to the old control plane t
old gateways and, to avoid downtime, make sure the old gateways are up and running before proceeding
with the canary uninstall.
{{< /tip >}}
## Cleanup
1. Clean up the namespaces used for canary upgrade with revision labels example:
{{< text bash >}}
$ kubectl delete ns istio-system test-ns
{{< /text >}}
1. Clean up the namespaces used for canary upgrade with revision tags example:
{{< text bash >}}
$ kubectl delete ns istio-system app-ns-1 app-ns-2 app-ns-3
{{< /text >}}

54
content/en/docs/setup/upgrade/canary/revision_tags_test.sh Normal file
View File

@ -0,0 +1,54 @@
#!/usr/bin/env bash
# Copyright Istio Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
source "tests/util/samples.sh"
set -e
set -u
set -o pipefail
# @setup profile=none
# setup two control plane revisions
snip_usage_1
_wait_for_deployment istio-system istiod-1-9-5
_wait_for_deployment istio-system istiod-1-10-0
# tag the revisions
snip_usage_2
# deploy app namespaces and label them
snip_usage_3
snip_usage_4
_wait_for_deployment app-ns-1 sleep
_wait_for_deployment app-ns-2 sleep
_wait_for_deployment app-ns-3 sleep
# verify both the revisions are managing workloads
_verify_contains snip_usage_5 "istiod-1-9-5"
_verify_contains snip_usage_5 "istiod-1-10-0"
# update the stable revision
snip_usage_6
# restart the older stable revision namespaces
snip_usage_7
# verify only the canary revision is managing workloads
_verify_not_contains snip_usage_8 "istiod-1-9-5"
_verify_contains snip_usage_8 "istiod-1-10-0"
# @cleanup
snip_uninstall_old_control_plane_1
istioctl uninstall --purge -y
snip_cleanup_2

175
content/en/docs/setup/upgrade/canary/snips.sh Normal file
View File

@ -0,0 +1,175 @@
#!/bin/bash
# shellcheck disable=SC2034,SC2153,SC2155,SC2164
# Copyright Istio Authors. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
####################################################################################################
# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE:
# docs/setup/upgrade/canary/index.md
####################################################################################################
source "content/en/boilerplates/snips/revision-tags-middle.sh"
source "content/en/boilerplates/snips/revision-tags-prologue.sh"
snip_before_you_upgrade_1() {
istioctl x precheck
}
! read -r -d '' snip_before_you_upgrade_1_out <<\ENDSNIP
✔ No issues found when checking the cluster. Istio is safe to install or upgrade!
To get started, check out https://istio.io/latest/docs/setup/getting-started/
ENDSNIP
snip_control_plane_1() {
istioctl install --set values.pilot.env.PILOT_ENABLE_CONFIG_DISTRIBUTION_TRACKING=true --set revision=canary
}
snip_control_plane_2() {
kubectl get pods -n istio-system -l app=istiod
}
! read -r -d '' snip_control_plane_2_out <<\ENDSNIP
NAME READY STATUS RESTARTS AGE
istiod-1-9-5-bdf5948d5-htddg 1/1 Running 0 47s
istiod-canary-84c8d4dcfb-skcfv 1/1 Running 0 25s
ENDSNIP
snip_control_plane_3() {
kubectl get svc -n istio-system -l app=istiod
}
! read -r -d '' snip_control_plane_3_out <<\ENDSNIP
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istiod-1-9-5 ClusterIP 10.96.93.151 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 109s
istiod-canary ClusterIP 10.104.186.250 <none> 15010/TCP,15012/TCP,443/TCP,15014/TCP 87s
ENDSNIP
snip_control_plane_4() {
kubectl get mutatingwebhookconfigurations
}
! read -r -d '' snip_control_plane_4_out <<\ENDSNIP
NAME WEBHOOKS AGE
istio-sidecar-injector-1-9-5 2 2m16s
istio-sidecar-injector-canary 2 114s
ENDSNIP
snip_data_plane_1() {
istioctl proxy-status | grep "$(kubectl -n istio-system get pod -l app=istio-ingressgateway -o jsonpath='{.items..metadata.name}')" | awk '{print $10}'
}
! read -r -d '' snip_data_plane_1_out <<\ENDSNIP
istiod-canary-6956db645c-vwhsk
ENDSNIP
snip_data_plane_2() {
kubectl label namespace test-ns istio-injection- istio.io/rev=canary
}
snip_data_plane_3() {
kubectl rollout restart deployment -n test-ns
}
snip_data_plane_4() {
istioctl proxy-status | grep "\.test-ns "
}
snip_usage_1() {
istioctl install --set values.pilot.env.PILOT_ENABLE_CONFIG_DISTRIBUTION_TRACKING=true --revision=1-9-5 --set profile=minimal --skip-confirmation
istioctl install --set values.pilot.env.PILOT_ENABLE_CONFIG_DISTRIBUTION_TRACKING=true --revision=1-10-0 --set profile=minimal --skip-confirmation
}
snip_usage_2() {
istioctl tag set prod-stable --revision 1-9-5
istioctl tag set prod-canary --revision 1-10-0
}
snip_usage_3() {
kubectl create ns app-ns-1
kubectl label ns app-ns-1 istio.io/rev=prod-stable
kubectl create ns app-ns-2
kubectl label ns app-ns-2 istio.io/rev=prod-stable
kubectl create ns app-ns-3
kubectl label ns app-ns-3 istio.io/rev=prod-canary
}
snip_usage_4() {
kubectl apply -n app-ns-1 -f samples/sleep/sleep.yaml
kubectl apply -n app-ns-2 -f samples/sleep/sleep.yaml
kubectl apply -n app-ns-3 -f samples/sleep/sleep.yaml
}
snip_usage_5() {
istioctl ps
}
! read -r -d '' snip_usage_5_out <<\ENDSNIP
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
sleep-78ff5975c6-62pzf.app-ns-3 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-s8zfg 1.16.1
sleep-78ff5975c6-8kxpl.app-ns-1 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-9-5-bdf5948d5-n72r2 1.16.1
sleep-78ff5975c6-8q7m6.app-ns-2 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-9-5-bdf5948d5-n72r2 1.16.1
ENDSNIP
snip_usage_6() {
istioctl tag set prod-stable --revision 1-10-0 --overwrite
}
snip_usage_7() {
kubectl rollout restart deployment -n app-ns-1
kubectl rollout restart deployment -n app-ns-2
}
snip_usage_8() {
istioctl ps
}
! read -r -d '' snip_usage_8_out <<\ENDSNIP
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
sleep-5984f48bc7-kmj6x.app-ns-1 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-jsktb 1.16.1
sleep-78ff5975c6-jldk4.app-ns-3 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-jsktb 1.16.1
sleep-7cdd8dccb9-5bq5n.app-ns-2 Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-1-10-0-7f6fc6cfd6-jsktb 1.16.1
ENDSNIP
snip_default_tag_1() {
istioctl tag set default --revision 1-10-0
}
snip_uninstall_old_control_plane_1() {
istioctl uninstall --revision 1-9-5 -y
}
snip_uninstall_old_control_plane_2() {
istioctl uninstall -f manifests/profiles/default.yaml -y
}
snip_uninstall_old_control_plane_3() {
kubectl get pods -n istio-system -l app=istiod
}
! read -r -d '' snip_uninstall_old_control_plane_3_out <<\ENDSNIP
NAME READY STATUS RESTARTS AGE
istiod-canary-55887f699c-t8bh8 1/1 Running 0 27m
ENDSNIP
snip_uninstall_canary_control_plane_1() {
istioctl uninstall --revision=canary -y
}
snip_cleanup_1() {
kubectl delete ns istio-system test-ns
}
snip_cleanup_2() {
kubectl delete ns istio-system app-ns-1 app-ns-2 app-ns-3
}