Setting up the Istio managed add-on

Removing other Istio installations from a cluster

If you previously installed Istio in the cluster by using the IBM Helm chart or through another method, clean up that Istio installation before you enable the managed Istio add-on.

Before you begin: Verify that Istio is already installed in the cluster. Run kubectl get namespaces and look for the istio-system namespace in the output.

To remove other Istio installations:

• If you installed Istio by using the IBM Cloud Istio Helm chart,

  1. Uninstall the Istio Helm deployment.

     helm del istio --purge
     

  2. If you used Helm 2.9 or earlier, delete the extra job resource.

     kubectl -n istio-system delete job --all
     

  3. The uninstallation process can take up to 10 minutes. Before you install the Istio managed add-on in the cluster, run kubectl get namespaces and verify that the istio-system namespace is removed.

• If you installed Istio manually or used the Istio community Helm chart, see the Istio uninstall documentation.

• If you previously installed BookInfo in the cluster, clean up those resources.

  1. Change the directory to the Istio file location.

     cd <filepath>/istio-1.24.6
     

  2. Delete all BookInfo services, pods, and deployments in the cluster.

     samples/bookinfo/platform/kube/cleanup.sh
     

  3. The uninstallation process can take up to 10 minutes. Before you install the Istio managed add-on in the cluster, run kubectl get namespaces and verify that the istio-system namespace is removed.

Installing the Istio add-on

Instead of the community Istio, you can install the managed Istio add-on.

Before you begin

• Ensure that you have the Writer or Manager IBM Cloud IAM service access role for IBM Cloud Kubernetes Service.

• Create a standard Kubernetes cluster with at least 3 worker nodes that each have 4 cores and 16 GB memory (b3c.4x16) or more.

• You can't run community Istio concurrently with the managed Istio add-on in your cluster. If you use an existing cluster and you previously installed Istio in the cluster by using the IBM Helm chart or through another method, clean up that Istio installation.

• Classic multizone clusters: Ensure that you enable a Virtual Routing and Forwarding (VRF) for your IBM Cloud infrastructure account. To enable VRF, see Enabling VRF. To check whether a VRF is already enabled, use the ibmcloud account show command. If you can't or don't want to enable VRF, enable VLAN spanning. To perform this action, you need the Manage Network VLAN Spanning infrastructure permission, or you can request the account owner to enable it. To check whether VLAN spanning is already enabled, use the ibmcloud ks vlan spanning get --region <region> command.

Customizing the Istio installation

You can customize a set of Istio configuration options by editing the managed-istio-custom ConfigMap resource. These settings include extra control over monitoring, logging, and networking in your control plane and service mesh.

1. Describe the managed-istio-custom ConfigMap resource to review its contents and the inline documentation.

   kubectl describe cm managed-istio-custom -n ibm-operators
   

2. Edit the managed-istio-custom ConfigMap resource.

   kubectl edit cm managed-istio-custom -n ibm-operators
   

3. In the data section, add the <key>: "<value>" pair of one or more of the following configuration options.

   istio-components-pilot-requests-cpu

   Default value: "500m"

   Configure the CPU request in milli CPU for the istiod component pod. Use caution when changing this value. Setting this value too low might prevent the control plane from working properly, and setting this value too high might prevent the istiod pod from being scheduled.

   istio-global-logging-level

   Default value: "default:info"

   Define the scope of logs and the level of log messages for control plane components. A scope represents a functional area within a control plane component and each scope supports specific log information levels. The default logging scope, which is for non-categorized log messages, is applied to all components in the control plane at the basic info level.

   To specify log levels for individual component scopes, enter a comma-separated list of scopes and levels, such as "<scope>:<level>,<scope>:<level>". For a list of the scopes for each control plane component and the information level of log messages, see the Istio component logging documentation. To change the log level of the data plane, use the istioctl proxy-config log <pod> --level <level> command.

   istio-global-outboundTrafficPolicy-mode

   Default value: "ALLOW_ANY"

   By default, all outbound traffic from the service mesh is permitted. To block outbound traffic from the service mesh to any host that is not defined in the service registry or that does not have a ServiceEntry within the service mesh, set to REGISTRY_ONLY.

   istio-global-proxy-accessLogFile

   Default value: ""

   Envoy proxies print access information to their standard output. These logs are helpful when you debug ingress or egress issues. To view this access information when running kubectl logs commands for the Envoy containers, set to "/dev/stdout".

   istio-monitoring-telemetry

   Default value: "true"

   By default, telemetry metrics and Prometheus support is enabled. To remove any performance issues associated with telemetry metrics and disable all monitoring, set to "false".

   istio-meshConfig-enableTracing

   Default value: "true"

   By default, Istio generates trace spans for 1 out of every 100 requests. To disable trace spans, set to "false".

   istio-pilot-traceSampling

   Default value: "1.0"

   By default, Istio generates trace spans for 1 out of every 100 requests, which is a sampling rate of 1%. To generate more trace spans, increase the percentage value.

   istio-components-pilot-hpa-maxReplicas

   Default value: "5"

   By default, Istio sets the default horizontal pod autoscaler (HPA) max pods for istiod to 5. Do not increase this value unless you have a large service mesh where istiod needs increased resources to update the configurations.

   For example, your ConfigMap might look like the following example.

   apiVersion: v1
   data:
     istio-ingressgateway-zone-1: dal10
     <key: value> # such as istio-egressgateway-public-1-enabled: "false"
   kind: ConfigMap
   metadata:
     name: managed-istio-custom
     namespace: ibm-operators
   

   Don't see an option from this table in your ConfigMap? Because your ConfigMap contains user-defined values, the ConfigMap is not updated with any options that are released over time. Instead, you can back up a copy of your ConfigMap and delete the ConfigMap from your cluster. After about 5 minutes, a default ConfigMap that contains the new options is created in your cluster. Then, you can copy your previously configured settings from your backup to this default ConfigMap, configure any new settings, and apply the changes.

