copyright | lastupdated | keywords | subcollection | ||
---|---|---|---|---|---|
|
2024-02-05 |
kubernetes, envoy, sidecar, mesh, bookinfo, istio |
containers |
{{site.data.keyword.attribute-definition-list}}
{: #istio}
Istio on {{site.data.keyword.containerlong}} provides a seamless installation of Istio, automatic updates and lifecycle management of Istio control plane components, and integration with platform logging and monitoring tools. {: shortdesc}
With one click, you can get all Istio core components up and running. Istio on {{site.data.keyword.containerlong_notm}} is offered as a managed add-on so that {{site.data.keyword.cloud_notm}} automatically keeps all your Istio components up-to-date.
{: #istio_install}
In Kubernetes clusters, you can install the generally available managed Istio add-on. {: shortdesc}
Before you begin
- Ensure that you have the Writer or Manager {{site.data.keyword.cloud_notm}} IAM service access role for {{site.data.keyword.containerlong_notm}}.
- 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 Network > 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 theibmcloud ks vlan spanning get --region <region>
command.
{: #istio_install-console} {: ui}
-
In your cluster dashboard{: external}, click the name of the cluster where you want to install the Istio add-on.
-
Navigate to the Add-ons section.
-
On the Managed Istio card, click Install.
-
Click Install again.
-
On the Managed Istio card, verify that the add-on is listed.
{: #istio_install-cli} {: cli}
-
Review the supported Istio versions.
ibmcloud ks addon-versions --addon istio
{: pre}
-
Enable the
istio
add-on. The default version of the generally available Istio managed add-on, 1.20.0, is installed.ibmcloud ks cluster addon enable istio --cluster <cluster_name_or_ID>
{: pre}
-
Verify that the managed Istio add-on has a status of
Addon Ready
.ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
{: pre}
Example output
NAME Version Health State Health Status istio 1.20.0 normal Addon Ready
{: screen}
-
You can also check out the individual components of the add-on to ensure that the Istio services and their corresponding pods are deployed.
kubectl get svc -n istio-system
{: pre}
kubectl get pods -n istio-system
{: pre}
-
Next, you can include your apps in the Istio service mesh.
{: #istioctl} {: cli}
Install the istioctl
CLI client. For more information, see the istioctl
command reference{: external}.
-
Check the version of Istio that you installed.
istioctl version
{: pre}
-
Download the version of
istioctl
that matches your cluster's Istio version.curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.20.0 sh -
{: pre}
-
Navigate to the Istio package directory.
cd istio-1.20.0
{: pre}
-
Linux and macOS users: Add the
istioctl
client to yourPATH
system variable.export PATH=$PWD/bin:$PATH
{: pre}
{: #customize}
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.
{: shortdesc}
-
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
{: pre}
-
Edit the
managed-istio-custom
ConfigMap resource.kubectl edit cm managed-istio-custom -n ibm-operators
{: pre}
-
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 inmilli
CPU for theistiod
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 theistiod
pod from being scheduled. {: important}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. Thedefault
logging scope, which is for non-categorized log messages, is applied to all components in the control plane at the basicinfo
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{: external}. To change the log level of the data plane, use theistioctl proxy-config log <pod> --level <level>
command. {: tip}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 aServiceEntry
within the service mesh, set toREGISTRY_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 runningkubectl 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 publicistio-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 theistio-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 runningkubectl delete pod -n ibm-system -l addon.cleanup=istio
andkubectl 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{: external}, 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
{: screen}
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. {: tip}
-
Save and close the configuration file.
-
If you changed the
istio-global-logging-level
oristio-global-proxy-accessLogFile
settings, you must restart your data plane pods to apply the changes to them.-
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
{: pre}
Example output
data plane version: version.ProxyInfo{ID:"test-6f86fc4677-vsbsf.default", IstioVersion:"1.20.0"} data plane version: version.ProxyInfo{ID:"rerun-xfs-f8958bb94-j6n89.default", IstioVersion:"1.20.0"} data plane version: version.ProxyInfo{ID:"test2-5cbc75859c-jh6bx.default", IstioVersion:"1.20.0"} data plane version: version.ProxyInfo{ID:"minio-test-78b5d4597d-hkpvt.default", IstioVersion:"1.20.0"} data plane version: version.ProxyInfo{ID:"sb-887f89d7d-7s8ts.default", IstioVersion:"1.20.0"} data plane version: version.ProxyInfo{ID:"gid-deployment-5dc86db4c4-kdshs.default", IstioVersion:"1.20.0"}
{: screen}
-
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.20.0"}
.kubectl delete pod <pod_name> -n <namespace>
{: pre}
-
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.
{: tip}
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.
{: note}
{: #istio_update}
Update your Istio add-on to the latest version, which is tested by {{site.data.keyword.cloud_notm}} and approved for the use in {{site.data.keyword.containerlong_notm}}. {: shortdesc}
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.
{: important}
Version 1.18 will be unsupported on 21 February 2024. Follow the steps to update your Istio components to the latest patch version of Istio 1.18 that is supported by {{site.data.keyword.containerlong_notm}}. {: important}
Version 1.17 is unsupported as of 6 December 2023. Follow the steps to update your Istio components to the latest patch version of Istio 1.18 that is supported by {{site.data.keyword.containerlong_notm}}. {: important}
{: #istio_minor}
{{site.data.keyword.cloud_notm}} keeps all your Istio components up-to-date by automatically rolling out patch updates to the most recent version of Istio that is supported by {{site.data.keyword.containerlong_notm}}. To update your Istio components to the next minor version of Istio that is supported by {{site.data.keyword.containerlong_notm}}, such as from version 1.9 to 1.10, you must manually update your add-on. You can only manually update Istio one version at a time. {: shortdesc}
You can only manually update the Istio add-on one version at a time. If you want to update the Istio add-on by two or more versions, you can repeat the manual update process or you can uninstall and remove the add-on and then reinstall it with a later version. {: note}
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.
You can't revert your managed Istio add-on to a previous version. If you want to revert to an earlier minor version, you must uninstall your add-on and then reinstall the add-on by specifying the earlier version. {: important}
-
Review the current version of your Istio add-on.
kubectl get iop managed-istio -n ibm-operators -o jsonpath='{.metadata.annotations.version}'
{: pre}
-
Review the available Istio add-on versions.
ibmcloud ks addon-versions
{: pre}
-
Review the changes that are in each version in the Istio add-on change log.
-
If you are upgrading from version 1.11 to version 1.12 and your Istio components were provisioned at version 1.10 or earlier:
-
Run the command to get the details of your mutating webhook configurations.
kubectl get mutatingwebhookconfigurations
{: pre}
Example output.
NAME WEBHOOKS AGE istio-sidecar-injector 5 32m
{: screen}
-
In the output, find the
istio-sidecar-injector
and review the WEBHOOKS column. If there are 5 or more webhooks, run the following command to delete the additional webhooks.kubectl delete mutatingwebhookconfigurations istio-sidecar-injector && kubectl rollout restart deploy addon-istio-operator -n ibm-operators
{: pre}
Example output.
mutatingwebhookconfiguration.admissionregistration.k8s.io "istio-sidecar-injector" deleted
{: screen}
-
Check that the additional webhooks were deleted. Get the details of your mutating webhook configurations and verify that there are 4
istio-sidecar-injector
webhooks.kubectl get mutatingwebhookconfigurations
{: pre}
Example output.
NAME WEBHOOKS AGE istio-sidecar-injector 4 60s
{: screen}
-
Run the command to get the details of your validating webhook configuration.
kubectl get validatingwebhookconfigurations
{: pre}
Example output.
NAME WEBHOOKS AGE istio-validator-istio-system 2 66s istiod-istio-system 1 31m
{: screen}
-
Review the output. If the
istiod-istio-system
webhook is listed, run the following command to delete it.kubectl delete ValidatingWebhookConfiguration istiod-istio-system
{: pre}
Example output.
validatingwebhookconfiguration.admissionregistration.k8s.io "istiod-istio-system" deleted
{: screen}
-
Verify that the
istiod-istio-system
webhook is no longer listed.kubectl get validatingwebhookconfigurations
{: pre}
Example output.
NAME WEBHOOKS AGE istio-validator-istio-system 2 2m
{: screen}
-
-
Update the Istio add-on.
ibmcloud ks cluster addon update istio --version <version> -c <cluster_name_or_ID>
{: pre}
-
Before you proceed, verify that the update is complete.
The update process can take up to 20 minutes to complete. {: note}
-
Ensure that the Istio add-on's Health State is
normal
and the Health Status isAddon Ready
. If the state isupdating
, the update is not yet complete.ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
{: pre}
-
Ensure that the control plane component pods in the
istio-system
namespace have a STATUS ofRunning
.kubectl get pods -n istio-system
{: pre}
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}
-
{: #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 {{site.data.keyword.containerlong_notm}}, 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.
-
Get the version of your
istioctl
client and the Istio add-on control plane components.istioctl version --short=false
{: pre}
Example output
client version: version.BuildInfo{Version:"1.11.2"} pilot version: version.BuildInfo{Version:1.20.0} pilot version: version.BuildInfo{Version:1.20.0} data plane version: version.ProxyInfo{ID:"istio-egressgateway-77bf75c5c-vp97p.istio-system", IstioVersion:1.20.0} data plane version: version.ProxyInfo{ID:"istio-egressgateway-77bf75c5c-qkhgm.istio-system", IstioVersion:1.20.0} data plane version: version.ProxyInfo{ID:"istio-ingressgateway-6dcb67b64d-dffhq.istio-system", IstioVersion:1.20.0} data plane version: version.ProxyInfo{ID:"httpbin-74fb669cc6-svc8x.default", IstioVersion:1.20.0} data plane version: version.ProxyInfo{ID:"istio-ingressgateway-6dcb67b64d-cs9r9.istio-system", IstioVersion:1.20.0} ...
{: screen}
-
In the output, compare the
client version
(istioctl
) to the version of the Istio control plane components, such as thepilot version
. If theclient version
and control plane component versions don't match:-
Download the
istioctl
client of the same version as the control plane components.curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.20.0 sh -
{: pre}
-
Navigate to the Istio package directory.
cd istio-1.20.0
{: pre}
-
Linux and macOS users: Add the
istioctl
client to yourPATH
system variable.export PATH=$PWD/bin:$PATH
{: pre}
-
-
In the output of step 1, compare the
pilot version
to thedata plane version
for each data plane pod.- If the
pilot version
and thedata plane version
match, no further updates are required. - If the
pilot version
and thedata 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 asdata plane version: version.ProxyInfo{ID:"<pod_name>.<namespace>", IstioVersion:"1.8.4"}
.
kubectl rollout restart deployment <deployment> -n <namespace>
{: pre}
- If the
{: #istio_uninstall}
If you're finished working with Istio, you can clean up the Istio resources in your cluster by uninstalling the Istio add-ons. {: shortdesc}
{: #uninstall_resources}
Review the following optional steps for saving or deleting custom Istio resources before you uninstall Istio. {: shortdesc}
-
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) are removed. If you want to keep these resources, save them before you uninstall the Istio add-on.-
Save any resources, such as configuration files for any services or apps, that you created or modified in the
istio-system
namespace.kubectl get pod <pod_name> -o yaml -n istio-system
{: pre}
-
Get the CRDs in
istio-system
.kubectl get crd -n istio-system
{: pre}
-
Save the Kubernetes resources that were automatically generated by these CRDs to a YAML file on your local machine.
-
-
The
managed-istio-custom
ConfigMap is not removed during uninstallation. If you later re-enable the Istio add-on, any customized settings that you made to the ConfigMap are 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.kubectl delete cm -n ibm-operators managed-istio-custom
{: pre}
-
Delete any custom Istio operator (IOP) resources that you created, such as for a custom ingress gateway. When you run this command, the Istio operator automatically removes any resources that the IOP resource created, such as deployments or services.
kubectl delete IstioOperator <resource_name> -n <namespace>
{: pre}
{: #istio_uninstall_addon}
Uninstall the add-on from the console or CLI. {: shortdesc}
{: #istio_uninstall_ui} {: ui}
-
In your cluster dashboard{: external}, click the name of the cluster where you want to remove the Istio add-on.
-
Navigate to the Add-ons section.
-
On the Managed Istio card, click the Action menu icon.
-
Click Uninstall. The managed Istio add-on is disabled in this cluster and all Istio resources in this cluster are removed.
-
On the Managed Istio card, verify that the add-on you uninstalled is no longer listed.
{: #istio_uninstall_cli} {: cli}
If you did not install the deprecated istio-sample-bookinfo
and istio-extras
add-ons, skip steps 1 and 2.
{: tip}
-
Disable the
istio-sample-bookinfo
add-on.ibmcloud ks cluster addon disable istio-sample-bookinfo --cluster <cluster_name_or_ID>
{: pre}
-
Disable the
istio-extras
add-on.ibmcloud ks cluster addon disable istio-extras --cluster <cluster_name_or_ID>
{: pre}
-
Disable the
istio
add-on.ibmcloud ks cluster addon disable istio --cluster <cluster_name_or_ID> -f
{: pre}
-
Verify that all managed Istio add-ons are disabled in this cluster. No Istio add-ons are returned in the output.
ibmcloud ks cluster addon ls --cluster <cluster_name_or_ID>
{: pre}
{: #istio_uninstall_operator}
After the add-on is completely uninstalled, you can remove the Istio operator. {: shortdesc}
{: #istio_uninstall_operator-110}
Delete the Istio operator deployment, service account, cluster role binding, and cluster role.
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
{: pre}
{: #istio_uninstall_operator-19}
Delete the Istio operator pod's CSV.
kubectl delete clusterserviceversion -n ibm-operators -l addon.name=istio --ignore-not-found=true
{: pre}
{: #istio_uninstall_other}
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.
{: shortdesc}
-
If you installed Istio by using the {{site.data.keyword.cloud_notm}} Istio Helm chart,
-
Uninstall the Istio Helm deployment.
helm del istio --purge
{: pre}
-
If you used Helm 2.9 or earlier, delete the extra job resource.
kubectl -n istio-system delete job --all
{: pre}
-
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 theistio-system
namespace is removed.
-
-
If you installed Istio manually or used the Istio community Helm chart, see the Istio uninstall documentation{: external}.
-
If you previously installed BookInfo in the cluster, clean up those resources.
-
Change the directory to the Istio file location.
cd <filepath>/istio-1.20.0
{: pre}
-
Delete all BookInfo services, pods, and deployments in the cluster.
samples/bookinfo/platform/kube/cleanup.sh
{: pre}
-
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 theistio-system
namespace is removed.
-
{: #istio-ts}
To resolve some common issues that you might encounter when you use the managed Istio add-on, see Troubleshooting managed add-ons. {: shortdesc}