Kiali

Table of Contents

1. Installing Kiali
2. Uninstall
3. The Kiali UI
- 3.1. Detail view of a single service
4. Additional Notes

Kiali works with Istio versions 1.0.5+ and 1.1.
Kiali will support the latest Istio version (1.1 at the moment) and the development is closely following the development of Istio. Older Istio versions like 1.0.x may continue to work, but will no longer be actively supported.

For several commands listed on this page, the OpenShift CLI command oc is used to interact with the cluster environment. If you are on Kubernetes, simply replace oc with kubectl unless otherwise noted.

1. Installing Kiali

1.1. Preparation

Kiali can be installed in an OpenShift or Kubernetes cluster environment. Before you begin, you may need to prepare your OpenShift or Kubernetes environment.

1.1.1. OpenShift Preparation

If you are installing on OpenShift, you need to grant the cluster-admin role to the user that is installing Istio and Kiali. If OpenShift is installed locally on the machine you are using, the following command should log you in as user system:admin which has this cluster-admin role:

oc login -u system:admin

1.1.2. Kubernetes Preparation

If you are not installing on OpenShift but instead installing on Kubernetes, there are no additional preparation steps required unless you are installing on Minikube. When installing on Minikube, ensure that you enable the Ingress add-on by executing the following command:

minikube addons enable ingress

When Kiali is installed in Minikube, this Ingress add-on will let you access the Kiali UI at the URL https://[minikube-ip]/kiali/console where [minikube-ip] is what is reported when you run the command: minikube ip.

1.2. Install Istio

Make sure your cluster environment has Istio installed. Because you are following these instructions to install the latest version of Kiali, you should not install the Kiali version that is bundled with Istio (that is, do not use the Helm setting kiali.enabled=true when installing Istio).

For details on how to install Istio, see the Istio Setup docs.

1.3. Kiali Operator

Now install the latest release of Kiali using the Kiali Operator.

1.3.1. What is the Kiali Operator?

First, a quick introduction of what the Kiali Operator actually is.

The Kiali Operator is an implementation of a Kubernetes Operator. It provides a method of packaging, deploying, and managing Kiali.

The Kiali Operator runs inside the kiali-operator namespace and listens for the creation of a Kiali CR (custom resource) object. When it sees one created, it will install Kiali using the settings it finds in the CR object. To see all the different settings you can configure in a Kiali CR, see this fully documented example Kiali CR yaml file. A minimal Kiali CR that uses all the defaults looks like this:

apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
  name: kiali

1.3.2. Installing the Kiali Operator

In the instructions below, you will install the Kiali Operator using the Kiali Operator install script. That install script has the option of also immediately installing a simple Kiali CR for you so you do not have to, thus making it easy to get started with Kiali by running a single command (this is, in fact, the install script’s default behavior). If, however, you wish to install Kiali specifically configured with custom settings of your choosing, you can tell the script to skip the installation of a Kiali CR and just simply install the Operator. In this case, you would be responsible for writing the Kiali CR yaml file and creating it in your cluster, thus allowing you to tell the Operator to install Kiali with the settings you want.

The Kiali Operator install script can be configured by setting environment variables when running it. For example, if you do not want the install script to install a Kiali CR (and thus avoid having the Kiali Operator install Kiali itself, as explained above), set the OPERATOR_INSTALL_KIALI environment variable to "false" and then run the script. Read the comments at the top of the Kiali Operator install script for details on what custom configuration settings are available to you.

The install script requires envsubst installed and in your PATH; you can get it via the GNU gettext package.

To install the Kiali Operator (and, by default, the Kiali CR), run the install script via this command:

