kiali

README

= Kiali image:https://img.shields.io/twitter/url/http/shields.io.svg?style=social["Tweet about Kiali", link="https://twitter.com/intent/tweet?text=Learn%20what%20your%20Istio-Mesh%20is%20doing.%20Visit%20https://www.kiali.io/%20and%20@kiali_project"]
:toc: macro
:toc-title:

image:https://travis-ci.org/kiali/kiali.svg["Build Status", link="https://travis-ci.org/kiali/kiali"]
image:https://img.shields.io/badge/license-Apache2-blue.svg["Apache 2.0 license", link="LICENSE"]

== Introduction

Kiali provides answers to the questions: _What microservices are part of my Istio service mesh and how are they connected?_

image::https://raw.githubusercontent.com/kiali/kiali.io/master/static/images/documentation/features/graph-overview.png[Kiali Graph, width=880]

== Table of contents

toc::[]

=== Description

A Microservice Architecture breaks up the monolith into many smaller pieces that are composed together. Patterns to secure the communication between services like fault tolerance (via timeout, retry, circuit breaking, etc.) have come up as well as distributed tracing to be able to see where calls are going.

A service mesh can now provide these services on a platform level and frees the application writers from those tasks. Routing decisions are done at the mesh level.

Kiali works with Istio to visualise the service mesh topology, features like circuit breakers or request rates.

Kiali also includes an integration with Jaeger Tracing to provide distributed tracing out of the box.

=== Getting Started

This README is targeted mainly toward Kiali developers. If you are not a developer but want to learn more about Kiali, you will find the link:https://www.kiali.io[Kiali documentation] more helpful. For some instructions on running Kiali without having to git clone this repository or build anything, please see the link:https://www.kiali.io/documentation/getting-started[Getting Started] page.

==== Testing on a OpenShift 4.1 Cluster

There are two hack scripts available to start a OpenShift 4.1 cluster - one to install in a local link:https://github.com/kiali/kiali/blob/master/hack/crc-openshift.sh[CRC VM] and one to install in an link:https://github.com/kiali/kiali/blob/master/hack/aws-openshift.sh[AWS environment].

Run the hack script with `--help` for usage details. Here is a brief synopsis on how to use the AWS hack script:

* `aws-openshift.sh -kuca true create` : Create an AWS cluster that includes Service Mesh, Kiali, Jaeger, ElasticSearch
* `aws-openshift.sh status` : Provides details about your AWS cluster
* `aws-openshift.sh oc-env` : Provides details about how to set up the `oc` client in your shell so it can access your AWS cluster
* `aws-openshift.sh destroy` : Destroy the AWS cluster
* `aws-openshift.sh bi-install` : Install BookInfo demo in the AWS cluster
* `aws-openshift.sh sm-uninstall` : Uninstall the Service Mesh and all its components that were previously installed via `create` or `sm-install`
* `aws-openshift.sh sm-install` : Re-install the Service Mesh and all its components
* `aws-openshift.sh k-uninstall` : Uninstall the Kiali component that was installed via `create` or `sm-install`

Here's a way you can work with AWS to do Kiali development:

* `aws-openshift.sh -kuca true create` to create your cluster with Service Mesh. `-kuca true` tells the script to create a cluster admin user "kiali" with password "kiali". This takes roughly 30 minutes to complete.
* `aws-openshift.sh status` to show you details about your cluster, including "oc login" details as well as the console URL among other things
* If you want to build and deploy your own Kiali:
** First must uninstall the one that was installed when you created the cluster. To do this, run `aws-openshift.sh k-uninstall`
** Next build Kiali and the Kiali operator normally (see below for details on that)
** Push the dev builds of your Kiali and Kiali operator into the AWS cluster's image registry via `make ocp-push`
** Create the new Kiali Operator in your AWS cluster via `make ocp-operator-create`
** Create the new Kiali in your AWS cluster via `make ocp-kiali-create`
** At this point, your dev build of Kiali should be starting up. Wait for it to come up and then you can access the Kiali UI normally.

==== Testing on a Local OpenShift 3.11 Cluster

