Visualizing Your Mesh

This task shows you how to visualize different aspects of your Istio mesh.

As part of this task, you install the Kiali add-onand use the web-based graphical user interface to view service graphs ofthe mesh and your Istio configuration objects. Lastly, you use the KialiPublic API to generate graph data in the form of consumable JSON.

This task does not cover all of the features provided by Kiali.To learn about the full set of features it supports,see the Kiali website.

This task uses the Bookinfo sample application as the example throughout.

Before you begin

The following instructions assume you have installed istioctl and will use it to install Kiali.To install Kiali without istioctl, follow the Kiali installation instructions.

Create a secret

If you plan on installing Kiali using the Istio demo profile as described in the Istio Quick Start Installation Steps then a default secret will be created for you with a username of admin and passphrase of admin. You can therefore skip this section.

Create a secret in your Istio namespace with the credentials that you use toauthenticate to Kiali.

First, define the credentials you want to use as the Kiali username and passphrase:

$ KIALI_USERNAME=$(read -p 'Kiali Username: ' uval && echo -n $uval | base64)
$ KIALI_PASSPHRASE=$(read -sp 'Kiali Passphrase: ' pval && echo -n $pval | base64)

If you are using the Z Shell, zsh, use the following to define the credentials:

$ KIALI_USERNAME=$(read '?Kiali Username: ' uval && echo -n $uval | base64)
$ KIALI_PASSPHRASE=$(read -s "?Kiali Passphrase: " pval && echo -n $pval | base64)

To create a secret, run the following commands:

$ NAMESPACE=istio-system
$ kubectl create namespace $NAMESPACE

$ cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: kiali
  namespace: $NAMESPACE
  labels:
    app: kiali
type: Opaque
data:
  username: $KIALI_USERNAME
  passphrase: $KIALI_PASSPHRASE
EOF

Install via istioctl

Once you create the Kiali secret, followthe install instructions to install Kiali via istioctl.For example:

$ istioctl manifest apply --set values.kiali.enabled=true

This task does not discuss Jaeger and Grafana. Ifyou already installed them in your cluster and you want to see how Kialiintegrates with them, you must pass additional arguments to theistioctl command, for example:

$ istioctl manifest apply \
    --set values.kiali.enabled=true \
    --set "values.kiali.dashboard.jaegerURL=http://jaeger-query:16686" \
    --set "values.kiali.dashboard.grafanaURL=http://grafana:3000"

Once you install Istio and Kiali, deploy the Bookinfo sample application.

Running on OpenShift

When Kiali runs on OpenShift it needs access to some OpenShift specific resources in order to function properly,which can be done using the following commands after Kiali has been installed:

$ oc patch clusterrole kiali -p '[{"op":"add", "path":"/rules/-", "value":{"apiGroups":["apps.openshift.io"], "resources":["deploymentconfigs"],"verbs": ["get", "list", "watch"]}}]' --type json
$ oc patch clusterrole kiali -p '[{"op":"add", "path":"/rules/-", "value":{"apiGroups":["project.openshift.io"], "resources":["projects"],"verbs": ["get"]}}]' --type json
$ oc patch clusterrole kiali -p '[{"op":"add", "path":"/rules/-", "value":{"apiGroups":["route.openshift.io"], "resources":["routes"],"verbs": ["get"]}}]' --type json

Generating a service graph

• To verify the service is running in your cluster, run the following command:

$ kubectl -n istio-system get svc kiali

• To determine the Bookinfo URL, follow the instructions to determine the Bookinfo ingress GATEWAY_URL.

• 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:

$ curl http://$GATEWAY_URL/productpage

• If you installed the watch command in your system, send requests continually with:

$ watch -n 1 curl -o /dev/null -s -w %{http_code} $GATEWAY_URL/productpage

• To open the Kiali UI, execute the following command in your Kubernetes environment:

$ istioctl dashboard kiali

• To log into the Kiali UI, go to the Kiali login screen and enter the username and passphrase stored in the Kiali secret.

• 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:

Example Overview

• To view a namespace graph, click on the bookinfo graph icon in the Bookinfo namespace card. The graph icon is in the lower left ofthe namespace card and looks like a connected group of circles.The page looks similar to:

Example Graph

• To view a summary of metrics, select any node or edge in the graph to displayits metric details in the summary details panel on the right.

• To view your service mesh using different graph types, select a graph typefrom the Graph Type drop down menu. There are several graph typesto 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 versionsof the reviews app.

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 exampleshows the reviews group box that contains the three nodes that represents thethree versions of the reviews app.

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 youopt to not use those labels on your components, this is the graph type you will use.

Example Workload Graph

• The Service graph type shows a node for each service in your mesh but excludesall apps and workloads from the graph.

Example Service Graph

Examining Istio configuration

• To view detailed information about Istio configuration, click on theApplications, Workloads, and Services menu icons on the left menubar. The following screenshot shows information for the Bookinfo application:

Example Details

Creating weighted routes

You can use the Kiali weighted routing wizard to define the specific percentage ofrequest traffic to route to two or more workloads.

• View the Versioned app graph of the bookinfo graph.

  • Make sure you have selected Requests percentage in the Edge Labels drop down menuto see the percentage of traffic routed to each workload.

  • Make sure you have selected the Service Nodes check box in the Display drop down menuto view the service nodes in the graph.

Bookinfo Graph Options

• Focus on the ratings service within the bookinfo graph by clicking on the ratings service (triangle) node.Notice the ratings service traffic is evenly distributed to the two ratings workloads v1 and v2(50% of requests are routed to each workload).

