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@kialiProject"]
:toc: macro
:toc-title:

image:https://img.shields.io/badge/license-Apache2-blue.svg["Apache 2.0 license", link="LICENSE"]

== Introduction

link:https://kiali.io/[kiali] is a management console for Istio service mesh. Kiali can be quickly installed as an Istio add-on, or trusted as a part of your production environment.

=== Table of contents

toc::[]

=== Contributing

First, check the link:https://kiali.io/community/[Community section on kiali.io], which provides a brief introduction on contributing, how to report issues and request features, and how to reach us.

If you would like to make code contributions, please also check the link:./CONTRIBUTING.md[Contribution Guide].

=== Getting Started

The target audience of this README are developers. If you are not a developer but want to learn more about Kiali, the link:https://kiali.io/docs[Kiali documentation] should be more helpful. For instructions on installing Kiali, please read the link:https://kiali.io/docs/installation/[Installation] page.

=== How and where Kiali is released?

Read the link:./RELEASING.adoc[RELEASING.adoc] file.

== Developer setup

[NOTE]
Please, complement the content of this readme document with the link:https://github.com/kiali/kiali/blob/master/frontend/README.adoc[README.adoc document of the front-end repository]. Although this document has some instructions about building the front-end, they are not complete.

Make sure you have the following tools:

* The link:http://golang.org/doc/install[Go Programming Language]
** Currently, Kiali releases are built using a specific minimum version of Go as declared in the link:https://github.com/kiali/kiali/blob/master/Makefile#L31[Makefile]. Although Kiali may build correctly using other versions of Go, it's suggested to use the version that the Makefile uses for your own development to ensure replicatable builds.
* link:http://git-scm.com/book/en/v2/Getting-Started-Installing-Git[git]
* link:https://docs.docker.com/installation/[Docker] or link:https://podman.io[Podman]
** If you are using `podman` declare the environment variable `DORP=podman`.
* link:https://nodejs.org[NodeJS] (Node.js >= 12.22.0 && <16 with the NPM command)
* link:https://classic.yarnpkg.com/[Yarn]
* The _GNU make_ utility or any of it's alternatives

Once you have the required developer tools, you can get and build the code with the following script:

[source,shell]
----
# Checkout the source code
mkdir kiali_sources
cd kiali_sources
export KIALI_SOURCES=$(pwd)

git clone https://github.com/kiali/kiali.git
git clone https://github.com/kiali/kiali-operator.git
git clone https://github.com/kiali/helm-charts.git

ln -s $KIALI_SOURCES/kiali-operator kiali/operator

# Build the back-end and run the tests
cd $KIALI_SOURCES/kiali
make build test

# You can pass go test flags through the GO_TEST_FLAGS env var
# make -e GO_TEST_FLAGS="-race -v -run=\"TestCanConnectToIstiodReachable\"" test

# Build the front-end and run the tests
make build-ui-test
----

[NOTE]
The rest of this README assumes the directory tree created by the previous commands:

 -- kiali_sources
    |- kiali
    |- kiali-operator
    \- helm-charts

=== Create a Kubernetes cluster and install a Service Mesh

Since Kiali is a management console for an Istio-based service mesh, you will need an Istio-like Service Mesh to try Kiali. Then, Istio Meshes are installed on Kubernetes clusters.

We provide a few unsupported scripts that can help to get started:

* You can use the link:hack/crc-openshift.sh[`crc-openshift.sh`] script to create an OpenShift cluster on your local machine.
* If you are familiar to minikube, you may try the link:hack/k8s-minikube.sh[`k8s-minikube.sh`] script. It has the option to install Dex which is useful if you want to test with OpenID.
* Finally, the link:hack/istio/install-istio-via-istioctl.sh[`install-istio-via-istioctl.sh`] and the link:hack/istio/install-bookinfo-demo.sh[`install-bookinfo-demo.sh`] scripts can assist into installing Istio and the Bookinfo sample application in your cluster, respectively. You can try running these scripts without any arguments.

These scripts are written to rely on the minimum dependencies as possible and will try to download any required tools.