If you have git cloned this repository, you can try to use our hack script to quickly install OpenShift 3.11, Maistra (Istio), and Kiali like this:

```
hack/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 link:hack/istio/README.adoc[Bookinfo Demo install script] provided here as a convenience.

There are other demo applications to choose from as well: link:./DEMOS.adoc[see some examples].

=== Container Image

The container images for Kiali and the Kiali Operator are published on https://quay.io/organization/kiali[Quay.io in the kiali organization].

=== License and Copyright

See the link:./LICENSE[LICENSE file].

== Building

[NOTE]
These build instructions assume you have the following installed on your system: (1) link:http://golang.org/doc/install[Go Programming Language] which must be at least version 1.8.3, (2) link:http://git-scm.com/book/en/v2/Getting-Started-Installing-Git[git], (3) link:https://docs.docker.com/installation/[Docker], and (4) make. To run Kiali on OpenShift after you build it, it is assumed you have a running OpenShift environment available to you. If you do not, you can find a set of link:#setting-up-openshift[instructions on how to set up OpenShift below]. To run Kiali on Kubernetes after you built it, it is assumed you have a running Kubernetes environment available to you.

To build Kiali:

* Clone this repository inside a GOPATH. These instructions will use the example GOPATH of "/source/kiali/kiali" but you can use whatever you want. Just change the first line of the below instructions to use your GOPATH.

[source,shell]
----
export GOPATH=/source/kiali/kiali
mkdir -p $GOPATH
cd $GOPATH
mkdir -p src/github.com/kiali
cd src/github.com/kiali
git clone git@github.com:kiali/kiali
export PATH=${PATH}:${GOPATH}/bin
----

* Install Glide - the Go dependency management tool that Kiali uses to build itself

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make dep-install
----

* Tell the dependency manager tool to update the Kiali dependencies
[NOTE]
You should only run this command if you add, remove, or modify a dependency. If you are simply git cloning and building from source, you should skip this step.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make dep-update
----

* Build Kiali

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make build
----

* At this point you can run the Kiali tests

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make test
----

== Running

[NOTE]
If you want to quickly get up and running to play with Kiali and do not wish to git clone the repository or build anything, see https://www.kiali.io/gettingstarted for instructions.

=== Running on OpenShift

==== Setting up OpenShift

The following section assumes that the user has link:https://github.com/openshift/origin[OpenShift] installed.

==== Building the Container Image

Create the Kiali container image through the "docker-build" make target:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make docker-build
----

This builds the Kiali operator image, too.

==== Deploying Kiali operator and Kiali to OpenShift

[NOTE]
Before deploying and running Kiali, you must first install and deploy link:https://istio.io[Istio]. *Required Istio Version: 1.1*. There are a few places that you can reference in order to learn how to do this. We recommend using link:https://maistra.io/docs/getting_started/[Maistra] but you can use the link:https://istio.io/docs/setup/kubernetes/install[upstream Istio instructions] making sure to follow the link:https://istio.io/docs/setup/kubernetes/prepare/platform-setup/openshift/[OpenShift preparation steps].

[NOTE]
The following make targets assume that either the `oc` command or the Maistra `istiooc` command is available in the user's PATH and that the user is logged in.

[NOTE]
The Makefile used in these commands is the link:./operator/Makefile[Operator Makefile] in the link:./operator[operator] directory. The legacy make targets in the main Makefile are still there for those developers that are used to using them - those legacy targets simply delegate to the Operator Makefile now.

===== Deploying Kiali Operator to OpenShift

[NOTE]
This command only works if running with OpenShift 3.11. If you are using OpenShift 4.x in either CRC or AWS, see the earlier instructions above. But in short, you need to push the images first via `ocp-push` and then use the target `ocp-operator-create` rather than `operator-create`.

You need to first install the Kiali operator. This needs to be done only one time. After the operator is deployed, you can deploy and remove Kiali any number of times using the steps described below.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali/operator
make operator-create
----

The main Makefile has the same target which delegates to the above.

===== Deploying Kiali to OpenShift

[NOTE]
This command only works if running with OpenShift 3.11. If you are using OpenShift 4.x in either CRC or AWS, see the earlier instructions above. But in short, you need to push the images first via `ocp-push` and then use the target `ocp-kiali-create` rather than `kiali-create`.

Now you can deploy Kiali. This creates a Kiali custom resource (CR) which instructs the Kiali operator to install Kiali. A secret will be created also.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali/operator
make kiali-create
----

The main Makefile legacy target `openshift-deploy` delegates to the above.

==== Removing Kiali from OpenShift

If you want to remove Kiali, you can do so via the operator by executing the `kiali-delete` target. This target will also remove the secret.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali/operator
make kiali-delete
----

The main Makefile legacy target `openshift-undeploy` delegates to the above.

If you want to quickly purge your OpenShift environment of all Kiali resources, you can run the `purge-kiali` target instead. This does not use the operator, instead it purges all Kiali resources using the oc/kubectl command.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali/operator
make purge-kiali
----

==== Reloading Kiali image in OpenShift

[NOTE]
To easily facilitate development, this target is in the main, top-level Makefile. This allows you to do `make clean build docker-build openshift-reload-image` to quickly get your new Kiali build into your running OpenShift.

If you already have Kiali installed but you want to recreate the pod with a new container image, you can run the following command:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make openshift-reload-image
----

==== Removing Kiali operator from OpenShift

You can remove the Kiali operator by running this make command. Note: after this completes, the `kiali-create` and `kiali-delete` targets will be ineffective until you run the `operator-create` target to re-deploy the Kiali operator.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali/operator
make operator-delete
----

There is no analogous target in the main Makefile.

=== Running on Kubernetes

==== Setting up Kubernetes

The following section assumes that the user has link:https://github.com/kubernetes/kubernetes[Kubernetes] installed.

==== Building the Container Image

Create the Kiali container image through the "docker-build" make target:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make docker-build
----

This builds the Kiali operator image, too.

Note that if you are using minikube, you can build the container images and push them directly into the minikube docker daemon using the alternative make target `minikube-docker`:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make minikube-docker
----

==== Deploying and Removing Kiali to/from Kubernetes

[NOTE]
Before deploying and running Kiali, you must first install and deploy link:https://istio.io[Istio]. *Required Istio Version: 1.1*. There are a few places that you can reference in order to learn how to do this. We recommend using link:https://maistra.io/docs/getting_started/[Maistra] but you can use the link:https://istio.io/docs/setup/kubernetes/install[upstream Istio instructions].

[NOTE]
The following make targets assume that the `kubectl` command is available in the user's PATH.

[NOTE]
In order to deploy on Kubernetes and to be able to access the deployed service, you must ensure you have Ingress support. If you are using minikube, you need to run `minikube addons enable ingress` and add `kiali` as a hostname in your `/etc/hosts` via something like this command: `echo "$(minikube ip) kiali" | sudo tee -a /etc/hosts`

The same commands documented above that explain how to deploy and remove Kiali operator and Kiali from OpenShift also apply to any Kubernetes environment. So these will work - see above for details about these commands.

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali/operator
make operator-create
make kiali-create
make kiali-delete
make purge-kiali
make operator-delete
----

==== Reloading Kiali image in Kubernetes

[NOTE]
To easily facilitate development, this target is in the main, top-level Makefile. This allows you to do `make clean build docker-build k8s-reload-image` to quickly get your new Kiali build into your running Kubernetes.

If you already have Kiali installed but you want to recreate the pod with a new container image, you can run the following command:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make k8s-reload-image
----

=== Running Standalone

Rarely, you may want to run Kiali outside of any cluster environment, perhaps for debugging purposes. To do this, run:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make install
make run
----

The "install" target installs the Kiali executable in your GOPATH /bin directory so you can run it outside of the Makefile:

[source,shell]
----
cd ${GOPATH}/src/github.com/kiali/kiali
make install
${GOPATH}/bin/kiali -config <your-config-file>
----

== Configuration

Many configuration settings can optionally be set within the Kiali Operator custom resource (CR) file. See link:./operator/deploy/kiali/kiali_cr.yaml[this example Kiali CR file] that has all the configuration settings documented.

== Embedding Kiali

If you want to embed Kiali in other applications, Kiali offers a simple feature called _Kiosk mode_. In this mode, Kiali won't show the main header, nor the main navigation bar.

To enable Kiosk mode, you only need to add a `kiosk=true` URL parameter. You will need to use the full path of the page you want to embed. For example, assuming that you access Kiali through HTTPS:

* To embed the _Overview_ page, use `https://_kiali_path_/overview?kiosk=true`.
* To embed the _Graph_ page, use `https://_kiali_path_/graph/namespaces?kiosk=true`.
* To embed the _Applications list_ page, use `https://_kiali_path_/applications?kiosk=true`.

