Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

This walkthrough demonstrates a canary-style Istio control plane upgrade from 1.26.2 → 1.26.3 and how to migrate workloads safely to the new revision. This upgrade pattern is commonly used in production and is covered in the Prep Course - Istio Certified Associate (ICA) Certification. Key goals:
  • Install a new Istio control plane revision alongside the existing one (canary install).
  • Migrate namespaces and workloads incrementally to the new revision.
  • Safely uninstall the old revision after confirming no proxies remain attached.
Prerequisites:
  • A Kubernetes cluster with Istio already installed (demo profile).
  • Bookinfo sample application for test workloads.

​
1) Inspect current Istio installation and workloads

Start by checking Istio system pods and application workloads to understand the current state. Check control plane components: 
# Istio control plane components
kubectl get pods -n istio-system
Example output: 
NAME                                   READY   STATUS    RESTARTS   AGE
istio-egressgateway-5478b96959-h7qzm   1/1     Running   0          5m10s
istio-ingressgateway-7dddb56f89-wjsp4  1/1     Running   0          5m10s
istiod-57dcc6d8b-wkf2n                 1/1     Running   0          5m20s
Check application workloads (Bookinfo): 
# Application workloads (bookinfo)
kubectl get pods
Example output: 
NAME                               READY   STATUS    RESTARTS   AGE
details-v1-65599dcf88-rgvm8        2/2     Running   0          4m14s
productpage-v1-9487c9c5b-mvv6k     2/2     Running   0          4m13s
ratings-v1-59b99c644-76r4h         2/2     Running   0          4m14s
reviews-v1-5985998544-s5tvt        2/2     Running   0          4m13s
reviews-v2-86d6cc668-pzz89         2/2     Running   0          4m13s
reviews-v3-dbb5fb5dd-c52wl         2/2     Running   0          4m13s
Verify Istio client, control plane, and data plane versions: 
istioctl version
Example output: 
client version: 1.26.2
control plane version: 1.26.2
data plane version: 1.26.2 (8 proxies)
Confirm which control plane revision each proxy is using: 
istioctl proxy-status
The VERSION column should show the control plane revision (for example 1.26.2 or the revision tag such as default).

​
2) Download the new istioctl (1.26.3)

Fetch the istioctl binary for the target control plane release and add it to your PATH so you can install the new revision. 
# Download Istio 1.26.3
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.26.3 sh -

# Add istioctl for 1.26.3 to PATH (example path for root user)
export PATH="$PATH:/root/istio-1.26.3/bin"

# Confirm client version changed
istioctl version
After updating PATH you should see something like: 
client version: 1.26.3
control plane version: 1.26.2
data plane version: 1.26.2 (8 proxies)
Note that installing a newer istioctl client does not upgrade the control plane by itself; next you will install a new control plane revision.

​
3) Install the new control plane as a new revision (canary)

Install a new Istio control plane revision using the demo profile and specify a revision identifier. In this guide we use 1-26-3 as the revision tag. 
istioctl install --set profile=demo --revision=1-26-3
Approve the prompt by entering y. After installation completes, verify pods in the istio-system namespace: 
kubectl get pods -n istio-system
You should observe both control planes active (the original default istiod and the new istiod-1-26-3) plus ingress/egress gateways.

​
4) Create a revision tag and enable injection per namespace

Register a user-friendly tag that points to the new revision and opt namespaces into that revision by labeling them. Create a tag named latest that maps to the new revision: 
istioctl tag set latest --revision 1-26-3
Label the namespace so automatic sidecar injection targets the tagged revision. For the default namespace: 
kubectl label namespace default istio.io/rev=latest --overwrite
Alternatively, edit the namespace: 
kubectl edit ns default
# add metadata.labels:
#   istio.io/rev: latest
Verify the label: 
kubectl get ns default --show-labels
Expected label output: 
default   Active   <age>   istio.io/rev=latest,kubernetes.io/metadata.name=default
Using revision-based labels (istio.io/rev) is the recommended approach for multi-revision installations. This replaces legacy patterns such as sidecar.istio.io/inject or istio-injection=enabled when running revisioned control planes.
After you label a namespace with istio.io/rev=<tag>, restarting workloads in that namespace (for example via kubectl rollout restart deployment <name> or deleting pods) is required for them to receive sidecars associated with the new revision.