You can also use link:https://kind.sigs.k8s.io/[kind], however we don't have a script to create a kind cluster.

Depending on the type of cluster you are using, you should define the `CLUSTER_TYPE` environment variable on your shell to `openshift` (this is the default if not set), `minikube` or `kind` value so that the Makefiles can assist in other operations. If you are not using any of these clusters, you should set the environment variable to `CLUSTER_TYPE=local`.

[NOTE]
If you are using `minikube` it's recommended that you enable the `registry` and `ingress` add-on. The `k8s-minikube.sh` script should do this for you.

[NOTE]
If you are using `docker` and using minikube's registry add-on or any custom non-secure registry, make sure the link:https://docs.docker.com/registry/insecure/[Docker daemon is properly configured to use your registry].

=== Building the Container Image and deploying to a cluster

Assuming that:

* you have successfully built the back-end and the front-end,
* you also have created a Kubernetes cluster with an Istio-based Service Mesh installed on it,
* and you are not using the `CLUSTER_TYPE=local` environment variable

the following commands should deploy a development build of Kiali to the cluster:

[source,shell]
----
cd $KIALI_SOURCES/kiali

# Build the Kiali-server and Kiali-operator container images and push them to the cluster
make cluster-push

# If you want to only build and push the Kiali-server container images:
# make cluster-push-kiali

# If you want to only build and push the Kiali-operator container images:
# make cluster-push-operator

# Deploy the operator to the cluster
make operator-create

# Create a KialCR to instruct the operator to deploy Kiali
make kiali-create
----

If you are using the `CLUSTER_TYPE=local` environment variable, you will need to declare some additional environment variables to set the container registry where container images should be pushed and use `make container-push*` targets instead of `cluster-push*` targets. For example, if your container registry is `localhost:5000`:

[source,shell]
----
export QUAY_NAME=localhost:5000/kiali/kiali
export CONTAINER_NAME=localhost:5000/kiali/kiali
export OPERATOR_QUAY_NAME=localhost:5000/kiali/kiali-operator
export OPERATOR_CONTAINER_NAME=localhost:5000/kiali/kiali-operator

cd $KIALI_SOURCES/kiali

# Build the Kiali-server and Kiali-operator container images and push them to the cluster
make container-build container-push

# If you want to only build and push the Kiali-server container images:
# make container-build-kiali container-push-kiali-quay

# If you want to only build and push the Kiali-operator container images:
# make container-build-operator container-push-operator-quay

# Deploy the operator to the cluster
make operator-create

# Create a KialCR to instruct the operator to deploy Kiali
make kiali-create
----

=== Reloading Kiali image

If you already have Kiali installed and you want to recreate the kiali server pod, you can run the following command:

[source,shell]
----
cd $KIALI_SOURCES/kiali
make kiali-reload-image
----

This is to facilitate development. To quickly build a new Kiali container image and load it to the cluster, you can run:

[source,shell]
----
cd $KIALI_SOURCES/kiali/frontend
yarn && yarn build

cd $KIALI_SOURCES/kiali
make clean build cluster-push-kiali kiali-reload-image
----

[NOTE]
There is no equivalent reload command for the operator. You would need to manually reload the operator via `kubectl` or `oc` commands.

=== Cluster clean-up

[source,shell]
----
cd $KIALI_SOURCES/kiali

# Delete the Kiali CR to let the operator remove Kiali.
make kiali-delete

# If the previous command never ends, the following command forces removal by bypassing the operator
# make kiali-purge

# Remove the operator
# 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 again.
make operator-delete
----

=== Code formatting and linting

If you are changing the back-end code of Kiali, before submitting a pull request make sure your changes are properly formatted and no new linting issues are introduced by running:

[source,shell]
----
# CD to the back-end source code
cd $KIALI_SOURCES/kiali

# Install linting tools
make lint-install

# Format the code and run linters
make format lint
----

=== Enable tracing

Kiali itself is instrumented with opentelemetry tracing to help provide insights and surface performance issues for the kiali server. To enable, set the `server.observability.tracing.enabled` and `server.observability.tracing.collector_url` configuration options.