If the page you want to embed uses other URL arguments, you can specify any of them to preset options. For example, if you want to embed the graph of the _bookinfo_ namespace, use the following URL: `http://_kiali_path_/graph/namespaces?namespaces=bookinfo&kiosk=true`.


== Configure External Services

=== Jaeger

If you have Jaeger installed in a custom way that is not easily auto-detectable by Kiali, you need to change in the Kiali CR the value of the jaeger > url

[source,yaml]
----
apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
  name: kiali
spec:
...
    external_services:
      jaeger:
        url: http://jaeger-query-istio-system.127.0.0.1.nip.io
...
----

=== Grafana

If you have Grafana installed in a custom way that is not easily auto-detectable by Kiali, you need to change in the Kiali CR the value of the grafana > url

[source,yaml]
----
apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
  name: kiali
spec:
...
    external_services:
      grafana:
        url: http://grafana-istio-system.127.0.0.1.nip.io
...
----

== Services API Documentation

Kiali can display API Documentation of your services. See https://user-images.githubusercontent.com/1235410/61569413-0e870480-aa3c-11e9-9527-bbea18eff475.png[API documentation screen capture] and https://user-images.githubusercontent.com/1235410/61569419-1777d600-aa3c-11e9-82cc-f9510e5b9808.png[API type list screen capture].