​
5) Recreate workloads so sidecars inject the new revision

Labeling a namespace only affects new pod creations. Existing pods keep their current sidecar. To adopt the new control plane you must recreate or restart workloads so the sidecar injected uses the new revision. Example: delete and reapply the Bookinfo sample so injected sidecars target 1-26-3: 
# Delete the sample (ensure correct URL)
kubectl delete -f https://raw.githubusercontent.com/istio/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo.yaml

# Reapply the sample so pods are injected with the new revision
kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo.yaml
Watch pod status: 
kubectl get pods
Pods may show 0/2 PodInitializing while the sidecar container is injected. Once pods reach 2/2 Running, validate the injected proxy image: 
kubectl describe pod details-v1-<pod-suffix>
Look for the istio-proxy container Image; it should indicate docker.io/istio/proxyv2:1.26.3. You can also confirm all application proxies have migrated: 
istioctl proxy-status
All proxies should now show VERSION 1.26.3 and reference the new control plane pods such as istiod-1-26-3-....

​
6) Migrate workloads gradually (canary-style)

A canary migration minimizes risk by routing only a subset of workloads or traffic to the new revision while monitoring behavior. Migration strategies:
  • Deploy to a new namespace labeled for the new revision and run tests there.
  • Stagger restarts by performing kubectl rollout restart deployment <app> per deployment.
  • Use telemetry and dashboards (Prometheus/Grafana) to validate the new revision before migrating additional workloads.
Examples: 
# Restart all deployments in a namespace
kubectl rollout restart deployment -n default

# Restart a specific deployment
kubectl rollout restart deployment details-v1 -n default
Monitor metrics and logs during the rollout to catch regressions early.

​
7) Uninstall the old control plane revision when safe

Only uninstall an old revision after confirming no proxies are attached to it. Istio protects you by warning if proxies still reference the revision you intend to remove. Confirm proxy assignments: 
istioctl proxy-status
Attempt to uninstall the old revision (for example default): 
istioctl uninstall --revision default
If proxies still reference the old revision, istioctl will display a message like: 
There are still 8 proxies pointing to the control plane revision default
details-v1-...default
productpage-v1-...default
...
If you proceed with the uninstall, these proxies will become detached from any control plane and will not function correctly.
Proceed? (y/N)
Do not uninstall a control plane revision while active proxies still reference it. Confirm all workloads have been migrated to the new revision (use istioctl proxy-status) before uninstalling the old revision.
If you confirm and proceed, istioctl removes objects associated with that revision and displays the deleted resources, concluding with: 
✓ Uninstall complete
Verify the istio-system namespace contains only the new revision: 
kubectl get pods -n istio-system
You should now see istiod-1-26-3, ingress/egress gateways, and no pods belonging to the old default revision.

​
Summary / Key steps

StepActionExample command
1Confirm current Istio versions and proxy assignmentistioctl version / istioctl proxy-status
2Download istioctl for the target release`curl -L https://istio.io/downloadIstioISTIO_VERSION=1.26.3 sh -`
3Install new revision (canary control plane)istioctl install --set profile=demo --revision=1-26-3
4Tag the new revisionistioctl tag set latest --revision 1-26-3
5Opt-in namespaces to new revisionkubectl label namespace <ns> istio.io/rev=latest --overwrite
6Restart or re-create workloads to inject new sidecarskubectl rollout restart deployment <name> or reapply manifests
7Validate proxies point to new revisionistioctl proxy-status
8Uninstall the old revision when safeistioctl uninstall --revision <old-rev>
This canary pattern gives you a safe, progressive upgrade path for Istio control plane updates with minimal disruption. Practice these steps in a test cluster to gain confidence before attempting production upgrades.

Watch Video

Practice Lab