Visualising the architecture of cloud-native applications with KubeDiagrams

What led to the development of KubeDiagrams?

This software originated from a small Python script that was developed for Hugo Monfleur's thesis, a member of the Spirals project team. It was used to visualise the results produced by his toolchain.

I later used it to visualise an application we were developing as part of the ANR SCALER project, and presented it at a seminar. The generated diagram caught the interest of an industrial colleague, who wanted to use the script themselves. That encouraged me to extract it and turn it into a fully standalone tool. 

What was the reaction to KubeDiagrams when you made it public?

We shared it on the r/Kubernetes forum on Reddit. The reaction was immediate. Within just a few weeks, the project went from 20 to 100 stars on GitHub, which is the equivalent of “favourites” on that platform. This showed that many people were eager to see how it was going to evolve. Ten months later, it has reached almost 1,800 stars and has already been downloaded over 12,000 times. It’s a remarkable growth, going way beyond that of many other research-based projects.

But besides the numbers, what surprised us most was just how involved the community was. Very quickly, developers from all over the world began sharing their feedback on social media, writing blog articles, suggesting uses we hadn’t considered, and even contributing directly to the code on a voluntary basis. 

What needs does this software address?

It operates within Kubernetes, an ecosystem that develops and manages cloud-native applications (designed for the Cloud). Originally developed by Google in the early 2010s, this system has since become an industry standard. Since its public release in 2013, Kubernetes has been used across a wide range of fields, including finance, healthcare, e-commerce, and scientific research.

However, the system can be difficult to grasp at first. Applications are described using configuration files, and the final outcome can differ from what was initially intended in the development phase. Without the right tools, it becomes challenging to verify whether the deployed architecture truly aligns with the original intention. This is precisely what KubeDiagrams offers: the ability to generate a visual representation of an application’s architecture. 

How is this graphic representation generated?

Kubernetes uses a specific language based on a declarative model. In the development phase, a set of ‘resources’, that is, the software components required by the application, is defined. Large-scale applications can include several hundred such resources. Each one is identified by a ‘type’ and a version number. In a given application, they may also be referenced by a name and various metadata fields.

KubeDiagrams collects all this information and turns it into a diagram. Resources appear as 'nodes’, their relationships are represented by links, and related resources are grouped into coloured sets. Icons, colours, and lines then help users quickly distinguish different affiliations. All of this is fully customisable: users can adjust the representation, hide certain default behaviours, add additional resource types, etc.

What are the practical applications of this tool?

This type of visualisation is useful at every stage of a project. During the design phase, it can help a developer verify that what’s described actually matches what they had in mind. It also makes it easier to compare different solutions or identify potential inconsistencies. Once the application is in operation, KubeDiagrams can be used to take ‘snapshots’ of its architecture at a given point in time and track changes over time. It can also be used as part of an audit process. 

For example, one of the first users of KubeDiagrams told us they had discovered a flaw in one of their applications. It contained unnecessary resources: old pieces of code that had been forgotten and not removed. With the tool, this user was able to instantly spot the presence of unused code. Without a visual representation, this issue would most likely have gone unnoticed.

At this stage, what do you think about how KubeDiagrams has evolved?

Our first version was very simple and only supported a few Kubernetes resource types. KubeDiagrams now handles close to fifty resource types by default, along with numerous metadata fields. The project, now public on GitHub, benefits from external contributions, both from industry developers and trainees. 

What’s surprising about this project is that the process is the reverse of traditional research. Usually, scientific results are published first, which may eventually lead to the development of a software tool. With KubeDiagrams, it’s the opposite. We started by building a tool we needed ourselves, and research is now being conducted into its practical use cases.

Our first scientific paper on KubeDiagrams was presented at the VISSOFT conference in September 2025 in Auckland, New Zealand. Several other publications are currently being prepared. To support this, we’re collaborating with Fabio Petrillo, a researcher at ETS Montreal, to conduct comparative experiments and work on refining the visualisation methods.

What’s next?

Several projects are underway. First, we’re conducting a study to assess the impact of visual choices on diagram comprehension, in order to determine what actually helps developers and what, on the contrary, renders the process unnecessarily complicated. We’re also working on algorithms capable of automatically detecting and correcting certain architectural issues, when a resource is mislabelled for example.

In addition, we’re developing a website that will allow users to use KubeDiagrams through a web interface, without needing to install it locally. Finally, KubeDiagrams is in the running for a national award recognising open-source research software. Ultimately, our goal is for this to become a key tool for every Kubernetes developer.