--- name: containers-cs_istio_update title: Updating Istio description: Whenever the Istio managed add-on is updated, update your `istioctl` client and the Istio sidecars for your app. last-updated: 2026-07-27 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/containers?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Updating Istio {: #istio-update} Do not use `istioctl` to update the version of Istio that is installed by the managed add-on. When updated, the managed Istio add-on includes an update of the Istio version as well. Supported versions of Istio are tested by IBM Cloud and approved for the use in IBM Cloud Kubernetes Service. {: important} ## Before you begin {: #istio-update-prereq} - You can only manually update the Istio add-on one version at a time. To update the Istio add-on by two or more versions, you can repeat the manual update process or you can [uninstall](https://cloud.ibm.com/docs/containers?topic=containers-istio&format=markdown#istio_uninstall_addon) the add-on and then [install](https://cloud.ibm.com/docs/containers?topic=containers-istio&format=markdown#istio_install) the later version. - You can't revert your managed Istio add-on to a previous version. To revert to an earlier minor version, you must [uninstall](https://cloud.ibm.com/docs/containers?topic=containers-istio&format=markdown#istio_uninstall_addon) the add-on and then [install](https://cloud.ibm.com/docs/containers?topic=containers-istio&format=markdown#istio_install) the earlier version. - When you update the Istio control components in the `istio-system` namespace to the latest minor version, you might experience disruptive changes. Review the following changes that occur during a minor version update. * As updates are rolled out to control plane pods, the pods are re-created. The Istio control plane is not fully available until after the update completes. * The Istio data plane continues to function during the update. However, some traffic to apps in the service mesh might be interrupted for a short period of time. * The external IP address for the `istio-ingressgateway` load balancer does not change during or after the update. ## Updating to a minor version of the Istio add-on {: #istio_minor} Before you begin: Review the [prerequisites](#istio-update-prereq) that apply to all version updates. To update the minor version of the Istio add-on: 1. Review the available Istio add-on versions. ```sh ibmcloud ks addon-versions ``` {: pre} 1. Review the changes that are in each version in the [Istio add-on change log](https://cloud.ibm.com/docs/containers?topic=containers-cl-add-ons-istio&format=markdown). 1. Update the Istio add-on. ```sh ibmcloud ks cluster addon update istio --version VERSION -c CLUSTER_NAME_OR_ID ``` {: pre} 1. Before you proceed, verify that the update is complete. The update process can take up to 20 minutes to complete. {: note} 1. Ensure that the Istio add-on's **Health State** is `normal` and the **Health Status** is `Addon Ready`. If the state is `updating`, the update is not yet complete. ```sh ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID ``` {: pre} 2. Ensure that the control plane component pods in the `istio-system` namespace have a **STATUS** of `Running`. ```sh kubectl get pods -n istio-system ``` {: pre} ```sh NAME READY STATUS RESTARTS AGE istio-system istio-egressgateway-6d4667f999-gjh94 1/1 Running 0 61m istio-system istio-egressgateway-6d4667f999-txh56 1/1 Running 0 61m istio-system istio-ingressgateway-7bbf8d885-b9xgp 1/1 Running 0 61m istio-system istio-ingressgateway-7bbf8d885-xhkv6 1/1 Running 0 61m istio-system istiod-5b9b5bfbb7-jvcjz 1/1 Running 0 60m istio-system istiod-5b9b5bfbb7-khcht 1/1 Running 0 60m ``` {: screen} 1. [Update your `istioctl` client and sidecars](#update_client_sidecar). ## Updating the `istioctl` client and sidecars {: #update_client_sidecar} Whenever the Istio managed add-on is updated, update your `istioctl` client and the Istio sidecars for your app. {: shortdesc} For example, the patch version of your add-on might be updated automatically by IBM Cloud Kubernetes Service, or you might [update the minor version of your add-on](#istio_minor). In either case, update your `istioctl` client and your app's existing Istio sidecars to match the Istio version of the add-on. 1. Get the version of your `istioctl` client and the Istio add-on control plane components. ```sh istioctl version --short=false ``` {: pre} Example output ```sh client version: version.BuildInfo{Version:"1.11.2"} pilot version: version.BuildInfo{Version:1.29.5} pilot version: version.BuildInfo{Version:1.29.5} data plane version: version.ProxyInfo{ID:"istio-egressgateway-77bf75c5c-vp97p.istio-system", IstioVersion:1.29.5} data plane version: version.ProxyInfo{ID:"istio-egressgateway-77bf75c5c-qkhgm.istio-system", IstioVersion:1.29.5} data plane version: version.ProxyInfo{ID:"istio-ingressgateway-6dcb67b64d-dffhq.istio-system", IstioVersion:1.29.5} data plane version: version.ProxyInfo{ID:"httpbin-74fb669cc6-svc8x.default", IstioVersion:1.29.5} data plane version: version.ProxyInfo{ID:"istio-ingressgateway-6dcb67b64d-cs9r9.istio-system", IstioVersion:1.29.5} ... ``` {: screen} 2. In the output, compare the `client version` (`istioctl`) to the version of the Istio control plane components, such as the `pilot version`. If the `client version` and control plane component versions don't match: 1. Download the `istioctl` client of the same version as the control plane components. ```sh curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.29.5 sh - ``` {: pre} 2. Navigate to the Istio package directory. ```sh cd istio-1.29.5 ``` {: pre} 3. Linux and macOS users: Add the `istioctl` client to your `PATH` system variable. ```sh export PATH=$PWD/bin:$PATH ``` {: pre} 3. In the output of step 1, compare the `pilot version` to the `data plane version` for each data plane pod. * If the `pilot version` and the `data plane version` match, no further updates are required. * If the `pilot version` and the `data plane version` don't match, restart your deployments for the data plane pods that run the old version. The pod name and namespace are listed in each entry as `data plane version: version.ProxyInfo{ID:".", IstioVersion:"1.8.4"}`. ```sh kubectl rollout restart deployment -n ``` In `addon-istio` 1.24 and later, if you have custom gateway deployments, you are also responsible for updating them to pick up the newer `istio/proxyv2` image. The custom gateways show in the list of data plane pods and can be updated with a rollout restart. {: note} ## Updating from an unsupported version of the Istio add-on {: #istio_update} Update your [Istio components](https://cloud.ibm.com/docs/containers?topic=containers-istio-update&format=markdown#istio_minor) to the latest patch version that is supported by IBM Cloud Kubernetes Service. {: shortdesc} `addon-istio` 1.26.8 is unsupported on 10 August 2026. Before that date, update to the latest patch version of `addon-istio` 1.29 that is supported by IBM Cloud Kubernetes Service. `addon-istio` 1.29 is available and supported on IBM Cloud Kubernetes Service versions 1.33, 1.34 and 1.35. To upgrade from 1.26 to 1.29, complete all minor upgrades, from 1.26 to 1.27, from 1.27 to 1.28 and from 1.28 to 1.29, by following [Updating to a minor version of the Istio add-on](#istio_minor).