古い版を消す前に一度戻してみる

目標

Istio 1.30.5を使う本物のメッシュを、リビジョンのカナリア方式で1.31.0に上げます。2つのコントロールプレーンを並べて立て、1つのネームスペースだけを先に移し、タグで残りを移した後でロールバックを練習し、最後に旧バージョンを消します。

なぜ重要なのか

コントロールプレーンのアップグレードは、メッシュ全体の設定の供給元を変える作業です。インプレースのアップグレードは、問題が起きるとみんなが一度に経験し、戻すのも難しくなります。リビジョンとタグを使えば、影響範囲をネームスペース単位に絞り、ロールバックを1行にできます。ただし、順序を守ったときだけです。

ステップ

kubectl apply -f /opt/fixtures/istlab/upgrade-app.yamlで材料(shopのweb、canaryのclient。2つのネームスペースともistio.io/rev=prod-stable)を載せ、準備ができるまで待ってください。その後、/root/istlab-upgrade/01-before.txtに、web_proxy=・client_proxy=(各Podのistio-proxyイメージのタグ)とprod_stable=(istioctl tag listでタグprod-stableが指すリビジョン)の3行を書いてください。
istioctl x precheckの出力を/root/istlab-upgrade/02-precheck.txtに保存してください。
1.31.0をリビジョン1-31-0としてインストールしてください。istioctl install --set profile=minimal --set revision=1-31-0 --set meshConfig.accessLogFile=/dev/stdout -yです。インストール後、2つのistiod(istiod-1-30-5・istiod-1-31-0)が一緒に起動している必要があり、ワークロードはまだ何も変わっていない必要があります。
canaryネームスペースのラベルをistio.io/rev=1-31-0に変えて、clientを再起動してください。その後、/root/istlab-upgrade/04-mixed.txtに、client_proxy=・web_proxy=(各プロキシイメージのタグ)とcode=(clientからhttp://web.shop/のステータスコード)の3行を書いてください。
タグprod-stableとdefaultを、どちらもリビジョン1-31-0に移してください(istioctl tag set <태그> --revision 1-31-0 --overwrite、プレースホルダーはタグ名です)。その後、canaryのラベルをistio.io/rev=prod-stableに戻し、shopのwebを再起動して、1.31.0のプロキシを受け取らせてください。
消す前にロールバックできるかを確認してください。タグprod-stableを1-30-5に移してwebを再起動し、プロキシのタグを/root/istlab-upgrade/06-rollback.txtにafter_rollback=の形で書いた後、もう一度1-31-0に移してwebを再起動し、after_forward=として追記してください。
すべてのプロキシが1.31.0であることを確認した後、istioctl uninstall --revision 1-30-5 -yで旧リビジョンを消し、istiod-1-30-5のDeploymentと、インジェクションWebhookのistio-sidecar-injector-1-30-5が消えるまで待ってください。その後も、canaryのclientからhttp://web.shop/は200である必要があります。
/root/istlab-upgrade/08-report.mdに5行を書き、その下に学んだことを4行以上書いてください。5行は、old_revision=・new_revision=(リビジョン名)、mixed_versions_code=(ステップ4のcode)、rollback_version=(ステップ6のafter_rollback)、old_injector_left=(現在istio-sidecar-injector-1-30-5のWebhookが残っていればyes)です。

参考

このVMは準備に2–4分かかります。リビジョン1-30-5(タグprod-stable)だけがインストールされていて、1.31.0のディストリビューションは/usr/local/istio-1.31.0にダウンロードしてあります。ログインシェルのistioctlは1.31.0です。
プロキシのバージョンは、istioctl proxy-statusのVERSION欄や、Podのistio-proxyイメージのタグで見ます。再起動の直後のproxy-statusは、しばらく旧Podを表示することがあるので、イメージで確認するほうが確実です。
ラベルを変えた後は、必ずkubectl rollout restartでPodを作り直してください。注入はPodが作られるときに起きます。
よくある失敗: ロールバックを確認する前に旧リビジョンを消すケースです。その後は、戻すには旧バージョンを再インストールする必要があります。

現在、何が何を指しているかを書く

kubectl apply -f /opt/fixtures/istlab/upgrade-app.yamlで材料(shopのweb、canaryのclient。2つのネームスペースともistio.io/rev=prod-stable)を載せ、準備ができるまで待ってください。その後、/root/istlab-upgrade/01-before.txtに、web_proxy=・client_proxy=(各Podのistio-proxyイメージのタグ)とprod_stable=(istioctl tag listでタグprod-stableが指すリビジョン)の3行を書いてください。

このVMのコントロールプレーンはリビジョン1-30-5だけでインストールされていて、ワークロードはリビジョン名ではなくタグprod-stableで注入を受けます。タグは「現在、本番で使うリビジョン」を指すラベルなので、アップグレードは、ワークロードのラベルを1つずつ直す作業ではなく、このラベルを移す作業になります。このVMのistioctlは1.31.0ですが、タグの一覧はバージョンに関係なく読めます。

上げる前に尋ねる: precheck

istioctl x precheckの出力を/root/istlab-upgrade/02-precheck.txtに保存してください。

precheckは、クラスターが新しいバージョンを受け入れる準備ができているか(Kubernetesのバージョン、権限、古い設定の非推奨フィールドなど)を調べます。ここで警告が出たら、インストールよりそれを先に直すのが順序です。1.31.0のistioctlで実行すれば、1.31.0を基準に見ます。

新バージョンを旧バージョンの隣に立てる

1.31.0をリビジョン1-31-0としてインストールしてください。istioctl install --set profile=minimal --set revision=1-31-0 --set meshConfig.accessLogFile=/dev/stdout -yです。インストール後、2つのistiod(istiod-1-30-5・istiod-1-31-0)が一緒に起動している必要があり、ワークロードはまだ何も変わっていない必要があります。

リビジョンでインストールすると、名前にリビジョンが付いたistiodとインジェクションWebhook(istio-sidecar-injector-1-31-0)が新しくでき、古いものはそのまま残ります。どのネームスペースも新しいリビジョンを指していないので、この瞬間のトラフィックには何の変化もありません。そのため、インストール自体はいつでも安全に行えます。istioctl tag listに、新しいリビジョンがタグなしで1行表示されます。

1つのネームスペースだけを新バージョンに移す

canaryネームスペースのラベルをistio.io/rev=1-31-0に変えて、clientを再起動してください。その後、/root/istlab-upgrade/04-mixed.txtに、client_proxy=・web_proxy=(各プロキシイメージのタグ)とcode=(clientからhttp://web.shop/のステータスコード)の3行を書いてください。

ラベルを変えるだけでは何も起きません。サイドカーはPodが作られるときに注入されるので、再起動して初めて新しいリビジョンのプロキシを受け取ります。このように1つのネームスペースだけを先に移すのがカナリアです。問題が起きても、そのネームスペースだけを戻せば済みます。公式ドキュメントは、データプレーン同士は現在すべてのバージョン間で互換があると述べているので(将来変わる可能性があるという但し書き付きで)、混ざったままでもmTLSが張れるはずです。

ラベルを移す: タグで残りを上げる

タグprod-stableとdefaultを、どちらもリビジョン1-31-0に移してください(istioctl tag set <태그> --revision 1-31-0 --overwrite、プレースホルダーはタグ名です)。その後、canaryのラベルをistio.io/rev=prod-stableに戻し、shopのwebを再起動して、1.31.0のプロキシを受け取らせてください。

タグは実際にはインジェクションWebhook1つです(istio-revision-tag-prod-stable)。タグを移すと、そのWebhookが指すistiodが変わり、そのタグを使うネームスペースで新しく作られるPodは、新しいリビジョンのプロキシを受け取ります。カナリアとして移しておいたcanaryもタグに戻しておけば、今後はタグ1つだけを管理すれば済みます。defaultタグは、istio-injection=enabledラベルを使うネームスペースと、istioctlのデフォルトの対象を決めます。

ロールバックを練習しておく

消す前にロールバックできるかを確認してください。タグprod-stableを1-30-5に移してwebを再起動し、プロキシのタグを/root/istlab-upgrade/06-rollback.txtにafter_rollback=の形で書いた後、もう一度1-31-0に移してwebを再起動し、after_forward=として追記してください。

旧リビジョンが生きている間は、ロールバックはタグ1行と再起動1回です。旧リビジョンを消した後は、そのバージョンを再インストールする必要があります。そのため運用では、新バージョンで十分に過ごした後で旧リビジョンを消し、その前に、戻す道が実際に使えるかを一度試します。再起動後にプロキシが変わったかは、Podのistio-proxyイメージで確認します。

すべて移った後で旧バージョンを消す

すべてのプロキシが1.31.0であることを確認した後、istioctl uninstall --revision 1-30-5 -yで旧リビジョンを消し、istiod-1-30-5のDeploymentと、インジェクションWebhookのistio-sidecar-injector-1-30-5が消えるまで待ってください。その後も、canaryのclientからhttp://web.shop/は200である必要があります。

リビジョンを指定したuninstallは、そのリビジョンのコントロールプレーンだけを消し、他のリビジョンとワークロードには触れません。まだ旧リビジョンのプロキシを使うPodが残っていれば、そのPodは設定を受け取る先を失います。そのため、消す前にistioctl proxy-statusとPodのイメージで、残っているものがないかを確認します。消した直後は、しばらく0/1のまま見えることがあるので、消えるまで待ってください。

アップグレードの記録を残す

/root/istlab-upgrade/08-report.mdに5行を書き、その下に学んだことを4行以上書いてください。5行は、old_revision=・new_revision=(リビジョン名)、mixed_versions_code=(ステップ4のcode)、rollback_version=(ステップ6のafter_rollback)、old_injector_left=(現在istio-sidecar-injector-1-30-5のWebhookが残っていればyes)です。

説明の行には、「インプレースのアップグレードの代わりにリビジョンを使うと何が得られるか」と「旧リビジョンをいつ消すか」を、自分の言葉で書いておいてください。