Architecture diagrams play an important role in the documentation of a system.

When I need to draft a solution, my favorite tool is draw.io1. It is simple to use, it has a field to search and include symbols, and it integrates with Google Drive.

Recently I had to revisit one of those drafts to create some documentation for a small system that was already deployed in Kubernetes. Since the initial draft, the system suffered some updates and I was not in the mood to redesign it in There must be a better way… 💭 And there is.


My first search result was k8sviz by Masaki Kimura. By quickly reading the README, it seemed to be easy to install and run, so I gave it a try.

k8sviz is a tool to generate Kubernetes architecture diagrams from the actual state in a namespace.

I also noticed this tool’s diagrams are generated with Graphviz, the same technology PlantUML2 uses.


There are two installation options - Bash and Go. I opted for the Go version:

git clone
cd k8sviz
make build

You must be able to use it by running:

./bin/k8sviz -h

However, if you prefer to access the binary from a different path in your system, you need to move both the binary and the icons' folder to a path such as $HOME/.local/bin, for example:

cp bin/k8sviz ${PATH_TO_INSTALL}
cp -r icons ${PATH_TO_INSTALL}

Usage and Results

For demo purposes, I will use a standard minikube cluster and choose to visualize the kube-system namespace:

minikube start
kubectl get all -n kube-system

The cluster is up and running and I can see a Deployment, a DaemonSet, a Service, and some Pods.

Now let’s run k8sviz:

k8sviz -n kube-system -kubeconfig /Users/nuno/.kube/config -o k8sviz_test.png -t png

As a result, we obtain the following output file:


In case you want to see more results, take a look at the examples section of k8sviz README.

  1. was rebranded to ↩︎

  2. PlantUM is a tool that allows the creation of sequence, usecase, class, and other diagrams as code. ↩︎