=== Configure your services

Your services must be annotated with the type of API ('rest', 'grpc', 'graphql') and a URL to the spec of the API. 
If the API spec is served from the service itself, Kiali will infer the hostname and port :

[source,yaml]
----
apiVersion: v1
kind: Service
metadata:
  name: myservice
  annotations:
    kiali.io/api-type: rest
    kiali.io/api-spec: /v1/api-spec  
spec:
...
----

The API spec can also be served from any http/s URL, internal or external to the cluster :

[source,yaml]
----
apiVersion: v1
kind: Service
metadata:
  name: petstore
  annotations:
    kiali.io/api-type: rest
    kiali.io/api-spec: https://petstore.swagger.io/v2/swagger.json  
spec:
...
----

For now, only REST APIs have their spec displayed but we are working to support gRpc and GraphQL soon.
A live console to test your APIs directly with Kiali is also being worked on.

=== Customize API docs annotations

You can configure Kiali to use your own annotation names with the Kiali CR

[source,yaml]
----
...
apidocs:
  annotations:
    api_spec_annotation_name: "my-annotation-for-api-spec"
    api_type_annotation_name: "my-annotation-for-api-type"
...
----

=== LDAP Configuration

The `auth.ldap` section is used to configure Kiali when the authentication strategy is LDAP. The following configuration is an example. Kiali will not start without the required LDAP settings of `ldap_host`, `ldap_port`, `ldap_base` and `ldap_bind_dn`.

[source,yaml]
----
auth:
  strategy: "ldap"
  ldap:
    ldap_base: "DC=example,DC=com"
    ldap_bind_dn: "CN={USERID},OU=xyz,OU=Users,OU=Accounts,DC=example,DC=com"
    ldap_group_filter: "(cn=%s)"
    ldap_host: "example.com"
    ldap_insecure_skip_verify: true
    ldap_mail_id_key: "mail"
    ldap_member_of_key: "memberOf"
    ldap_port: 123
    ldap_role_filter: ".*xyz.*"
    ldap_search_filter: "(&(name={USERID}))"
    ldap_use_ssl: false
    ldap_user_filter: "(cn=%s)"
    ldap_user_id_key: "cn"
----

== Additional Notes

=== 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 situations 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 `/` and not end with `/` (e.g. `/kiali`).