[source,yaml]
----
apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
  name: kiali
spec:
...
  server:
    observability:
      tracing:
        collector_url: http://jaeger-collector.istio-system:14268/api/traces
        enabled: true
...
----

=== Running Standalone

You may want to run Kiali outside of any cluster environment for debugging purposes. To do this, you
will want to use the link:./hack/run-kiali.sh[run-kiali.sh hack script] located in the
link:./hack[hack directory]. See the `--help` output for the options you can set.
The default configuration it uses is found in the link:./hack/run-kiali-config-template.yaml[config template file]
also located in the `hack` directory. Read the comments at the tops of both files for more details.

[source,shell]
----
cd $KIALI_SOURCES/kiali/hack
./run-kiali.sh
----

=== Running Cypress tests

Integration testing is done with cypress. More information can be found link:./frontend/cypress/README.md[here].

Requirements:
- Istio
- Kiali
- bookinfo demo app
- error rates demo app

You can use link:./hack/istio/install-testing-demos.sh[this script] to install all the neccessary demo apps for testing. The script supports both openshift and non-openshift deployments.

[source,shell]
----
# If you are doing frontend development, start the frontend development server, where `<kiali-url>` is the URL to the base Kiali UI location such as `http://localhost:20001/kiali`:
make -e YARN_START_URL=http://<kiali-url> yarn-start

# Start the cypress tests. The tests will run against the frontend development server by default.
# Otherwise you can pass a custom url with env vars:
#
# make -e CYPRESS_BASE_URL=http://<kiali-url> cypress-gui
make cypress-gui
----

Note that `make cypress-gui` runs the Cypress GUI that allows you to pick which individual tests to run. To run the entire test suite in headless mode, use the make target `cypress-run` instead.

=== Debugging Server Backend

==== VisualStudio Code

If you are using VisualStudio Code, you can install the following `launcher.json` that is then used to launch the Kiali Server in the debugger. Run the `hack/run-kiali.sh` script first to ensure the proper services are up (such as the Prometheus port-forward proxy).

[source,json]
----
{
    // To use this, first run "hack/run-kiali.sh --tmp-root-dir $HOME/tmp --enable-server false"
    // Pass in --help to that hack script for details on more options.
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Kiali to use hack script services",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceRoot}/kiali.go",
            "cwd": "${env:HOME}/tmp/run-kiali",
            "args": ["-config", "${env:HOME}/tmp/run-kiali/run-kiali-config.yaml"],
            "env": {
                "KUBERNETES_SERVICE_HOST": "127.0.0.1",
                "KUBERNETES_SERVICE_PORT": "8001",
                "LOG_LEVEL": "trace"
            }
        }
    ]
}
----

=== Debugging GUI Frontend

You can debug the Kiali GUI directly inside of Google Chrome using the Chrome Developer Tools or using VisualStudio Code.

In order to use either one, you first must perform some initial steps.

First, run the Kiali Server backend, either normally within a cluster or via `run-kiali.sh` as explained earlier. Determine what the Kiali URL is before moving to the next step. For example, if you run Kiali in minikube, and you set up a port-forward that exposes it, the URL to remember will be `http://localhost:20001/kiali`.

Second, run the GUI frontend using make: `make -e YARN_START_URL=<kiali-url> yarn-start` where `<kiali-url>` is the URL you determined from the previous step. You may need to also pass `-e PORT=3001` to override the default port where the yarn server will listen to (the default is `3000` which will conflict with Grafana if you started the Kiali Server via `run-kiali.sh`). Some examples:

* If the Kiali Server is running in minikube with a port-forward exposing it, then run `make -e YARN_START_URL=http://localhost:20001/kiali yarn-start`.
* If the Kiali Server is running in OpenShift with the usual Kiali Route exposing it, then run `make -e YARN_START_URL=https://<Kiali-OpenShift-Route-IP>/ yarn-start`.
* If the Kiali Server is running locally via `run-kiali.sh`, then run `make -e YARN_START_URL=http://localhost:20001/kiali -e PORT=3001 yarn-start`.

