copyright

lastupdated

keywords

subcollection

years
2014, 2021

2021-04-29

kubernetes, iks, envoy, sidecar, mesh, bookinfo

containers

{:DomainName: data-hd-keyref="APPDomain"} {:DomainName: data-hd-keyref="DomainName"} {:android: data-hd-operatingsystem="android"} {:api: .ph data-hd-interface='api'} {:apikey: data-credential-placeholder='apikey'} {:app_key: data-hd-keyref="app_key"} {:app_name: data-hd-keyref="app_name"} {:app_secret: data-hd-keyref="app_secret"} {:app_url: data-hd-keyref="app_url"} {:authenticated-content: .authenticated-content} {:beta: .beta} {:c#: data-hd-programlang="c#"} {:cli: .ph data-hd-interface='cli'} {:codeblock: .codeblock} {:curl: .ph data-hd-programlang='curl'} {:deprecated: .deprecated} {:dotnet-standard: .ph data-hd-programlang='dotnet-standard'} {:download: .download} {:external: target="_blank" .external} {:faq: data-hd-content-type='faq'} {:fuzzybunny: .ph data-hd-programlang='fuzzybunny'} {:generic: data-hd-operatingsystem="generic"} {:generic: data-hd-programlang="generic"} {:gif: data-image-type='gif'} {:go: .ph data-hd-programlang='go'} {:help: data-hd-content-type='help'} {:hide-dashboard: .hide-dashboard} {:hide-in-docs: .hide-in-docs} {:important: .important} {:ios: data-hd-operatingsystem="ios"} {:java: .ph data-hd-programlang='java'} {:java: data-hd-programlang="java"} {:javascript: .ph data-hd-programlang='javascript'} {:javascript: data-hd-programlang="javascript"} {:new_window: target="_blank"} {:note .note} {:note: .note} {:objectc data-hd-programlang="objectc"} {:org_name: data-hd-keyref="org_name"} {:php: data-hd-programlang="php"} {:pre: .pre} {:preview: .preview} {:python: .ph data-hd-programlang='python'} {:python: data-hd-programlang="python"} {:route: data-hd-keyref="route"} {:row-headers: .row-headers} {:ruby: .ph data-hd-programlang='ruby'} {:ruby: data-hd-programlang="ruby"} {:runtime: architecture="runtime"} {:runtimeIcon: .runtimeIcon} {:runtimeIconList: .runtimeIconList} {:runtimeLink: .runtimeLink} {:runtimeTitle: .runtimeTitle} {:screen: .screen} {:script: data-hd-video='script'} {:service: architecture="service"} {:service_instance_name: data-hd-keyref="service_instance_name"} {:service_name: data-hd-keyref="service_name"} {:shortdesc: .shortdesc} {:space_name: data-hd-keyref="space_name"} {:step: data-tutorial-type='step'} {:subsection: outputclass="subsection"} {:support: data-reuse='support'} {:swift: .ph data-hd-programlang='swift'} {:swift: data-hd-programlang="swift"} {:table: .aria-labeledby="caption"} {:term: .term} {:tip: .tip} {:tooling-url: data-tooling-url-placeholder='tooling-url'} {:troubleshoot: data-hd-content-type='troubleshoot'} {:tsCauses: .tsCauses} {:tsResolve: .tsResolve} {:tsSymptoms: .tsSymptoms} {:tutorial: data-hd-content-type='tutorial'} {:ui: .ph data-hd-interface='ui'} {:unity: .ph data-hd-programlang='unity'} {:url: data-credential-placeholder='url'} {:user_ID: data-hd-keyref="user_ID"} {:vbnet: .ph data-hd-programlang='vb.net'} {:video: .video}

Setting up Istio

{: #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.

Installing the Istio add-on

{: #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 cannot 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 Router Function (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 cannot or do not 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 the ibmcloud ks vlan spanning get --region <region> command.

To use the {{site.data.keyword.cloud_notm}} console:

In your cluster dashboard{: external}, click the name of the cluster where you want to install the Istio add-on.
Click the Add-ons tab.
On the Managed Istio card, click Install.
Click Install again.
On the Managed Istio card, verify that the add-on is listed.

To use the CLI:

Target the CLI to your cluster.
Enable the istio add-on. The default version of the generally available Istio managed add-on, 1.9.3, 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.9.3       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.

Installing the `istioctl` CLI

{: #istioctl}

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

{: pre} 3. Navigate to the Istio package directory.

cd istio-1.9.3

{: pre} 4. Linux and macOS users: Add the istioctl client to your PATH system variable.

export PATH=$PWD/bin:$PATH

{: pre}

Customizing the Istio installation

{: #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 add-on configuration options

Configuration option	Default value	Description
`istio-components-pilot-requests-cpu`	`"500m"`	Configure the CPU request in millicpu for the `istiod` component pod. Use caution when changing this value. Setting this value too low might prevent the control plane from workering properly, and setting this value too high might prevent the `istiod` pod from being scheduled.
`istio-global-logging-level`	`"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 `":,:"`. 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 link icon](../icons/launch-glyph.svg "External link icon")](https://istio.io/latest/docs/ops/diagnostic-tools/component-logging/). To change the log level of the data plane, use the `istioctl proxy-config log --level ` command.
`istio-global-outboundTrafficPolicy-mode`	`"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`	`"true"`	To disable the default Istio egress gateway, set to `"false"`. For example, you might [create a custom egress gateway](/docs/containers?topic=containers-istio-custom-gateway#custom-egress-gateway) instead.
`istio-global-proxy-accessLogFile`	`""`	Envoy proxies print access information to their standard output. 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`	`"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](/docs/containers?topic=containers-istio-custom-gateway#custom-egress-gateway) instead of the default ingress gateway, you can set to `"false"`.
`istio-ingressgateway-zone-1\|2\|3`	`""`	The zones where your worker nodes are deployed. These fields apply your cluster's zones to the `istio-ingressgateway-public-1\|2\|3-enabled` fields. If you installed the Istio add-on at version 1.5 or later, your cluster's zones are already listed. If you updated your Istio add-on from version 1.4 to a later version, you must add your cluster's zones.
`istio-monitoring-telemetry`	`"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`	`"true"`	By default, Istio generates trace spans for 1 out of every 100 requests. To disable trace spans, set to `"false"`.
`istio-pilot-traceSampling`	`"1.0"`	By default, Istio [generates trace spans for 1 out of every 100 requests ![External link icon](../icons/launch-glyph.svg "External link icon")](https://istio.io/latest/docs/tasks/observability/distributed-tracing/overview/#trace-sampling), which is a sampling rate of 1%. To generate more trace spans, increase the percentage value.

For example, your configmap might look like the following:

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 reconciled 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 or istio-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.9.3"}
data plane version: version.ProxyInfo{ID:"rerun-xfs-f8958bb94-j6n89.default", IstioVersion:"1.9.3"}
data plane version: version.ProxyInfo{ID:"test2-5cbc75859c-jh6bx.default", IstioVersion:"1.9.3"}
data plane version: version.ProxyInfo{ID:"minio-test-78b5d4597d-hkpvt.default", IstioVersion:"1.9.3"}
data plane version: version.ProxyInfo{ID:"sb-887f89d7d-7s8ts.default", IstioVersion:"1.9.3"}
data plane version: version.ProxyInfo{ID:"gid-deployment-5dc86db4c4-kdshs.default", IstioVersion:"1.9.3"}
```
{: 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.9.3"}. kubectl delete pod <pod_name> -n <namespace> {: pre}

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

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

Updating the Istio add-on

{: #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}

Updating the minor version of the Istio add-on

{: #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 most recent minor version of Istio that is supported by {{site.data.keyword.containerlong_notm}}, such as from version 1.7 to 1.8, you must manually update your add-on. {: shortdesc}

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 cannot 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 included in each version in the Istio add-on changelog.
Istio version 1.8: If you created a custom IstioOperator resource, remove the revision field from the resource before you update your add-on to version 1.8 so that the custom gateways use version 1.8 of istiod.
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.

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> {: pre}

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

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}

Istio version 1.8: If you created a custom IstioOperator resource, update the tag for any custom gateways to 1.8.
Update your istioctl client and sidecars.

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 {{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: 1.8.4
cluster-local-gateway version:
citadel version: 1.9.3
egressgateway version: 1.9.3
egressgateway version: 1.9.3
galley version: 1.9.3
ingressgateway version: 1.9.3
ingressgateway version: 1.9.3
pilot version: 1.9.3
policy version: 1.9.3
sidecar-injector version: 1.8.4
telemetry version: 1.9.3
data plane version: version.ProxyInfo{ID:"cluster-local-gateway-859958cb-fjv2d.istio-system", IstioVersion:"1.8.4"}
data plane version: version.ProxyInfo{ID:"istio-egressgateway-7966998fd7-vxhm6.istio-system", IstioVersion:"1.8.4"}
data plane version: version.ProxyInfo{ID:"webserver-6c6db9ffbc-xzjzl.default", IstioVersion:"1.8.4"}
...

{: screen}

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 do not match:
1. Download the istioctl client of the same version as the control plane components.
```
curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.9.3 sh -
```
{: pre} 2. Navigate to the Istio package directory.
```
cd istio-1.9.3
```
{: pre} 3. Linux and macOS users: Add the istioctl client to your PATH system variable.
```
export PATH=$PWD/bin:$PATH
```
{: pre}
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 do not 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>
```
{: pre}

Uninstalling Istio

{: #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}

Managing resources before uninstallation

{: #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. Example command:
```
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 do not 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}

Uninstalling the Istio add-on from the console

{: #istio_uninstall_ui}

In your cluster dashboard{: external}, click the name of the cluster where you want to remove the Istio add-on.
Click the Add-ons tab.
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.

### Uninstalling managed Istio add-ons from the CLI {: #istio_uninstall_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}

Uninstalling other Istio installations in your cluster

{: #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:
1. Uninstall the Istio Helm deployment.
```
helm del istio --purge
```
{: pre}
1. If you used Helm 2.9 or earlier, delete the extra job resource.
```
kubectl -n istio-system delete job --all
```
{: pre}
1. 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{: external}.

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.9.3
```
{: pre}
1. Delete all BookInfo services, pods, and deployments in the cluster.
```
samples/bookinfo/platform/kube/cleanup.sh
```
{: pre}
1. 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

{: #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}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cs_istio.md

cs_istio.md

Setting up Istio

Installing the Istio add-on

Installing the `istioctl` CLI

Customizing the Istio installation

Updating the Istio add-on

Updating the minor version of the Istio add-on

Updating the `istioctl` client and sidecars

Uninstalling Istio

Managing resources before uninstallation

Uninstalling the Istio add-on from the console

Uninstalling other Istio installations in your cluster

Troubleshooting

Files

cs_istio.md

Latest commit

History

cs_istio.md

File metadata and controls

Setting up Istio

Installing the Istio add-on

Installing the istioctl CLI

Customizing the Istio installation

Updating the Istio add-on

Updating the minor version of the Istio add-on

Updating the istioctl client and sidecars

Uninstalling Istio

Managing resources before uninstallation

Uninstalling the Istio add-on from the console

Uninstalling other Istio installations in your cluster

Troubleshooting

Installing the `istioctl` CLI

Updating the `istioctl` client and sidecars