Upgrading Means Moving a Name Tag
In one line
If you install with a revision, the new version's control plane stands next to the old one. You let workloads know only the revision tag, and an upgrade becomes moving where the tag points and then restarting the workloads. Until you delete the old version, rolling back is a single tag line.
Why this was needed
If you upgrade Istio in place, the moment istiod changes, the whole mesh attaches to the new control plane. If there is a problem with the new version, every workload is affected at once, and to roll back you have to reinstall the old version. A sidecar is injected when a Pod is created, so after changing the control plane there is also an unavoidable period in which proxies of the two versions run mixed until you restart all the Pods.
A revision turns that mixed period into a controlled order. You stand up the new version under a separate name (istiod-1-31-0), move one namespace at a time while watching, and delete the old version after everything has moved.
How it works
Revision install — istioctl install --set revision=1-31-0 creates an istiod and an injection webhook (istio-sidecar-injector-1-31-0) with the revision in their names. The old revision's are left as they are.
The namespace label decides which version's sidecar to receive.
| Label | Meaning |
|---|---|
istio.io/rev=1-31-0 |
That revision's webhook injects |
istio.io/rev=prod-stable |
The revision the tag prod-stable points to injects |
istio-injection=enabled |
The default tag (or an install without a revision) injects |
A tag is a single webhook. istioctl tag set prod-stable --revision 1-31-0 makes the injection webhook named istio-revision-tag-prod-stable call the istiod of 1-31-0. If a workload's label points at prod-stable, then just by moving the tag, the Pods created next receive the new version. Pods that are already running change only when restarted.
So the order is like this.
1. precheck 새 판이 이 클러스터에 올라가도 되는가
2. 새 리비전 설치 istiod-1-31-0 가 옆에 선다 (트래픽 변화 없음)
3. 카나리 네임스페이스 이동 라벨을 1-31-0 으로 + 재시작 → 섞인 상태에서 통신 확인
4. 태그 이동 + 나머지 재시작 prod-stable → 1-31-0
5. 되돌리기 연습 태그를 옛 리비전으로 옮겨 재시작 → 다시 앞으로
6. 옛 리비전 제거 모든 프록시가 옮긴 뒤 uninstall --revision 1-30-5
The fact that communication works even while the proxies of the two versions are mixed is thanks to the compatibility rules the official docs state — data planes are currently compatible across all versions (with the caveat that this may change in the future), and a control plane may be one version ahead of the data plane but cannot lag behind it. That is why the docs recommend the revision approach, which removes the version difference itself, and the order of moving is also 'control plane first, proxies later'.
What it looks like in the field
"I changed the label but the proxy version is the same." You did not restart the Pods. Injection happens at Pod creation time.
"I deleted the old revision and some Pods cannot get configuration." Pods that were not restarted were attached to the old istiod. Before deleting, check with istioctl proxy-status that no proxy is attached to the old revision.
"I installed a new revision but nothing changed for the existing Pods." That is normal. Installing a revision does not change traffic — running Pods are still attached to the old istiod, and the new webhook is called only when a Pod is newly created in a namespace whose label points at that revision.
"I did not use tags and wrote the revision name in every namespace." You have to fix every namespace label at each upgrade. A tag reduces that job to one line.
Official docs: Canary Upgrades · Supported releases · istioctl tag · istioctl x precheck
What you will do in the next lab
In a mesh where the recipe installed only revision 1-30-5, you run the precheck and stand 1.31.0 up next to it as revision 1-31-0. You move only the canary namespace first and confirm that it communicates with the two versions mixed, then move the tag to bring up the rest and practice the rollback once. Finally you delete the old revision.