The `yarn-start` make command will start the Kiali GUI frontend on a local endpoint - when it is ready, look at the output for the "Local" URL you use to access it. The output will look something like this:

```
Compiled successfully!

You can now view @kiali/kiali-ui in the browser.

  Local:            http://localhost:3001
  On Your Network:  http://192.168.1.15:3001
...
```

At this point, you can begin to set up your debugger tool of choice - see the next sections.

==== Google Chrome Developer Tools

Start Google Chrome and point the browser to the local URL for the Kiali GUI frontend started by yarn-start (in the example above, that will be `http://localhost:3001`).

In Google Chrome, open the Developer Tools. You can press `F12` or `Control-Shift-I` to do this.

Within the Developer Tools, navigate to the `Sources` tab, then the `Filesystem` sub-tab, and press the `+ Add folder to workspace` link. In the file selection dialog, select your Kiali `frontend/src` folder. This will inform Developer Tools where your Kiali GUI frontend source code can be found.

At this point, you need to give Google Chrome permission to access your local source code folder. Towards the top of the browser window, you will see a prompt - press the "Allow" button to give Chrome the necessary permissions it needs.

You are now ready to debug the Kiali Server frontend. You can set breakpoints, inspect variables, examine stack traces, etc. just as you can do with any typical debugging tool.

==== VisualStudio Code

If you are using VisualStudio Code, you can install the following `launcher.json` that is then used to launch Google Chrome to debug the Kiali Server GUI frontend in the debugger. The `url` setting is the local URL of the yarn-start server - make sure you use the one appropriate for your environment.

[source,json]
----
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch Chrome",
            "type": "chrome",
            "request": "launch",
            "url": "http://localhost:3001",
            "webRoot": "${workspaceFolder}"
        }
    ]
}
----

== Configuration