Graph Showing Percentage of Traffic

• Click the ratings link found in the side panel to go to the service view for the ratings service.

• From the Action drop down menu, select Create Weighted Routing to access the weighted routing wizard.

Service Action Menu

• Drag the sliders to specify the percentage of traffic to route to each workload.For ratings-v1, set it to 10%; for ratings-v2 set it to 90%.

Weighted Routing Wizard

• Click the Create button to create the new routing.

• Click Graph in the left hand navigation bar to return to the bookinfo graph.

• Send requests to the bookinfo application. For example, to send one request per second,you can execute this command if you have watch installed on your system:

$ watch -n 1 curl -o /dev/null -s -w %{http_code} $GATEWAY_URL/productpage

• After a few minutes you will notice that the traffic percentage will reflect the new traffic route,thus confirming the fact that your new traffic route is successfully routing 90% of all trafficrequests to ratings-v2.

90% Ratings Traffic Routed to ratings-v2

Validating Istio configuration

Kiali can validate your Istio resources to ensure they follow proper conventions and semantics. Any problems detected in the configuration of your Istio resources can be flagged as errors or warnings depending on the severity of the incorrect configuration. See the Kiali validations page for the list of all validation checks Kiali performs.

Istio 1.4 introduces istioctl analyze which lets you perform similar analysis in a way that can be used in a CI pipeline.

Force an invalid configuration of a service port name to see how Kiali reports a validation error.

• Change the port name of the details service from http to foo:

$ kubectl patch service details -n bookinfo --type json -p '[{"op":"replace","path":"/spec/ports/0/name", "value":"foo"}]'

• Navigate to the Services list by clicking Services on the left hand navigation bar.

• Select bookinfo from the Namespace drop down menu if it is not already selected.

• Notice the error icon displayed in the Configuration column of the details row.

Services List Showing Invalid Configuration

• Click the details link in the Name column to navigate to the service details view.

• Hover over the error icon to display a tool tip describing the error.

Service Details Describing the Invalid Configuration

• Change the port name back to http to correct the configuration and return bookinfo back to its normal state.

$ kubectl patch service details -n bookinfo --type json -p '[{"op":"replace","path":"/spec/ports/0/name", "value":"http"}]'

Service Details Showing Valid Configuration

Viewing and editing Istio configuration YAML

Kiali provides a YAML editor for viewing and editing Istio configuration resources. The YAML editor will also provide validation messageswhen it detects incorrect configurations.

• Create Bookinfo destination rules:

Zip

$ kubectl apply -f @samples/bookinfo/networking/destination-rule-all.yaml@

• Click Istio Config on the left hand navigation bar to navigate to the Istio configuration list.

• Select bookinfo from the Namespace drop down menu if it is not already selected.

• Notice the error messages and the error and warning icons that alert you to several configuration problems.

Istio Config List Incorrect Configuration Messages

• Hover over the error icon in the Configuration column of the details row to see additional messages.

Istio Config List Incorrect Configuration Tool Tips

• Click the details link in the Name column to navigate to the details destination rule view.

• Notice the messages and icons that alert you to several validation rules that failed.

Istio Configuration Details View Showing Errors

• Click the YAML tab to view the YAML for this Istio destination rule resource.

• Notice the color highlights and icons on the rows that have failed validation checks.

YAML Editor Showing Validation Errors and Warnings

• Hover over the yellow icon to view the tool tip message that informs you of the validation check that triggered the warning.For more details on the cause of the warning and how to resolve it, look up the validation warning message on theKiali Validations page.

YAML Editor Showing Warning Tool Tip

• Hover over the red icon to view the tool tip message that informs you of the validation check that triggered the error.For more details on the cause of the error and how to resolve it, look up the validation error message on theKiali Validations page.

YAML Editor Showing Error Tool Tip

• Delete the destination rules to return bookinfo back to its original state.

$ kubectl delete -f samples/bookinfo/networking/destination-rule-all.yaml

About the Kiali Public API

To generate JSON files representing the graphs and other metrics, health, andconfiguration information, you can access theKiali Public API.For example, point your browser to $KIALI_URL/api/namespaces/graph?namespaces=bookinfo&graphType=appto 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 thestandard Istio metric configuration. It also makes Kubernetes API calls toobtain additional details about your services. For the best experience usingKiali, use the metadata labels app and version on your applicationcomponents. As a template, the Bookinfo sample application follows thisconvention.

Cleanup

If you are not planning any follow-up tasks, remove the Bookinfo sample application and Kiali from your cluster.

• To remove the Bookinfo application, refer to the Bookinfo cleanup instructions.

• To remove Kiali from a Kubernetes environment, remove all components with the app=kiali label:

$ kubectl delete all,secrets,sa,configmaps,deployments,ingresses,clusterroles,clusterrolebindings,customresourcedefinitions --selector=app=kiali -n istio-system

See also

Visualizing Metrics with Grafana

This task shows you how to setup and use the Istio Dashboard to monitor mesh traffic.

Mixer and the SPOF Myth

Improving availability and reducing latency.

Mixer Adapter Model

Provides an overview of Mixer's plug-in architecture.

Collecting Logs

This task shows you how to configure Istio to collect and customize logs.

Collecting Metrics

This task shows you how to configure Istio to collect and customize metrics.

Collecting Metrics for TCP services

This task shows you how to configure Istio to collect metrics for TCP services.