bash <(curl -L https://git.io/getLatestKialiOperator)

You will be prompted for the authentication strategy you want to use.

Choose login if you want to secure Kiali using a username and passphrase.
Choose anonymous to remove authentication from Kiali and allow full access to Kiali without requiring any credentials.
Choose openshift to use the OpenShift OAuth login which controls access based on the individual’s RBAC roles in OpenShift (this is only a feature available when deployed on OpenShift - the Operator will fail to install Kiali successfully and will log an appropriate error message if you choose this when installing on Kubernetes).

If the authentication strategy of "login" is selected, a secret containing Kiali login credentials is required to be deployed along with Kiali. In this case, the install script will prompt you to enter a username and passphrase for the credentials that you want users to enter in order to log in successfully to Kiali. The install script will store those credentials in a secret that is deployed in the same namespace where Kiali is installed.

See the Login Options section below for more information.

If you told the install script to not create a Kiali CR (and thus not have Kiali installed yet) via the OPERATOR_INSTALL_KIALI=false environment variable, you are responsible for creating this secret if you wish to install Kiali with the authentication strategy of "login". A secret is not required if your authentication strategy is not "login". The following command is a simple way to create a secret for Kiali whose username is "admin" and passphrase is "admin":

oc create secret generic kiali -n istio-system --from-literal "username=admin" --from-literal "passphrase=admin"

Once the Kiali Operator has installed Kiali and the Kiali pod has successfully started, you can access the Kiali UI.

If on OpenShift, you can easily find the URL to access Kiali by going to the OpenShift Console and navigating to the istio-system project’s Overview page:

Figure 1. OpenShift console

In this case, the Kiali URL is http://kiali-istio-system.192.168.64.13.nip.io. In your case this will be a different IP.

You can also use the oc command to determine the base URL:

oc get route -n istio-system -l app=kiali

If on Kubernetes, access Kiali over the Ingress URL.

2. Uninstall

To uninstall Kiali is simple - just delete the Kiali CR. This will trigger the Kiali Operator to uninstall Kiali:

oc delete kiali kiali -n kiali-operator

At this point, you have no Kiali installed, but you still have the Kiali Operator running. You could create another Kiali CR (with potentially different configuration settings) to install a new Kiali instance.

To uninstall the Kiali Operator, simply remove the kiali-operator namespace along with everything in it:

oc delete namespace -n kiali-operator

3. The Kiali UI

Log in to Kiali UI as admin/admin. If you installed on OpenShift with the default authentication strategy of "openshift", you will need to log in using your OpenShift credentials.

To achieve the best results you should have an example application like 'bookinfo' from the Istio examples deployed.

3.1. Detail view of a single service

Figure 2. Service view

4. Additional Notes

4.1. Customize the Kiali UI web context root

By default, when installed on OpenShift, the Kiali UI is deployed to the root context path of "/" e.g. https://kiali-istio-system.<your_cluster_domain_or_ip>/. In some situations such as when you want to serve the Kiali UI along with other apps under the same host name, e.g., example.com/kiali, example.com/app1, you can edit the Kiali CR and provide a different value for web_root. Note: the path must begin with a / and not end with a / (e.g. /kiali or /mykiali).

An example of custom web root:

server:
  web_root: /kiali
  ...

The above is actually the default when Kiali is installed on Kubernetes - so to access the Kiali UI on Kubernetes you access it at the root context path of "/kiali".

4.2. Login Options

Kiali supports three different login options.

login: This option allows a user to login into Kiali using a username and password. This is the default option if using Kubernetes.

anonymous: This option removes any login requirement. A user will not be presented the login page and will automatically have access to Kiali without having to present any credentials.

openshift: If you have deployed Kiali on OpenShift you can use this option (this is the default option if using OpenShift). With this option users will log into Kiali using the OpenShift OAuth login. What users can access in Kiali will now be based on their user roles in OpenShift using the kubernetes RBAC.

Using the anonymous option will leave Kiali unsecured. Anyone who can access the console will have full access to Kiali. If you are using this option you will need to make sure that it is only available on a trusted network and that only trusted users can access it.

For the login and anonymous login options, the content displayed in Kiali is based on the permissions of the Kiali service account. On Kubernetes, the Kiali service account has cluster wide access and will be able to display everything in the cluster. By default, in OpenShift the service account will also have access to everything in the cluster but this can be customized by following the instructions below.

For the openshift login option, the content displayed in Kiali is based on the permissions of the user who logged in via the OpenShift OAuth login page. This means that individual users will be shown different content based on their roles within OpenShift. See the section below for how to grant or remove a user’s access to specific namespaces.

The login option can be specified in the Kiali CR when installing Kiali. For instance, to use the openshift login option, the Kiali CR should contain the following in the auth section:

auth:
  strategy: openshift

4.2.1. OpenShift User Permissions

If you are running with the openshift login option you will need to grant a user the 'kiali' role for them to be able to properly access a namespace in Kiali.

For instance, to grant the user 'developer' access to the 'myproject' namespace, you could run the following command:

oc adm policy add-role-to-user kiali developer -n myproject

To remove the 'kiali' role from the user 'developer' in the 'myproject' namespace you can run the following command:

oc adm policy remove-role-from-user kiali developer -n myproject

4.3. Reducing Permissions in OpenShift

By default, Kiali will run with its cluster role named kiali. It provides some read-write capabilities so Kiali can add, modify, or delete some service mesh resources to perform tasks such as adding and modifying Istio destination rules in any namespace.

If you prefer not to run Kiali with this read-write role across the cluster, it is possible to reduce these permissions to individual namespaces.

This only works for OpenShift since it can return a list of namespaces that a user has access to. Know how to make this work with Kubernetes? Awesome, please let us know in this issue.

The first thing you will need to do is to remove the cluster-wide permissions that are granted to Kiali by default:

oc delete clusterrolebindings kiali

Then you will need to grant the kiali role in the namespace of your choosing:

oc adm policy add-role-to-user kiali system:serviceaccount:istio-system:kiali -n ${NAMESPACE}

You can alternatively tell the Kiali Operator to install Kiali in "view only" mode (this does work for either OpenShift or Kubernetes). You do this by setting the view_only_mode to true in the Kiali CR:

deployment:
  view_only_mode: true
  ...

This allows Kiali to read service mesh resources found in the cluster, but it does not allow Kiali to add, modify, or delete them.

4.4. Cleaning Up If You Cannot Uninstall Kiali

In some unusual situations, you may notice you are unable to uninstall Kiali. For example, you may try to delete the istio-system namespace but the command to do so hangs. This may be because the Kiali Operator failed to successfully run its finalizer. When you get into a hung state, try this to see if it clears up the problem:

oc patch kiali kiali -n kiali-operator -p '{"metadata":{"finalizers": []}}' --type=merge

If you happened to have installed the Kiali Operator (and more specifically the Kiali CR) in a different namespace, replace "kiali-operator" in the above command with the proper namespace where the Kiali CR is located.

Getting started