Many configuration settings can optionally be set within the Kiali Operator custom resource (CR) file. See link:https://github.com/kiali/kiali-operator/blob/master/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=<platform_id>` 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=console`.
* To embed the _Graph_ page, use `https://_kiali_path_/graph/namespaces?kiosk=console`.
* To embed the _Applications list_ page, use `https://_kiali_path_/applications?kiosk=console`.

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=console`.

`<platform_id>` value in the `kiosk` URL parameter will be used in future use cases to add conditional logic on embedded use cases, for now, any non empty value will enable the kiosk mode.

== Configure External Services

=== 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
...
----

== Additional Notes

=== Upgrading Go

The Kiali project will periodically upgrade to a newer version of Go. These are the steps that need to be performed in order for the Kiali build to use a different version of Go:

1. In the top link:./Makefile[Makefile], change the value of the variable `GO_VERSION_KIALI` to the new Go version (use a z-stream version: "x.y.z").
2. Run `go mod edit -go=x.y` where "x" and "y" are the major/minor versions of the Go version being used.
3. Run `go mod tidy -v`
4. Run `make clean build build-ui test` to ensure everything builds correctly. If any problems occur, obviously you must fix them.
5. Commit the changes to your working branch, create a PR, and make sure everything builds and works before merging the PR.

=== Running the UI outside the cluster

When developing the http://github.com/kiali/kiali/frontend[Kiali UI] you will find it useful to run it outside of the cluster to make it easier to update the UI code and see the changes without having to re-deploy. The preferred approach for this is to use the _proxy_ feature of React. The process is described https://github.com/kiali/kiali/blob/master/frontend/README.adoc#developing[here]. Alternatively, you can use the `make -e YARN_START_URL=<url> yarn-start` command where `<url>` is to the Kiali backend.

=== 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.beta.openshift.io/serving-cert-secret-name" in the Kiali Service, and the related `kiali-cabundle` volume that is declared and mounted in Kiali Deployment (but if you don't, they will just be ignored).

== Exposing Kiali to External Clients Using Istio Gateway

The operator will create a Route or Ingress by default (see the Kiali CR setting "deployment.ingress_enabled"). If you want to expose Kiali via Istio itself, you can create Gateway, Virtual Service, and Destination Rule resources similar to below:

[source,yaml]
----
---
apiVersion: networking.istio.io/v1alpha3
kind: Gateway
metadata:
  name: kiali-gateway
  namespace: istio-system
spec:
  selector:
    istio: ingressgateway
  servers:
  - port:
      number: 80
      name: http-kiali
      protocol: HTTP
    # https://istio.io/latest/docs/reference/config/networking/gateway/#ServerTLSSettings
    tls:
      httpsRedirect: false
    hosts: [<your-host>]
  - port:
      number: 443
      name: https-kiali
      protocol: HTTPS
    tls: {}
    hosts: [<your-host>]
...
---
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: kiali-virtualservice
  namespace: istio-system
spec:
  gateways:
  - kiali-gateway
  hosts: [<your-host>]
  http:
  - route:
    - destination:
        host: kiali.istio-system.svc.cluster.local
        port:
          number: 20001
      weight: 100
...
---
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: kiali-destinationrule
  namespace: istio-system
spec:
  host: kiali
  trafficPolicy:
    tls:
      mode: DISABLE
...
----

== Experimental

=== Observing a Remote Cluster

[NOTE]
The "Central IstioD" setup is currently named "Primary-remote" multi-cluster setup.

[WARNING]
When this support was incorporated into Kiali, the "Central IstioD" setup of Istio was in an early development phase. These instructions are probably now broken.

There are certain use cases where Kiali needs to be deployed in one cluster (Control Plane) and observe a different cluster (Data Plane). 
image:https://user-images.githubusercontent.com/6889074/87819080-ad099980-c839-11ea-834b-56eec038ce4d.png[Diagram]

Follow these steps:

1: You should have the link:https://istio.io/latest/docs/setup/install/external-controlplane[Istio with an External Control Plane] setup running

2: Create the link:https://github.com/istio/istio/blob/master/samples/addons/kiali.yaml[Kiali ClusterRole, ClusterRoleBinding, and ServiceAccount] in the Data Plane cluster

3: Create a remote secret in the Control Plane, using the Data Plane ServiceAccount you just created. This allows the Control Plane to read from and modify the Data Plane
[source,shell]
----
istioctl x create-remote-secret --service-account kiali-service-account --context=$DataPlane --name kiali | kubectl apply -n istio-system --context=$ControlPlane -f -
----

4: You will now run Kiali in the Control Plane. You need to add the remote secret to the Kiali Deployment by specifying a Volume and VolumeMount. When Kiali sees */kiali-remote-secret/kiali* it will use the remote cluster's API server instead of the local API server
[source,yaml]
----
spec:
  template:
    spec:
      containers:
      - volumeMounts:
        - mountPath: /kiali-remote-secret
          name: kiali-remote-secret
      volumes:
      - name: kiali-remote-secret
        secret:
          defaultMode: 420
          optional: true
          secretName: istio-remote-secret-kiali
----

5: Kiali now needs the Istio metrics from the sidecars. You need to run Prometheus in the Control Plane and have it scrape the metrics from an link:https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig[envoyMetricsService]. These link:https://kiali.io/docs/faq/general/#which-istio-metrics-and-attributes-are-required-by-kiali[metrics] are *required*.

6: Kiali in the Control Plane should now be fully functional with the Data Plane

Documentation

Overview

Kiali

Kiali Project, The Console for Istio Service Mesh

NOTE! The Kiali API is not for public use and is not supported for any use outside of the Kiali UI itself. The API can and will change from version to version with no guarantee of backwards compatibility.

To generate this API document: ```

> alias swagger='docker run --rm -it  --user $(id -u):$(id -g) -e GOCACHE=/tmp -e GOPATH=$(go env GOPATH):/go -v $HOME:$HOME -w $(pwd) quay.io/goswagger/swagger'
> swagger generate spec -o ./swagger.json
> swagger generate markdown --quiet --spec ./swagger.json --output ./kiali_internal_api.md

```

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

Consumes:
- application/json

Produces:
- application/json

swagger:meta