Setting up Istio

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.

Updating the Istio add-on

Update your Istio add-on, which is tested by IBM Cloud and approved for the use in IBM Cloud Kubernetes Service.

Do not use istioctl to update the version of Istio that is installed by the managed add-on. Only use the following steps to update your managed Istio add-on, which includes an update of the Istio version.

To update from unsupported versions of the Istio add-on, update your Istio components to the latest patch version that is supported by IBM Cloud Kubernetes Service.

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 in-line 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-egressgateway-public-1-enabled

   Default value: "true"

   To disable the default Istio egress gateway, set to "false". For example, you might create a custom egress gateway instead.

   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-ingressgateway-public-1|2|3-enabled

   Default value: "true" in zone 1 only.

   To make your apps more highly available, set to "true" for each zone where you want a public istio-ingressgateway load balancer to be created. To use custom ingress gateways instead of the default ingress gateway, you can set to "false".

   istio-ingressgateway-zone-1|2|3

   Default value: "<zone>"

   The zones where your worker nodes are deployed, which are automatically populated when you install the add-on and whenever you apply an Istio patch update. These fields apply your cluster's zones to the istio-ingressgateway-public-1|2|3-enabled fields. Note that if the zones that are listed in this setting are out of sync with your cluster zones, you can restart the auto population job by running kubectl delete pod -n ibm-system -l addon.cleanup=istio and kubectl delete job -n ibm-system -l addon.cleanup=istio.

   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.23.1"}
      data plane version: version.ProxyInfo{ID:"rerun-xfs-f8958bb94-j6n89.default", IstioVersion:"1.23.1"}
      data plane version: version.ProxyInfo{ID:"test2-5cbc75859c-jh6bx.default", IstioVersion:"1.23.1"}
      data plane version: version.ProxyInfo{ID:"minio-test-78b5d4597d-hkpvt.default", IstioVersion:"1.23.1"}
      data plane version: version.ProxyInfo{ID:"sb-887f89d7d-7s8ts.default", IstioVersion:"1.23.1"}
      data plane version: version.ProxyInfo{ID:"gid-deployment-5dc86db4c4-kdshs.default", IstioVersion:"1.23.1"}
      

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

      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?

Check the logs for the addon-istio-operator (Istio version 1.10 or later) or managed-istio-operator (Istio version 1.9 or earlier) 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.

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

Uninstalling other Istio installations in your 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 in the cluster. To check whether Istio is already in a cluster, run kubectl get namespaces and look for the istio-system namespace in the output.

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

  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.

Troubleshooting the Istio add-on

To resolve some common issues that you might encounter when you use the managed Istio add-on, see Troubleshooting managed add-ons.

Step 2: Scale down the Istio operator

Scale down the Istio operator deployment.

Run the following command:

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

Step 3: Saving resources

Save any resources that you created or modified in the istio-system namespace and all Kubernetes resources that were automatically generated by custom resource definitions (CRDs).

1. Save the managed-istio-custom ConfigMap to troubleshoot a problem or to reinstall the add-on later.

   kubectl get cm -n ibm-operators managed-istio-custom -o yaml > Customizations.yaml
   

2. Save all IstioOperator CRs (IOPs).

   • List the IOP resources:

     kubectl get iop -A
     

   • For each IOP resource listed, remove the finalizer. Example using the managed-istio IOP:

     kubectl patch -n ibm-operators istiooperator/managed-istio --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]'
     

   • For each IOP resource listed, save each to a file:

     kubectl get iop -n <IOP_namespace> <IOP_name> -o yaml > <IOP_name>.yaml
     

3. Wait 10 minutes before continuing to the next step.

Step 4: Changing the installer of the IOPs

Delete all Istio operator (IOP) resources, such as for a custom ingress gateway.

1. Make sure your istioctl cli tool is at the desired patch version

   istioctl version
   

2. For each IOP file that you saved in the previous step, run the upgrade command.

   istioctl upgrade -f <filename>.yaml
   

Step 5: Removing the Istio operator and IOPs

Delete the Istio operator deployment, service account, cluster role binding, cluster role, and all IOPs.

1. Run the following commands to delete the istio operator deployment:

   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
   

2. Delete the IOPs.

   • List the IOP resources:

     kubectl get iop -A
     

   • For each IOP resource listed, delete it:

     kubectl delete IstioOperator <resource_name> -n <namespace>
     

Step 6: Removing the ConfigMap

Because the ConfigMap was saved earlier, it can be removed.

Remove the managed-istio-custom ConfigMap.

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

The removal of the add-on is complete and you can continue to use and upgrade the community Istio as needed.