Before you begin

• 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 the add-on and then 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 the add-on and then 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

Before you begin:

Review the prerequisites that apply to all version updates.

To update the minor version of the Istio add-on:

1. Review the available Istio add-on versions.

   ibmcloud ks addon-versions
   

2. Review the changes that are in each version in the Istio add-on change log.

3. Update the Istio add-on.

   ibmcloud ks cluster addon update istio --version VERSION -c CLUSTER_NAME_OR_ID
   

4. Before you proceed, verify that the update is complete.

   The update process can take up to 20 minutes to complete.

   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.

      ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID
      

   2. Ensure that the control plane component pods in the istio-system namespace have a STATUS of Running.

      kubectl get pods -n istio-system
      

      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
      

5. Update your istioctl client and sidecars.

Updating the istioctl client and sidecars

Whenever the Istio managed add-on is updated, update your istioctl client and the Istio sidecars for your app.

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. 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.

   istioctl version --short=false
   

   Example output

   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}
   ...
   

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.

      curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.29.5 sh -
      

   2. Navigate to the Istio package directory.

      cd istio-1.29.5
      

   3. Linux and macOS users: Add the istioctl client to your PATH system variable.

      export PATH=$PWD/bin:$PATH
      

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:"<pod_name>.<namespace>", IstioVersion:"1.8.4"}.

   kubectl rollout restart deployment <deployment> -n <namespace>
   

   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.

Updating from an unsupported version of the Istio add-on

Update your Istio components to the latest patch version that is supported by IBM Cloud Kubernetes Service.

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.