github.com/kiali/kiali@v1.84.0/README.adoc (about) 1 = 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"] 2 :toc: macro 3 :toc-title: 4 5 image:https://img.shields.io/badge/license-Apache2-blue.svg["Apache 2.0 license", link="LICENSE"] 6 7 == Introduction 8 9 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. 10 11 === Table of contents 12 13 toc::[] 14 15 === Contributing 16 17 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. 18 19 If you would like to make code contributions, please also check the link:./CONTRIBUTING.md[Contribution Guide]. 20 21 === Getting Started 22 23 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. 24 25 === How and where Kiali is released? 26 27 Read the link:./RELEASING.adoc[RELEASING.adoc] file. 28 29 == Developer setup 30 31 Make sure you have the following tools: 32 33 * The link:http://golang.org/doc/install[Go Programming Language] 34 ** 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. 35 * link:http://git-scm.com/book/en/v2/Getting-Started-Installing-Git[git] 36 * gcc 37 * link:https://docs.docker.com/installation/[Docker] or link:https://podman.io[Podman] 38 ** If you are using `podman` declare the environment variable `DORP=podman`. 39 * link:https://nodejs.org[NodeJS] (Node.js >= 18 with the NPM command) 40 * link:https://classic.yarnpkg.com/[Yarn] 41 * The _GNU make_ utility or any of it's alternatives 42 43 Once you have the required developer tools, you can get and build the code with the following script: 44 45 [source,shell] 46 ---- 47 # Checkout the source code 48 mkdir kiali_sources 49 cd kiali_sources 50 export KIALI_SOURCES=$(pwd) 51 52 git clone https://github.com/kiali/kiali.git 53 git clone https://github.com/kiali/kiali-operator.git 54 git clone https://github.com/kiali/helm-charts.git 55 56 ln -s $KIALI_SOURCES/kiali-operator kiali/operator 57 58 # Build the back-end and run the tests 59 cd $KIALI_SOURCES/kiali 60 make build test 61 62 # You can pass go test flags through the GO_TEST_FLAGS env var 63 # make -e GO_TEST_FLAGS="-race -v -run=\"TestCanConnectToIstiodReachable\"" test 64 65 # Build the front-end and run the tests 66 make build-ui-test 67 ---- 68 69 [NOTE] 70 The rest of this README assumes the directory tree created by the previous commands: 71 72 -- kiali_sources 73 |- kiali 74 |- kiali-operator 75 \- helm-charts 76 77 === Create a Kubernetes cluster and install a Service Mesh 78 79 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. 80 81 We provide a few unsupported scripts that can help to get started: 82 83 * You can use the link:hack/crc-openshift.sh[`crc-openshift.sh`] script to create an OpenShift cluster on your local machine. 84 * 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. 85 * You can also use link:https://kind.sigs.k8s.io/[kind], run link:hack/start-kind.sh[`start-kind.sh`] script to create a single node KinD cluster with metallb enabled for testing Kiali against a real environment. 86 * 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. 87 88 These scripts are written to rely on the minimum dependencies as possible and will try to download any required tools. 89 90 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`. 91 92 [NOTE] 93 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. 94 95 [NOTE] 96 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]. 97 98 === Building the Container Image and deploying to a cluster 99 100 Assuming that: 101 102 * you have successfully built the back-end and the front-end, 103 * you also have created a Kubernetes cluster with an Istio-based Service Mesh installed on it, 104 * and you are not using the `CLUSTER_TYPE=local` environment variable 105 106 the following commands should deploy a development build of Kiali to the cluster: 107 108 [source,shell] 109 ---- 110 cd $KIALI_SOURCES/kiali 111 112 # Build the Kiali-server and Kiali-operator container images and push them to the cluster 113 make cluster-push 114 115 # If you want to only build and push the Kiali-server container images: 116 # make cluster-push-kiali 117 118 # If you want to only build and push the Kiali-operator container images: 119 # make cluster-push-operator 120 121 # Deploy the operator to the cluster 122 make operator-create 123 124 # Create a KialCR to instruct the operator to deploy Kiali 125 make kiali-create 126 ---- 127 128 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`: 129 130 [source,shell] 131 ---- 132 export QUAY_NAME=localhost:5000/kiali/kiali 133 export CONTAINER_NAME=localhost:5000/kiali/kiali 134 export OPERATOR_QUAY_NAME=localhost:5000/kiali/kiali-operator 135 export OPERATOR_CONTAINER_NAME=localhost:5000/kiali/kiali-operator 136 137 cd $KIALI_SOURCES/kiali 138 139 # Build the Kiali-server and Kiali-operator container images and push them to the cluster 140 make container-build container-push 141 142 # If you want to only build and push the Kiali-server container images: 143 # make container-build-kiali container-push-kiali-quay 144 145 # If you want to only build and push the Kiali-operator container images: 146 # make container-build-operator container-push-operator-quay 147 148 # Deploy the operator to the cluster 149 make operator-create 150 151 # Create a KialCR to instruct the operator to deploy Kiali 152 make kiali-create 153 ---- 154 155 === Reloading Kiali image 156 157 If you already have Kiali installed and you want to recreate the kiali server pod, you can run the following command: 158 159 [source,shell] 160 ---- 161 cd $KIALI_SOURCES/kiali 162 make kiali-reload-image 163 ---- 164 165 This is to facilitate development. To quickly build a new Kiali container image and load it to the cluster, you can run: 166 167 [source,shell] 168 ---- 169 cd $KIALI_SOURCES/kiali/frontend 170 yarn && yarn build 171 172 cd $KIALI_SOURCES/kiali 173 make clean build cluster-push-kiali kiali-reload-image 174 ---- 175 176 [NOTE] 177 There is no equivalent reload command for the operator. You would need to manually reload the operator via `kubectl` or `oc` commands. 178 179 === Cluster clean-up 180 181 [source,shell] 182 ---- 183 cd $KIALI_SOURCES/kiali 184 185 # Delete the Kiali CR to let the operator remove Kiali. 186 make kiali-delete 187 188 # If the previous command never ends, the following command forces removal by bypassing the operator 189 # make kiali-purge 190 191 # Remove the operator 192 # NOTE: After this completes, the `kiali-create` and `kiali-delete` targets will be ineffective 193 # until you run the `operator-create` target to re-deploy the Kiali operator again. 194 make operator-delete 195 ---- 196 197 === Code formatting and linting 198 199 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: 200 201 [source,shell] 202 ---- 203 # CD to the back-end source code 204 cd $KIALI_SOURCES/kiali 205 206 # Install linting tools 207 make lint-install 208 209 # Format the code and run linters 210 make format lint 211 ---- 212 213 === Enable tracing 214 215 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. 216 217 [source,yaml] 218 ---- 219 apiVersion: kiali.io/v1alpha1 220 kind: Kiali 221 metadata: 222 name: kiali 223 spec: 224 ... 225 server: 226 observability: 227 tracing: 228 collector_url: http://jaeger-collector.istio-system:14268/api/traces 229 enabled: true 230 ... 231 ---- 232 233 === Running Standalone 234 235 You may want to run Kiali outside of any cluster environment for debugging purposes. To do this, you 236 will want to use the link:./hack/run-kiali.sh[run-kiali.sh hack script] located in the 237 link:./hack[hack directory]. See the `--help` output for the options you can set. 238 The default configuration it uses is found in the link:./hack/run-kiali-config-template.yaml[config template file] 239 also located in the `hack` directory. Read the comments at the tops of both files for more details. 240 241 [source,shell] 242 ---- 243 cd $KIALI_SOURCES/kiali/hack 244 ./run-kiali.sh 245 ---- 246 247 === Running integration tests 248 249 There are two sets of integration tests. The first are backend tests that test the Kiali API directly. These can be found at link:./tests/integration/README.md[backend tests]. The second are frontend Cypress tests that test Kiali through the browser. These can be found at link:./frontend/cypress/README.md[frontend tests]. 250 251 Both tests are run as part of the CI pipeline. If you'd like to run these same tests locally, you can use link:./hack/run-integration-tests.sh[this script] to setup your local environment and run the integration tests. Or these tests can be run against any live environment that meets the following requirements. 252 253 Requirements: 254 - Istio 255 - Kiali 256 - bookinfo demo app 257 - error rates demo app 258 259 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. 260 261 [source,shell] 262 ---- 263 # 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`: 264 make -e YARN_START_URL=http://<kiali-url> yarn-start 265 266 # Start the cypress tests. The tests will run against the frontend development server by default. 267 # Otherwise you can pass a custom url with env vars: 268 # 269 # make -e CYPRESS_BASE_URL=http://<kiali-url> cypress-gui 270 make cypress-gui 271 ---- 272 273 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. 274 275 === Debugging Server Backend 276 277 ==== VisualStudio Code 278 279 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). 280 281 [source,json] 282 ---- 283 { 284 // To use this, first run "hack/run-kiali.sh --tmp-root-dir $HOME/tmp --enable-server false" 285 // Pass in --help to that hack script for details on more options. 286 "version": "0.2.0", 287 "configurations": [ 288 { 289 "name": "Launch Kiali to use hack script services", 290 "type": "go", 291 "request": "launch", 292 "mode": "debug", 293 "program": "${workspaceRoot}/kiali.go", 294 "cwd": "${env:HOME}/tmp/run-kiali", 295 "args": ["-config", "${env:HOME}/tmp/run-kiali/run-kiali-config.yaml"], 296 "env": { 297 "KUBERNETES_SERVICE_HOST": "127.0.0.1", 298 "KUBERNETES_SERVICE_PORT": "8001", 299 "LOG_LEVEL": "trace" 300 } 301 } 302 ] 303 } 304 ---- 305 306 === Debugging GUI Frontend 307 308 You can debug the Kiali GUI directly inside of Google Chrome using the Chrome Developer Tools or using VisualStudio Code. 309 310 In order to use either one, you first must perform some initial steps. 311 312 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`. 313 314 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: 315 316 * 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`. 317 * 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`. 318 * 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`. 319 320 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: 321 322 ``` 323 Compiled successfully! 324 325 You can now view @kiali/kiali-ui in the browser. 326 327 Local: http://localhost:3001 328 On Your Network: http://192.168.1.15:3001 329 ... 330 ``` 331 332 At this point, you can begin to set up your debugger tool of choice - see the next sections. 333 334 ==== Google Chrome Developer Tools 335 336 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`). 337 338 In Google Chrome, open the Developer Tools. You can press `F12` or `Control-Shift-I` to do this. 339 340 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. 341 342 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. 343 344 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. 345 346 ==== VisualStudio Code 347 348 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. 349 350 [source,json] 351 ---- 352 { 353 "version": "0.2.0", 354 "configurations": [ 355 { 356 "name": "Launch Chrome", 357 "type": "chrome", 358 "request": "launch", 359 "url": "http://localhost:3001", 360 "webRoot": "${workspaceFolder}" 361 } 362 ] 363 } 364 ---- 365 366 == Configuration 367 368 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. 369 370 == Embedding Kiali 371 372 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. 373 374 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: 375 376 * To embed the _Overview_ page, use `https://_kiali_path_/overview?kiosk=console`. 377 * To embed the _Graph_ page, use `https://_kiali_path_/graph/namespaces?kiosk=console`. 378 * To embed the _Applications list_ page, use `https://_kiali_path_/applications?kiosk=console`. 379 380 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`. 381 382 `<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. 383 384 == Configure External Services 385 386 === Grafana 387 388 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 389 390 [source,yaml] 391 ---- 392 apiVersion: kiali.io/v1alpha1 393 kind: Kiali 394 metadata: 395 name: kiali 396 spec: 397 ... 398 external_services: 399 grafana: 400 url: http://grafana-istio-system.127.0.0.1.nip.io 401 ... 402 ---- 403 404 == Additional Notes 405 406 === Frontend development guidelines 407 408 Frontend development guidelines (styles, i18n, etc.) can be found link:./frontend/README.adoc#developing[here] 409 410 === Upgrading Go 411 412 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: 413 414 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"). 415 2. Run `go mod edit -go=x.y` where "x" and "y" are the major/minor versions of the Go version being used. 416 3. Run `go mod tidy -v` 417 4. Run `make clean build build-ui test` to ensure everything builds correctly. If any problems occur, obviously you must fix them. 418 5. Commit the changes to your working branch, create a PR, and make sure everything builds and works before merging the PR. 419 420 === Procedure to check and update patternfly versions 421 422 1. Launch command `npx npm-check-updates -t latest -f '/^@patternfly/'` 423 2. Launch `yarn install` to update the yarn.lock 424 3. Add to the commit package.json and yarn.lock 425 426 === Running the UI outside the cluster 427 428 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. 429 430 === Disabling SSL 431 432 In the provided OpenShift templates, SSL is turned on by default. If you want to turn it off, you should: 433 434 * Remove the "tls: termination: reencrypt" option from the Kiali route 435 436 * Remove the "identity" block, with certificate paths, from the Kiali Config Map. 437 438 * 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). 439 440 == Exposing Kiali to External Clients Using Istio Gateway 441 442 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: 443 444 [source,yaml] 445 ---- 446 --- 447 apiVersion: networking.istio.io/v1alpha3 448 kind: Gateway 449 metadata: 450 name: kiali-gateway 451 namespace: istio-system 452 spec: 453 selector: 454 istio: ingressgateway 455 servers: 456 - port: 457 number: 80 458 name: http-kiali 459 protocol: HTTP 460 # https://istio.io/latest/docs/reference/config/networking/gateway/#ServerTLSSettings 461 tls: 462 httpsRedirect: false 463 hosts: [<your-host>] 464 - port: 465 number: 443 466 name: https-kiali 467 protocol: HTTPS 468 tls: {} 469 hosts: [<your-host>] 470 ... 471 --- 472 apiVersion: networking.istio.io/v1alpha3 473 kind: VirtualService 474 metadata: 475 name: kiali-virtualservice 476 namespace: istio-system 477 spec: 478 gateways: 479 - kiali-gateway 480 hosts: [<your-host>] 481 http: 482 - route: 483 - destination: 484 host: kiali.istio-system.svc.cluster.local 485 port: 486 number: 20001 487 weight: 100 488 ... 489 --- 490 apiVersion: networking.istio.io/v1alpha3 491 kind: DestinationRule 492 metadata: 493 name: kiali-destinationrule 494 namespace: istio-system 495 spec: 496 host: kiali 497 trafficPolicy: 498 tls: 499 mode: DISABLE 500 ... 501 ---- 502 503 == Experimental 504 505 === Observing a Remote Cluster 506 507 [NOTE] 508 The "Central IstioD" setup is currently named "Primary-remote" multi-cluster setup. 509 510 [WARNING] 511 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. 512 513 There are certain use cases where Kiali needs to be deployed in one cluster (Control Plane) and observe a different cluster (Data Plane). 514 image:https://user-images.githubusercontent.com/6889074/87819080-ad099980-c839-11ea-834b-56eec038ce4d.png[Diagram] 515 516 Follow these steps: 517 518 1: You should have the link:https://istio.io/latest/docs/setup/install/external-controlplane[Istio with an External Control Plane] setup running 519 520 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 521 522 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 523 [source,shell] 524 ---- 525 istioctl create-remote-secret --service-account kiali-service-account --context=$DataPlane --name kiali | kubectl apply -n istio-system --context=$ControlPlane -f - 526 ---- 527 528 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 529 [source,yaml] 530 ---- 531 spec: 532 template: 533 spec: 534 containers: 535 - volumeMounts: 536 - mountPath: /kiali-remote-secret 537 name: kiali-remote-secret 538 volumes: 539 - name: kiali-remote-secret 540 secret: 541 defaultMode: 420 542 optional: true 543 secretName: istio-remote-secret-kiali 544 ---- 545 546 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*. 547 548 6: Kiali in the Control Plane should now be fully functional with the Data Plane