4. Save and close the configuration file.

5. If you changed the istio-global-logging-level or istio-global-proxy-accessLogFile settings, you must restart your data plane pods to apply the changes to them.

   1. Get the list of all data plane pods that are not in the istio-system namespace.

      istioctl version --short=false | grep "data plane version" | grep -v istio-system
      

      Example output

      data plane version: version.ProxyInfo{ID:"test-6f86fc4677-vsbsf.default", IstioVersion:"1.24.6"}
      data plane version: version.ProxyInfo{ID:"rerun-xfs-f8958bb94-j6n89.default", IstioVersion:"1.24.6"}
      data plane version: version.ProxyInfo{ID:"test2-5cbc75859c-jh6bx.default", IstioVersion:"1.24.6"}
      data plane version: version.ProxyInfo{ID:"minio-test-78b5d4597d-hkpvt.default", IstioVersion:"1.24.6"}
      data plane version: version.ProxyInfo{ID:"sb-887f89d7d-7s8ts.default", IstioVersion:"1.24.6"}
      data plane version: version.ProxyInfo{ID:"gid-deployment-5dc86db4c4-kdshs.default", IstioVersion:"1.24.6"}
      

   2. Restart each pod by deleting it. In the output of the previous step, the pod name and namespace are listed in each entry as data plane version: version.ProxyInfo{ID:"<pod_name>.<namespace>", IstioVersion:"1.24.6"}.

      kubectl delete pod <pod_name> -n <namespace>
      

Want to change a ConfigMap setting?

If you want to change a setting that you added to the ConfigMap, you can use a patch script. For example, if you added the istio-global-proxy-accessLogFile: "/dev/stdout" setting and later want to change it back to "", you can run kubectl patch cm managed-istio-custom -n ibm-operators --type='json' -p='[{"op": "add", "path": "/data/istio-global-proxy-accessLogFile", "value":""}]'.

Need to debug your customization setup in 1.24 or later?

Check the helm value.yaml and the helm results logs in the managed-istio-istiod-control-plane-values configmap in the ibm-operators namespace. The value.yaml will show you whether your change was added. The helm results will show you if there were any syntax errors.

kubectl get cm -n ibm-operators managed-istio-istiod-control-plane-values -o json | jq -r .data.\"values.yaml\"
kubectl get cm -n ibm-operators managed-istio-istiod-control-plane-values -o json | jq -r .data.\"values.yaml.helm.result\"

Thu, 23 Oct 2025 19:58:48 GMT HELM_SUCCESS: Release "istiod" has been upgraded. Happy Helming!
NAME: istiod
LAST DEPLOYED: Thu Oct 23 19:58:42 2025
NAMESPACE: istio-system
STATUS: deployed
REVISION: 275
TEST SUITE: None
NOTES:
"istiod" successfully installed!

Need to debug your customization setup in 1.23?

Check the logs for the addon-istio-operator (Istio version 1.10 to 1.23) pod by running kubectl logs -n ibm-operators -l name=managed-istio-operator. The Istio operator validates and reconciles any custom Istio changes that you make.

If you disable the Istio add-on, the managed-istio-custom ConfigMap is not removed during uninstallation. When you re-enable the Istio add-on, your customized ConfigMap is applied during installation. If you don't want to re-use your custom settings in a later installation of Istio, you must delete the ConfigMap after you disable the Istio add-on by running kubectl delete cm -n ibm-operators managed-istio-custom. When you re-enable the Istio add-on, the default ConfigMap is applied during installation.

Migrating from the Istio add-on to community Istio

If you are using the managed Istio add-on versions 1.21 to 1.23, you can migrate to a later version of the community Istio instead.

Before you begin: If you no longer need Istio, you can uninstall the add-on without installing the community Istio instead of completing these step.

kubectl scale deployment -n ibm-operators addon-istio-operator --replicas=0

kubectl delete cm -n ibm-operators managed-istio-custom

Uninstalling the Istio add-on

If you're finished working with Istio, you can clean up the Istio resources in your cluster and uninstall the Istio add-ons.

kubectl delete deployment -n ibm-operators addon-istio-operator --ignore-not-found=true
kubectl delete serviceaccount -n ibm-operators addon-istio-operator --ignore-not-found=true
kubectl delete clusterrolebinding addon-istio-operator --ignore-not-found=true
kubectl delete clusterrole addon-istio-operator --ignore-not-found=true