Visualizing Cloud-native Applications with KubeDiagrams
Philippe Merle, Fabio Petrillo
TL;DR
The paper addresses the challenge of maintaining accurate, up-to-date architectural views for cloud-native Kubernetes deployments. It introduces KubeDiagrams, an open-source tool that automatically generates semantically faithful diagrams from manifests or live cluster state, supporting 47 resource kinds and multiple IaC inputs. Key contributions include the tool's architecture, visual semiotics, extensibility, and real-world case studies, plus a comparative landscape and practitioner feedback. The work demonstrates that automated, scriptable visualization integrated with CI/CD can improve onboarding, debugging, and compliance in DevOps workflows.
Abstract
Modern distributed applications increasingly rely on cloud-native platforms to abstract the complexity of deployment and scalability. As the de facto orchestration standard, Kubernetes enables this abstraction, but its declarative configuration model makes the architectural understanding difficult. Developers, operators, and architects struggle to form accurate mental models from raw manifests, Helm charts, or cluster state descriptions. We introduce KubeDiagrams, an open-source tool that transforms Kubernetes manifests into architecture diagrams. By grounding our design in a user-centered study of real-world visualization practices, we identify the specific challenges Kubernetes users face and map these to concrete design requirements. KubeDiagrams integrates seamlessly with standard Kubernetes artifacts, preserves semantic fidelity to core concepts, and supports extensibility and automation. We detail the tool's architecture, visual encoding strategies, and extensibility mechanisms. Three case studies illustrate how KubeDiagrams enhances system comprehension and supports architectural reasoning in distributed cloud-native systems. KubeDiagrams addresses concrete pain points in Kubernetes-based DevOps practices and is valued for its automation, clarity, and low-friction integration into real-world tooling environments.