diff --git a/content/docs/tasks/telemetry/kiali/index.md b/content/docs/tasks/telemetry/kiali/index.md new file mode 100644 index 0000000000..79ab71a69f --- /dev/null +++ b/content/docs/tasks/telemetry/kiali/index.md @@ -0,0 +1,211 @@ +--- +title: Visualizing Your Mesh +description: This task shows you how to visualize your services within an Istio mesh. +weight: 49 +keywords: [telemetry,visualization] +--- + +This task shows you how to visualize different aspects of your Istio mesh. + +As part of this task, you install the [Kiali](https://www.kiali.io) add-on +and use the web-based graphical user interface to view service graphs of +the mesh and your Istio configuration objects. Lastly, you use the Kiali +Public API to generate graph data in the form of consumable JSON. + +This task uses the [Bookinfo](/docs/examples/bookinfo/) sample application as the example throughout. + +## Before you begin + +> {{< idea_icon >}} The following instructions assume you have installed Helm and use it to install Kiali. +To install Kiali without using Helm, following the [Kiali install instructions](https://www.kiali.io/gettingstarted/). + +Create a secret in your Istio namespace with the credentials that you use to +authenticate to Kiali. + +First, define the credentials you want to use as the Kiali username and passphrase: + +{{< text bash >}} +$ KIALI_USERNAME=$(read -p 'Kiali Username: ' uval && echo -n $uval | base64) +{{< /text >}} + +{{< text bash >}} +$ KIALI_PASSPHRASE=$(read -sp 'Kiali Passphrase: ' pval && echo -n $pval | base64) +{{< /text >}} + +To create a secret, run the following commands: + +```bash +NAMESPACE=istio-system +kubectl create namespace $NAMESPACE +cat <}} +$ helm template --set kiali.enabled=true install/kubernetes/helm/istio --name istio --namespace istio-system > $HOME/istio.yaml +$ kubectl apply -f $HOME/istio.yaml +{{< /text >}} + +> {{< idea_icon >}} This Task does not discuss Jaeger and Grafana. If +you already installed them in your cluster and you want to see how Kiali +integrates with them, you must pass additional arguments to the +`helm` command, for example: + +{{< text bash >}} + $ helm template \ + --set kiali.enabled=true \ + --set "kiali.dashboard.jaegerURL=http://$(kubectl get svc tracing -o jsonpath='{.spec.clusterIP}'):80" \ + --set "kiali.dashboard.grafanaURL=http://$(kubectl get svc grafana -o jsonpath='{.spec.clusterIP}'):3000" \ + install/kubernetes/helm/istio \ + --name istio --namespace istio-system > $HOME/istio.yaml + $ kubectl apply -f $HOME/istio.yaml +{{< /text >}} + +Once you install Istio and Kiali, deploy the [Bookinfo](/docs/examples/bookinfo/) sample application. + +## Generating a service graph + +1. To verify the service is running in your cluster, run the following command: + + {{< text bash >}} + $ kubectl -n istio-system get svc kiali + {{< /text >}} + +1. To determine the Bookinfo URL, follow the instructions to determine the [Bookinfo ingress `GATEWAY_URL`](/docs/examples/bookinfo/#determining-the-ingress-ip-and-port). + +1. To send traffic to the mesh, you have three options + + * Visit `http://$GATEWAY_URL/productpage` in your web browser + + * Use the following command multiple times: + + {{< text bash >}} + $ curl http://$GATEWAY_URL/productpage + {{< /text >}} + + * If you installed the `watch` command in your system, send requests continually with: + + {{< text bash >}} + $ watch -n 1 curl -o /dev/null -s -w %{http_code} $GATEWAY_URL/productpage + {{< /text >}} + +1. To open the Kiali UI, execute the following command in your Kubernetes environment: + + {{< text bash >}} + $ kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=kiali -o jsonpath='{.items[0].metadata.name}') 20001:20001 + {{< /text >}} + +1. Visit in your web browser. + +1. To log into the Kiali UI, go to the Kiali login screen and enter the username and passphrase stored in the Kiali secret. + +1. View the overview of your mesh in the **Overview** page that appears immediately after you log in. + The **Overview** page displays all the namespaces that have services in your mesh. + The following screenshot shows a similar page: + + {{< image width="75%" ratio="41%" + link="./kiali-overview.png" + caption="Example Overview" + >}} + +1. To view a namespace graph, click on the `bookinfo` namespace in the Bookinfo namespace card. + The page looks similar to: + + {{< image width="75%" ratio="89%" + link="./kiali-graph.png" + caption="Example Graph" + >}} + +1. To view a summary of metrics, select any node or edge in the graph to display + its metric details in the summary details panel on the right. + +1. To view your service mesh using different graph types, select a graph type + from the **Graph Type** drop down menu. There are several graph types + to choose from: **App**, **Versioned App**, **Workload**, **Service**. + + * The **App** graph type aggregates all versions of an app into a single graph node. + The following example shows a single **reviews** node representing the three versions + of the reviews app. + + {{< image width="75%" ratio="35%" + link="./kiali-app.png" + caption="Example App Graph" + >}} + + * The **Versioned App** graph type shows a node for each version of an app, + but all versions of a particular app are grouped together. The following example + shows the **reviews** group box that contains the three nodes that represents the + three versions of the reviews app. + + {{< image width="75%" ratio="67%" + link="./kiali-versionedapp.png" + caption="Example Versioned App Graph" + >}} + + * The **Workload** graph type shows a node for each workload in your service mesh. + This graph type does not require you to use the `app` and `version` labels so if you + opt to not use those labels on your components, this is the graph type you will use. + + {{< image width="70%" ratio="76%" + link="./kiali-workload.png" + caption="Example Workload Graph" + >}} + + * The **Service** graph type shows a node for each service in your mesh but excludes + all apps and workloads from the graph. + + {{< image width="70%" ratio="35%" + link="./kiali-service-graph.png" + caption="Example Service Graph" + >}} + +1. To examine the details about the Istio configuration, click on the + **Applications**, **Workloads**, and **Services** menu icons on the left menu + bar. The following screenshot shows the Bookinfo applications information: + + {{< image width="80%" ratio="53%" + link="./kiali-services.png" + caption="Example Details" + >}} + +## About the Kiali Public API + +To generate JSON files representing the graphs and other metrics, health, and +configuration information, you can access the +[Kiali Public API](https://www.kiali.io/api). +For example, point your browser to `$KIALI_URL/api/namespaces/graph?namespaces=bookinfo&graphType=app` +to get the JSON representation of your graph using the `app` graph type. + +The Kiali Public API is built on top of Prometheus queries and depends on the +standard Istio metric configuration. It also makes Kubernetes API calls to +obtain additional details about your services. For the best experience using +Kiali, use the metadata labels `app` and `version` on your application +components. As a template, the Bookinfo sample application follows this +convention. + +## Cleanup + +If you are not planning any follow-up tasks, remove the Bookinfo sample application and Kiali from your cluster. + +1. To remove the Bookinfo application, refer to the [Bookinfo cleanup](/docs/examples/bookinfo/#cleanup) instructions. + +1. To remove Kiali from a Kubernetes environment, remove all components with the `app=kiali` label: + +{{< text bash >}} +$ kubectl delete all,secrets,sa,configmaps,deployments,ingresses,clusterroles,clusterrolebindings,virtualservices,destinationrules --selector=app=kiali -n istio-system +{{< /text >}} diff --git a/content/docs/tasks/telemetry/kiali/kiali-app.png b/content/docs/tasks/telemetry/kiali/kiali-app.png new file mode 100644 index 0000000000..993f02f8bc Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-app.png differ diff --git a/content/docs/tasks/telemetry/kiali/kiali-graph.png b/content/docs/tasks/telemetry/kiali/kiali-graph.png new file mode 100644 index 0000000000..cbdd611cec Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-graph.png differ diff --git a/content/docs/tasks/telemetry/kiali/kiali-overview.png b/content/docs/tasks/telemetry/kiali/kiali-overview.png new file mode 100644 index 0000000000..3136509589 Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-overview.png differ diff --git a/content/docs/tasks/telemetry/kiali/kiali-service-graph.png b/content/docs/tasks/telemetry/kiali/kiali-service-graph.png new file mode 100644 index 0000000000..b3ce9ab29e Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-service-graph.png differ diff --git a/content/docs/tasks/telemetry/kiali/kiali-services.png b/content/docs/tasks/telemetry/kiali/kiali-services.png new file mode 100644 index 0000000000..59b3c9b3f8 Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-services.png differ diff --git a/content/docs/tasks/telemetry/kiali/kiali-versionedapp.png b/content/docs/tasks/telemetry/kiali/kiali-versionedapp.png new file mode 100644 index 0000000000..5873a143d6 Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-versionedapp.png differ diff --git a/content/docs/tasks/telemetry/kiali/kiali-workload.png b/content/docs/tasks/telemetry/kiali/kiali-workload.png new file mode 100644 index 0000000000..0d2d6963fe Binary files /dev/null and b/content/docs/tasks/telemetry/kiali/kiali-workload.png differ