Skip to main content
In this lesson we will walk through a canary upgrade of Istio control plane from 1.26.2 to 1.26.3 and how to migrate workloads safely to the new revision. The process uses Istio revisioned installs so you can run the old and new control planes side-by-side, move workloads to the new revision, and then uninstall the old one. Prerequisites used in this article:
  • A Kubernetes cluster with Istio installed (profile: demo).
  • Bookinfo sample application for testing.
  1. Check the current Istio and workload state
First, verify the Istio system components and the Bookinfo workloads.
Example output:
Check the running Bookinfo workloads:
Example output:
Confirm the client, control plane, and data plane versions:
Example output:
To inspect what proxy version a pod’s sidecar is running, you can describe the pod and look at the istio-proxy image:
Example snippet from kubectl describe pod ratings-...:
Or use istioctl proxy-status to get a concise mapping of proxies to control plane revisions:
  1. Download the new istioctl (1.26.3)
Download the new Istio release and add it to your PATH. Replace the ISTIO_VERSION if you want a different version.
After exporting PATH, verify the client version has updated while your control and data planes remain on the old version:
Example output:
  1. Install the new Istio control plane as a revision
Install Istio 1.26.3 as a new revision (revision name chosen here is 1-26-3). We keep the demo profile for this example.
Confirm the new control plane pods appear alongside the old ones:
Example output:
  1. Create a revision tag and label namespaces for injection
Create a human-friendly tag (e.g., latest) that points to the new control plane revision:
This command outputs guidance: to enable injection using this revision tag, label the namespace:
Label the namespace where your app lives (for this demo the default namespace):
Verify the namespace label:
Example output:
Note: Using istio.io/rev=<tag> enables automatic sidecar injection for that namespace to target the specified control plane revision.
  1. Migrate workloads to the new revision
There are two common ways to move workloads to the new revision:
  • Redeploy the workloads (delete and reapply or use kubectl rollout restart) so the injected sidecar uses the new revision tag.
  • Alternatively, if pods were created with manual injection, update them accordingly.
Example: redeploy Bookinfo workloads by deleting and reapplying the sample:
Check pod status while pods initialize:
Once pods are running, describe a pod to confirm the istio-proxy image version:
Example excerpt showing the proxy is now 1.26.3:
Also check istioctl proxy-status to ensure the proxies are attached to the new istiod revision:
Example output (all proxies pointing to istiod 1.26.3):
You can also use kubectl rollout restart deployment/<deployment-name> to trigger a restart and pick up the new revision tag.
Before uninstalling the old control plane, ensure every workload has been migrated to the new revision. Uninstalling the old revision while proxies still point to it will detach those proxies and break traffic.
  1. Uninstall the old revision
Once you’re confident all workloads and gateways are using the new revision, uninstall the old control plane revision (for example the default revision). First confirm which pods are still associated with the default revision (labels and istioctl proxy-status help with this). Uninstall the old revision:
If there are still proxies pointing to the revision, istioctl will warn you and list those proxies. Confirm only after you have migrated everything. Example uninstall output:
  1. Final verification
Check that only the new revision remains in the istio-system namespace and that all application pods are using the new proxy:
Example istio-system output after cleanup:
And your workloads should show 2/2 with the updated sidecar proxy version (1.26.3). Summary
  • Download and use a new istioctl client for the target control plane version.
  • Install the new control plane as a revision with --revision=....
  • Create a tag (e.g., latest) pointing to the new revision with istioctl tag set.
  • Label namespaces with istio.io/rev=<tag> to route injection to the new revision.
  • Redeploy or restart workloads to pick up the new sidecar (or reapply manifests).
  • After confirming all proxies are attached to the new control plane, uninstall the old revision.
This revision-based canary install flow lets you upgrade Istio with minimal disruption and a straightforward rollback path if needed.

Watch Video

Practice Lab