- Introduction
- Table of contents
- Building
- Running
- Running on OpenShift or Kubernetes/Minikube
- Building the Container Image
- Pushing Kiali operator and Kiali images to your cluster
- Deploying Kiali operator to your cluster
- Deploying Kiali to your cluster
- Removing Kiali from your cluster
- Reloading Kiali image
- Removing Kiali operator from your cluster
- Running Standalone
- Configuration
- Embedding Kiali
- Configure External Services
- Services API Documentation
- Additional Notes
- Exposing Kiali to External Clients Using Istio Gateway
- Experimental
- Contributing
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.
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 Kiali documentation more helpful. For some instructions on running Kiali without having to git clone this repository or build anything, please see the Getting Started page.
To install a OpenShift 4.x cluster in AWS, use this hack script.
Run the hack script with --help
for usage details. Here is a brief synopsis:
-
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 theoc
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 viacreate
orsm-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 viacreate
orsm-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 cluster-push
. -
Create the new Kiali Operator in your AWS cluster via
make operator-create
-
Create the new Kiali in your AWS cluster via
make 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.
-
The container images for Kiali and the Kiali Operator are published on Quay.io in the kiali organization.
See the LICENSE file.
Note
|
These build instructions assume you have the following installed on your system: (1) Go Programming Language, (2) git, (3) Docker or Podman , (4) NPM, and (5) make. If you are using podman instead of docker , pass the environment variable DORP=podman when executing make . To run Kiali in a cluster after you build it, it is assumed you have a running OpenShift or Minikube environment available to you.
|
Note
|
Currently, Kiali releases are built using Go 1.14. Although Kiali may build correctly using other versions of Go, it’s suggested to use version 1.14 for development to ensure replicatable builds. Makefiles will require this minimum version of Go. |
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.
export GOPATH=/source/kiali/kiali
mkdir -p $GOPATH
cd $GOPATH
mkdir -p src/github.com/kiali
cd src/github.com/kiali
git clone [email protected]:kiali/kiali
git clone [email protected]:kiali/kiali-operator kiali/operator
git clone [email protected]:kiali/helm-charts kiali/helm-charts
export PATH=${PATH}:${GOPATH}/bin
-
Build Kiali
cd ${GOPATH}/src/github.com/kiali/kiali
make build
-
At this point you can run the Kiali tests
cd ${GOPATH}/src/github.com/kiali/kiali
make test
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. |
Note
|
Before deploying and running Kiali, you must first install and deploy Istio. There are a few places that you can reference in order to learn how to do this. We recommend using Maistra which is a variant of Istio. If you choose to use Istio, make sure to follow the OpenShift preparation steps. Also, check the version requirements on our website to read notes about Istio and Maistra compatibility. There is a install-istio-via-istioctl.sh hack script that can install Istio for you. |
By default, the make targets used to push and deploy Kiali images will assume you have an OpenShift 4.x cluster installed and running and that oc
is found in your $PATH.
If you wish to push and deploy Kiali to an installed and running Kubernetes (via Minikube) environment, pass the environment variable CLUSTER_TYPE=minikube
to the make
commands and make sure kubectl
is found in your $PATH.
If you have neither minikube nor a remote OpenShift cluster, you can pass the environment variable CLUSTER_TYPE=local
to the make
commands and make sure you have either oc
or kubectl
in your $PATH. This requires your Kubernetes cluster to be able to pull from your local image repository.
In order to deploy on Minikube using the below instructions, and to be able to access the deployed services, you must ensure you have the Registry and Ingress addons. To do this, ensure you run minikube addons enable registry
and 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
If you are using docker
, make sure the endpoint for your OpenShift image registry or Kubernetes image registry is configured as an insecure registry in your docker daemon config.
Create the Kiali container images through the "container-build" make target:
cd ${GOPATH}/src/github.com/kiali/kiali
make container-build
This will build the Kiali image.
Generated container image will be consistant with the host machine (either x86_64 or aarch64).
cd ${GOPATH}/src/github.com/kiali/kiali
make cluster-push
This actually invokes the container-build
target as well, so you technically do not have to run make container-build
as a separate step.
cd ${GOPATH}/src/github.com/kiali/kiali
make operator-create
Deploying the Kiali operator 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.
cd ${GOPATH}/src/github.com/kiali/kiali
make kiali-create
This creates a Kiali custom resource (CR) which instructs the Kiali operator to install Kiali. A secret will be created if needed (i.e. when the authentication strategy is set to login
).
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.
cd ${GOPATH}/src/github.com/kiali/kiali
make kiali-delete
If you want to purge your cluster of all Kiali resources without going through the operator to do it, you can run the kiali-purge
target instead. This does not use the operator, instead it purges all Kiali resources using the oc/kubectl command.
cd ${GOPATH}/src/github.com/kiali/kiali
make kiali-purge
Note
|
To easily facilitate development, this allows you to do make clean build cluster-push-kiali kiali-reload-image to quickly get your new Kiali build into your running cluster.
|
If you already have Kiali installed but you want to recreate the pod with a new container image, you can run the following command:
cd ${GOPATH}/src/github.com/kiali/kiali
make kiali-reload-image
cd ${GOPATH}/src/github.com/kiali/kiali
make operator-delete
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.
|
Rarely, you may want to run Kiali outside of any cluster environment, perhaps for debugging purposes. To do this, run:
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:
cd ${GOPATH}/src/github.com/kiali/kiali
make install
${GOPATH}/bin/kiali -config <your-config-file>
Many configuration settings can optionally be set within the Kiali Operator custom resource (CR) file. See this example Kiali CR file that has all the configuration settings documented.
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: https://kiali_path/graph/namespaces?namespaces=bookinfo&kiosk=true
.
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
apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
name: kiali
spec:
...
external_services:
jaeger:
url: https://jaeger-query-istio-system.127.0.0.1.nip.io
...
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
apiVersion: kiali.io/v1alpha1
kind: Kiali
metadata:
name: kiali
spec:
...
external_services:
grafana:
url: https://grafana-istio-system.127.0.0.1.nip.io
...
Kiali can display API Documentation of your services. See API documentation screen capture and API type list screen capture.
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 :
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 :
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.
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:
...
server:
web_root: /kiali
...
When developing the 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 here.
To connect with the backend and avoid the javascript prompt requesting authentication you need to send the requests with a specific header.
X-Auth-Type-Kiali-UI: 1
The response will contain the header
WWW-Authenticate: xBasic realm="Kiali"
Otherwise the header will be
WWW-Authenticate: Basic realm="Kiali"
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 container-build
or cluster-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:
CONSOLE_VERSION=local make container-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:
CONSOLE_VERSION=local CONSOLE_LOCAL_DIR=/my/git/repo make container-build
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.
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 similiar to below:
---
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
...
There are certain use cases where Kiali needs to be deployed in one cluster (Control Plane) and observe a different cluster (Data Plane). Diagram.
Follow these steps:
1: You should have the remote central istiod with a single cluster setup running
2: Create the 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
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
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 envoyMetricsService. These metrics are required:
-
istio_requests_total
-
istio_request_duration_milliseconds
-
istio_response_bytes
-
istio_request_bytes
6: Kiali in the Control Plane should now be fully functional with the Data Plane
First, check the Contribute section in our web site, 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 Contribution Guide as a starting point.