An example of custom web root:

[source,yaml]
----
...
server:
  web_root: /kiali
...
----

=== Running the UI Outside the Core

When developing the http://github.com/kiali/kiali-ui[Kiali UI] you will find it useful to run it outside of the core to make it easier to update the UI code and see the changes without having to recompile. The prefered approach for this is to use a proxy on the UI to mount the core. The process is described https://github.com/kiali/kiali-ui#developing[here].

To connect with the backend and avoid the javascript prompt requesting authentication you need to send the requests with a specific header.
[source]
----
X-Auth-Type-Kiali-UI: 1
----
The response will contain the header
[source]
----
WWW-Authenticate: xBasic realm="Kiali"
----
Otherwise the header will be
[source]
----
WWW-Authenticate: Basic realm="Kiali"
----

=== Running A Locally Built UI Inside the Core

If you are developing the UI on your local machine but you want to see it deployed and running inside of the core server, you can do so by setting the environment variable CONSOLE_VERSION to the value "local" when building the container image via the `docker-build` target. By default, your UI's build/ directory is assumed to be in a directory called `kiali-ui` that is a peer directory of the GOPATH root directory for the core server. If it is not, you can set the environment variable CONSOLE_LOCAL_DIR to the value of the path of the root directory for the UI such that `$CONSOLE_LOCAL_DIR/build` contains the generated build files for the UI.

For example, if your GOPATH directory for the Kiali project is `/source/kiali/kiali` and you have git cloned the Kiali UI repository in `/source/kiali/kiali-ui` then you do not need to set CONSOLE_LOCAL_DIR. You can embed your locally built console into the core container image via:

[source,shell]
----
CONSOLE_VERSION=local make docker-build
----

If you git cloned the Kiali UI repository in directory `/my/git/repo` and have built the UI there (such that the build files are located at `/my/git/repo/build`) then you can embed that locally built console into the core container image via:

[source,shell]
----
CONSOLE_VERSION=local CONSOLE_LOCAL_DIR=/my/git/repo make docker-build
----

=== Disabling SSL

In the provided OpenShift templates, SSL is turned on by default. If you want to turn it off, you should:

* Remove the "tls: termination: reencrypt" option from the Kiali route

* Remove the "identity" block, with certificate paths, from the Kiali Config Map.

* Optionally you can also remove the annotation "service.alpha.openshift.io/serving-cert-secret-name", and the related volume that is declared and mounted in Kiali Deployment (but if you don't, they will just be ignored).

In the provided Kubernetes templates, SSL is turned on by default. If you want to turn it off, you should:

* Remove the "identity" block, with certificate paths, from the Kiali Config Map.

* Optionally you can also remove the volume that is declared and mounted in Kiali Deployment (the name of the volume and mount are both "kiali-cert". If you don't remove these, they will just be ignored.

== Contributing

See the link:./CONTRIBUTING.md[Contribution Guide].

=== Talk to us

Ask questions on the Kiali IRC channel (_#kiali_ on freenode) or the Google Groups: link:++https://groups.google.com/forum/#!forum/kiali-users++[kiali-users] or link:++https://groups.google.com/forum/#!forum/kiali-dev++[kiali-dev].

=== Issue tracking

The Kiali team is using link:https://issues.jboss.org/browse/KIALI[JIRA] for issue tracking. 
If you do not have a JIRA account, you can also https://github.com/kiali/kiali/issues[open issues here on GitHub] (we are monitoring this as well) for any bugs or problems you encounter or to suggest new features.

When you are looking for issues to get started, you can use this https://issues.jboss.org/issues/?filter=12336706[JIRA query for good first issues].
If you pick one from the list, please let us know by the above mentioned means.

=== Code Style Guide

See the link:./STYLE_GUIDE.adoc[Backend Style Guide] and the link:https://github.com/kiali/kiali-ui/blob/master/STYLE_GUIDE.adoc[Frontend Style Guide].

Documentation

Overview

Kiali

Kiali project, observability for the Istio service mesh

Schemes: http, https
BasePath: /api
Version: _

Consumes:
- application/json

Produces:
- application/json

swagger:meta