Getting started

  Kiali currently requires Istio version 1.0.

1. Getting started on OpenShift

To deploy Kiali to your OpenShift cluster you can do the following.

1.1. Preparation

First, you need to grant the user that is installing Istio and Kiali the cluster-admin role.

If OpenShift is installed locally on the machine you are using, the following command should log you in as a user with the cluster-admin role:

oc login -u system:admin

You can now install Istio if needed. See the Istio Setup docs for details.

1.2. Install Kiali

Now install the latest release of Kiali.

  The install script can be configured for a customized install by setting environment variables when running the script. For example, to install a different version of Kiali, set IMAGE_VERSION to the version you want. Also, if your Jaeger or Grafana are accessible at different URLs than the default, then set JAEGER_URL and GRAFANA_URL appropriately. The defaults are: JAEGER_URL="http://jaeger-query-istio-system.127.0.0.1.nip.io" and GRAFANA_URL="http://grafana-istio-system.127.0.0.1.nip.io"

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

curl -L http://git.io/getLatestKiali | bash

Once the above has completed and the Docker image has been pulled from Dockerhub, go to the OpenShift console, select the istio-system project and determine the base-URL of Kiali

OpenShift console
Figure 1. OpenShift console

 

In this case it is http://kiali-istio-system.192.168.64.13.nip.io. In your case this could 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

2. Getting started on Kubernetes

To deploy Kiali to your Kubernetes cluster you can do the following.

2.1. Preparation

Preparation is only needed if you are installing in Minikube. When installing in Minikube, ensure that you enable the Ingress add-on by executing the following command:

minikube addons enable ingress

You can now install Istio if needed. See the Istio Setup docs for details.

2.2. Install Kiali

Now install the latest release of Kiali.

  The install script can be configured for a customized install by setting environment variables when running the script. For example, to install a different version of Kiali, set IMAGE_VERSION to the version you want. Also, if your Jaeger or Grafana are accessible at different URLs than the default, then set JAEGER_URL and GRAFANA_URL appropriately. The defaults are: JAEGER_URL="http://jaeger-query-istio-system.127.0.0.1.nip.io" and GRAFANA_URL="http://grafana-istio-system.127.0.0.1.nip.io"

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

curl -L http://git.io/getLatestKialiKubernetes | bash

Once this is done, Kiali will be deployed and running in Kubernetes with an Ingress set up.

If you deployed in minikube, you can go directly to 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.

3. Quick Start

If you do not already have an Istio-enabled cluster but want to see what Kiali is all about, you can try to run the convenience hack script cluster-openshift.sh which will install OpenShift, Istio, and Kiali all at once:

wget https://raw.githubusercontent.com/kiali/kiali/master/hack/cluster-openshift.sh
sh cluster-openshift.sh --kiali-enabled true up

This command installs an OpenShift cluster with Maistra and Kiali.

  If you do not already have an Istio-enabled application to test with, you can install one using the Bookinfo Sample install script provided as a convenience. See the Istio docs for more details about this sample application.

4. The Kiali UI

Log in to Kiali-UI as admin/admin.

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

4.1. Detail view of a single service

Service view
Figure 2. Service view

 

5. Additional Notes

5.1. Customize the UI web context root

By default, Kiali UI is deployed to the top level of https://kiali-istio-system.<your_cluster_domain_or_ip>/. In some situation such as when you want to serve Kiali UI along with other apps under the same host name, e.g., example.com/kiali, example.com/app1, you can edit Kiali Config Map and provide a different value for web_root. Note: the path must begin with a /.

An example of custom web root:

server:
  web_root: /kiali
  ...

 

5.2. Reducing Permissions in OpenShift

By default, Kiali will run with the cluster wide kiali role.

If you prefer not to run Kiali with cluster wide permissions, 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}