> ## 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. # Demo Canary Release Istio Upgrade > Walkthrough for a canary Istio control plane upgrade from 1.26.2 to 1.26.3, demonstrating revisioned installs, namespace migration, sidecar injection, gradual rollout, and safe uninstall 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](https://learn.kodekloud.com/user/courses/istio-certified-associate-ica). 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: ```bash theme={null} # Istio control plane components kubectl get pods -n istio-system ``` Example output: ```bash theme={null} 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): ```bash theme={null} # Application workloads (bookinfo) kubectl get pods ``` Example output: ```bash theme={null} 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: ```bash theme={null} istioctl version ``` Example output: ```bash theme={null} 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: ```bash theme={null} 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. ```bash theme={null} # 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: ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} istioctl tag set latest --revision 1-26-3 ``` Label the namespace so automatic sidecar injection targets the tagged revision. For the `default` namespace: ```bash theme={null} kubectl label namespace default istio.io/rev=latest --overwrite ``` Alternatively, edit the namespace: ```bash theme={null} kubectl edit ns default # add metadata.labels: # istio.io/rev: latest ``` Verify the label: ```bash theme={null} kubectl get ns default --show-labels ``` Expected label output: ```text theme={null} default Active 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=`, restarting workloads in that namespace (for example via `kubectl rollout restart deployment ` 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`: ```bash theme={null} # 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: ```bash theme={null} 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: ```bash theme={null} kubectl describe pod details-v1- ``` 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: ```bash theme={null} 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 ` per deployment. * Use telemetry and dashboards (Prometheus/Grafana) to validate the new revision before migrating additional workloads. Examples: ```bash theme={null} # 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: ```bash theme={null} istioctl proxy-status ``` Attempt to uninstall the old revision (for example `default`): ```bash theme={null} istioctl uninstall --revision default ``` If proxies still reference the old revision, istioctl will display a message like: ```text theme={null} 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: ```text theme={null} ✓ Uninstall complete ``` Verify the istio-system namespace contains only the new revision: ```bash theme={null} 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 | Step | Action | Example command | | | ---- | ----------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------- | | 1 | Confirm current Istio versions and proxy assignment | `istioctl version` / `istioctl proxy-status` | | | 2 | Download istioctl for the target release | \`curl -L [https://istio.io/downloadIstio](https://istio.io/downloadIstio) | ISTIO\_VERSION=1.26.3 sh -\` | | 3 | Install new revision (canary control plane) | `istioctl install --set profile=demo --revision=1-26-3` | | | 4 | Tag the new revision | `istioctl tag set latest --revision 1-26-3` | | | 5 | Opt-in namespaces to new revision | `kubectl label namespace istio.io/rev=latest --overwrite` | | | 6 | Restart or re-create workloads to inject new sidecars | `kubectl rollout restart deployment ` or reapply manifests | | | 7 | Validate proxies point to new revision | `istioctl proxy-status` | | | 8 | Uninstall the old revision when safe | `istioctl uninstall --revision ` | | 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. *** ## Links and references * Istio official docs: [https://istio.io/](https://istio.io/) * Istioctl download: [https://istio.io/latest/docs/setup/getting-started/](https://istio.io/latest/docs/setup/getting-started/) * Bookinfo sample (release-1.26): `https://raw.githubusercontent.com/istio/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo.yaml` * KodeKloud Istio Certified Associate (ICA) Prep Course: [https://learn.kodekloud.com/user/courses/istio-certified-associate-ica](https://learn.kodekloud.com/user/courses/istio-certified-associate-ica)