First, Some Concepts You Need To Know
Within Istio, there are several basic concepts one must know about when dealing with how to visualize a mesh. I will (very briefly) describe these concepts here because without understanding these concepts the Kiali graphs I am going to show will have some nuances that you may not fully understand.
First there is the concept of a workload. A workload can be, for example, a pod in your OpenShift cluster. Workloads, as the name suggests, actually perform the work within a mesh (e.g. process HTTP requests and return HTTP responses).
Next is the concept of a service. A service is nothing more than a named endpoint that requests are sent to. A service does not actually do any work, but instead requests sent to a service are routed to a workload to perform the actual work necessary to process that service’s requests. A service can route to more than one workload, and a workload can process requests for one or more services.
Finally, we have the concept of an app. An app is made up of nothing more than workloads that have an “app” label applied to them (the app name is the value of the app label). Apps are versioned by another label called “version”. So if your workload (e.g. OpenShift pod) has a label “app=details” with another label “version=v1” then you have what Kiali calls a “versioned app” whose name is “details v1”.
With all of those concepts in mind, one interesting thing to note is that it is not trivial to try to draw a graph showing service-to-service links. It is more correct to draw workload-to-workload (or app-to-app) links. The Istio Policies and Telemetry Working Group wrote a nice document explaining the issues — if interested, read “The Problem” section of this design document.
The Example Service Mesh
In the examples I show below, what is being graphed is the Istio Bookinfo example application. I added one additional thing to this example — I told Istio to inject a fault in some (but not all) requests to the “details” service. What this means is that some requests to the “details” service will never make it to any “details” workload. This simulates something like a network error, for example the client (in this case “productpage”) sending requests to the “details” service will occasional get an error response because some requests never get to a workload that can process the requests.
Now that I’ve given you some background, let me show the different ways Kiali can graph a mesh.
The first graph type that Kiali can visualize is the “workload” graph. This shows every workload in your service mesh. This type of graph ignores the metadata associated with the workloads (in other words, it does not use the “app” or “version” labels), thus you can still use Kiali to visualize your mesh even if you do not wish to use metadata labels like “app” on your workloads.
Workloads are denoted with the “circle” nodes. The “diamond” represents a source of traffic coming into the mesh (in this case, it represents my browser making direct requests into the Bookinfo “productpage-v1” workload).
Notice the “productpage-v1” workload is red with the red edge going from that workload to the “details” service (services are denoted by triangles) — this indicates there are errors occurring here. I bring your attention to the oddity of the green edge going from “productpage-v1” to the “detail” workload. It seems odd that two edges would represent requests going to the same “details” — but if you think back to the definitions of “service” and “workload” I mentioned earlier, this really is not odd at all. The requests made by “productpage-v1” that were successful actually made it to the workload “details-v1” which explains the green edge. However, the requests that failed never made it to any details workload — the only thing that can be known about those failed requests is that they were sent to the “details” service. Because these requests never made it to the “details-v1” workload, it would be incorrect for Kiali to have a red edge from “productpage-v1” to “details-v1” — instead, Kiali visualizes this error condition by adding a separate service node (denoted with a triangle) labeled “details” and have the red edge from “product-v1” to that service node “details”.
Injecting Service Nodes
But it is still odd to see two nodes that seem related (“details” and “details-v1”) but not have them somehow grouped or connected to each other on the graph. And notice also this graph does not, by default, show any of the other services (such as “reviews” or “ratings” or “productpage”). This graph only shows service nodes when they are responsible for errors. This brings me to a new feature Kiali just implemented, and that is the ability to inject service nodes (the triangles) directly in the service mesh graph. If you wish to see your services visualized, Kiali can now do this. It will make the graph more noisy, but it will provide you with a potentially more easily understood graph:
Notice this now shows all the different services within the Bookinfo application (“productpage”, “reviews”, “ratings”, “details”). But now notice that there is a single edge leaving “productpage-v1” to “details” (there is not a second edge leaving “productpage-v1” going to “details-v1” as there was before). The red edge indicates there are some errors happening here, but we can also see at least some requests made it to the “details-v1” workload (the green edge from “details” to “details-v1” tells us this). This indicates that “productpage-v1” is encountering some errors when sending requests to the “details” service, but some of those requests are successfully making their way to the “details-v1” workload.
The Bookinfo example is very simplistic, so the usefulness of this feature is not in full view. But consider the case when a workload has multiple services in front of it or when a service routes requests to multiple workloads. Injecting service nodes into your graph when either or both of those are the case will provide you with very interesting and useful service mesh visualizations.
Versioned App Graph
If you opt to add those “app” and “version” metadata labels to your workloads, Kiali can visualize your graph utilizing that metadata. This allows Kiali to show you a graph in a way that is more aligned to the way you want to group your workloads (since it is you that define what apps your workloads belong to, and what their versions are).
Kiali provides what is called a “versioned app” graph. In this graph, rather than show workload nodes, it will show you your “apps”. If you have more than one version of an app, Kiali will group your versioned apps in a composite “version box”.
The square nodes denote your apps. Notice the Bookinfo example has three versions of the “reviews” app — thus Kiali renders a composite “reviews” box with each of the three versioned apps in that box.
The names of the app nodes are not actually workload names (though they look similar, only because the Bookinfo example sets the names of its workloads to values that are very similar to the app and version labels). The app node names are values of the “app” label and “version” label concatenated together — e.g. “productpage v1” app node means this represents the workloads who app label has a value of “productpage” and version label of “v1”.
You will again notice the “details” service (the triangle) due to the errors that were injected in the requests. Again, as before, Kiali can be told to inject service nodes into this versioned app graph (just as can be done in the workload graph shown earlier) — this will help show you a more fully detailed, but perhaps more noisy, graph:
Once again you can see how injecting service nodes in the graph makes visualizing this graph potentially more easily understood because there is now a single edge from “productpage v1” app to the “details” service (which is red to indicate some errors are occurring) but the edge from “details” service to the “details v1” app is green to denote some requests going to the “details” service are successfully being processed by the “details v1” app.
Finally, the third type of graph Kiali can visualize is an app graph. This is similar to the versioned app graph, except Kiali will aggregate all versions of an app into a single app node. So here you will notice there is no box grouping the three “reviews” versioned app nodes — there are no versioned app nodes in a Kiali app graph. Only apps are visualized, with all versions of an app aggregated into a single app node (as you see here with the single “reviews” app node which represents the three versions of that app):
The utility of this graph type is that it helps reduce the size of your graph and thus may make large meshes more easily viewed on screen.
And, just as before, we can inject service nodes into app graphs, thus showing services as well as apps in the graph:
The Kiali team is still refining these graph features. If you wish to provide suggestions, feedback, or want to help further develop Kiali, feel free to contribute!