Getting started

1. Getting started on OpenShift

Kiali currently requires Istio version 1.0 (see below if you have not yet installed Istio).

Kiali is still in development. Snapshots releases are pushed on Dockerhub from the CI pipeline.

To deploy Kiali to your Istio-enabled OpenShift cluster you can run the following. Kiali currently requires Istio version 1.0 (see below if you have not yet installed Istio).

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 follow 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 https://istio.io/docs/setup/ for details.

1.2. Install Kiali

Then install Kiali (note: this assumes you are installing v0.9.0 - set your VERSION_LABEL to the appropriate version you want to install):

JAEGER_URL="http://jaeger-query-istio-system.127.0.0.1.nip.io"
GRAFANA_URL="http://grafana-istio-system.127.0.0.1.nip.io"
VERSION_LABEL="v0.9.0"

curl https://raw.githubusercontent.com/kiali/kiali/${VERSION_LABEL}/deploy/openshift/kiali-configmap.yaml | \
  VERSION_LABEL=${VERSION_LABEL} \
  JAEGER_URL=${JAEGER_URL}  \
  GRAFANA_URL=${GRAFANA_URL} envsubst | oc create -n istio-system -f -

curl https://raw.githubusercontent.com/kiali/kiali/${VERSION_LABEL}/deploy/openshift/kiali-secrets.yaml | \
  VERSION_LABEL=${VERSION_LABEL} envsubst | oc create -n istio-system -f -

curl https://raw.githubusercontent.com/kiali/kiali/${VERSION_LABEL}/deploy/openshift/kiali.yaml | \
  VERSION_LABEL=${VERSION_LABEL}  \
  IMAGE_NAME=kiali/kiali \
  IMAGE_VERSION=${VERSION_LABEL}  \
  NAMESPACE=istio-system  \
  VERBOSE_MODE=4  \
  IMAGE_PULL_POLICY_TOKEN="imagePullPolicy: Always" envsubst | oc create -n istio-system -f -

If you do not have envsubst installed, you can get it via the GNU gettext package.

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

Kiali currently requires Istio version 1.0 (see below if you have not yet installed Istio).

To deploy Kiali to your Istio-enabled Kubernetes cluster you can run the following (note: this assumes you are installing v0.9.0 - set your VERSION_LABEL to the appropriate version you want to install):

     If you wish to install in Minikube, ensure that you enable the Ingress add-on by executing minikube addons enable ingress.

JAEGER_URL="http://jaeger-query-istio-system.127.0.0.1.nip.io"
GRAFANA_URL="http://grafana-istio-system.127.0.0.1.nip.io"
VERSION_LABEL="v0.9.0"

curl https://raw.githubusercontent.com/kiali/kiali/${VERSION_LABEL}/deploy/kubernetes/kiali-configmap.yaml | \
  VERSION_LABEL=${VERSION_LABEL} \
  JAEGER_URL=${JAEGER_URL}  \
  GRAFANA_URL=${GRAFANA_URL} envsubst | kubectl create -n istio-system -f -

curl https://raw.githubusercontent.com/kiali/kiali/${VERSION_LABEL}/deploy/kubernetes/kiali-secrets.yaml | \
  VERSION_LABEL=${VERSION_LABEL} envsubst | kubectl create -n istio-system -f -

curl https://raw.githubusercontent.com/kiali/kiali/${VERSION_LABEL}/deploy/kubernetes/kiali.yaml | \
  VERSION_LABEL=${VERSION_LABEL}  \
  IMAGE_NAME=kiali/kiali \
  IMAGE_VERSION=${VERSION_LABEL}  \
  NAMESPACE=istio-system  \
  VERBOSE_MODE=4  \
  IMAGE_PULL_POLICY_TOKEN="imagePullPolicy: Always" envsubst | kubectl create -n istio-system -f -

If you do not have envsubst installed, you can get it via the GNU gettext package.

Once this is done, Kiali will be deployed and running in Kubernetes. An Ingress will have been set up so you can go directly to the Kiali UI at the URL http://[minikube-ip]/ 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

 
     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:
  port: 20001
  web_root: /kiali
external_services:
  jaeger:
  ...

 

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}