Generate Kubernetes Architecture Maps Directly from Your Cluster

Maintaining accurate documentation for a Kubernetes cluster is hard. If you’re a DevOps engineer, you’ve probably felt the pain: an architecture diagram drawn a month ago might as well be an year old today. We deploy new microservices, tweak existing ones, scale things up and down – and meanwhile our diagrams and docs grow stale. Keeping those architecture diagrams in sync across dev, staging, and prod environments can feel like a never-ending chore.

I used to spend hours manually updating diagrams (or worse, skipping updates entirely). Sound familiar? One day you realize the “current” cluster diagram on the wiki doesn’t match reality at all. Perhaps a service is missing, or it shows an outdated database that was replaced last sprint. This drift isn’t just an annoyance – it can confuse teammates, hinder onboarding, and complicate troubleshooting when you’re already under pressure.

The Kubernetes Documentation Dilemma

In a dynamic Kubernetes environment, change is constant. New deployments, config maps, ingress rules… every change threatens to invalidate your documentation. Many of us resort to tools like Draw.io, Lucidchart, or manually crafted diagrams. But manually drawing each connection or updating every object across multiple environments (dev/staging/prod) quickly becomes unmanageable. It’s like trying to hit a moving target – by the time you finish updating a diagram, something has likely changed again.

As one Kubernetes blogger noted, explaining your cluster by flipping through YAMLs and piecing together services across namespaces gets messy – exactly the kind of problem begging for automation. We need a source of truth that’s tied to the live state of our clusters. Ideally, a way to capture a snapshot of the actual running environment and produce an up-to-date architecture diagram on the spot.

Discovery: An Auto-Diagramming Solution Appears

Not long ago, I stumbled upon an open-source tool that felt like a breath of fresh air. It’s called KubeDiagrams (yes, with an "s") – and it does exactly what I always wished for. KubeDiagrams automatically generates architecture diagrams of your Kubernetes cluster by querying the real cluster state (or by reading your manifests/Helm charts). In other words, it can draw your cluster for you, on demand, based on what’s actually deployed. No more manually tweaking boxes and arrows whenever something changes!

The first time I tried KubeDiagrams, it felt almost magical. Instead of manually gathering information, I ran a single command and out popped a clean diagram showing all my services, deployments, persistent volumes, and how they relate. It solved the “outdated diagram” problem in one swoop by always reflecting the live environment. Suddenly, maintaining separate diagrams for dev, staging, and prod didn’t seem so impossible – I could just generate each from its cluster state whenever I needed.

So what exactly is KubeDiagrams? In short, it’s a CLI tool (and Python library) that visualizes Kubernetes resources. Created by Philippe Merle, it’s open-source on GitHub (philippemerle/KubeDiagrams). Under the hood, it reads Kubernetes manifests or queries the cluster API (via kubectl) to collect all the resources and then renders an architecture diagram. The output can be an image (PNG by default, but other formats like SVG or PDF are supported) that illustrates your cluster’s components and their relations.

Unlike static drawings, KubeDiagrams pulls data from the real source (your YAML or your running cluster). That means what you see in the diagram is what’s truly deployed right now – no guessing, no stale info. If you update your deployment or add a new service, just regenerate the diagram and it’s captured. It’s the documentation that updates itself.

How KubeDiagrams Works (and Why It’s Awesome)

KubeDiagrams is straightforward to use and integrates seamlessly into a DevOps workflow. There’s no fancy UI to spin up or complex configuration. If you’re comfortable running kubectl commands, you’re already 90% of the way there. Here’s how it works and its key features:

Real-Time Cluster Snapshots: You can generate a diagram from a live cluster by piping Kubernetes data into KubeDiagrams. For example, to diagram the current state of your default namespace, you can simply run:

kubectl get all -o yaml | kube-diagrams -o cluster-diagram.png -

This one-liner fetches all resources in the namespace (kubectl get all) and pipes the YAML into KubeDiagrams, which then outputs an up-to-date cluster-diagram.png. Need the whole cluster? Just add --all-namespaces to that command and KubeDiagrams will capture everything. The result is a snapshot of your environment’s architecture at that moment in time. No more manually drawing what’s already running!

Broad Kubernetes Object Support: One thing I worried about initially was, will it capture all the kinds of resources I have? The answer is yes – KubeDiagrams supports a wide array of Kubernetes objects out of the box. Deployments, Pods, Services, ConfigMaps, Ingresses, PersistentVolumes, Autoscalers, DaemonSets, CronJobs… you name it. In fact, as of the latest version it covers most built-in Kubernetes resources (47 kinds and counting) and even Custom Resource Definitions (CRDs) for those using operators or extensions. This means your diagram isn’t missing pieces; everything from core components to custom ones can be visualized.

Logical Grouping for Clarity: In a complex cluster, a raw dump of all objects could be overwhelming. KubeDiagrams helps by grouping related resources visually. By default it can cluster resources by namespace, and it also leverages labels to group components of an application together. For example, all objects with the same app label might be drawn within one box labeled “Application: my-app”, and separated by namespace. This visual grouping makes the diagram easier to read, so you see higher-level systems rather than a flat wall of icons. It’s especially useful when you have multiple microservices or teams sharing a cluster.

Standard Kubernetes Icons: The diagrams produced use recognizable Kubernetes icons for each resource type. Services, deployments, pods, volumes, etc., each have their own icon, so it’s intuitive to identify what’s what at a glance. This adheres to the style of official K8s architecture diagrams. You don’t have to invent symbols – it’s all consistent and clear.

Multiple Sources – Manifests, Helm, or Live Cluster: Flexibility is a big win here. You aren’t limited to only running it against a live cluster. You can point KubeDiagrams at static YAML manifest files (even multiple files at once), at Kustomize configurations, or directly at a Helm chart. For instance, if you have a Helm chart you’re evaluating, you can generate its diagram before deploying it using the provided helm-diagrams command. This flexibility means KubeDiagrams is useful in both design (visualizing what you plan to deploy) and operational phases (visualizing what is running now). Whether your source of truth is Git (IaC manifests) or the cluster’s current state, KubeDiagrams has you covered.

Simple Setup, No Heavy Tools: Getting started with KubeDiagrams is almost effortless. It’s distributed as a Python package and as a Docker container. You can install it with a single pip command (pip install KubeDiagrams) or run it via Docker (docker run philippemerle/kubediagrams ...) without installing anything on your machine. There’s no web interface or server component to maintain – just a command-line tool that you invoke when you need it. This simplicity means you can easily script it or integrate it into CI pipelines. For example, you might have a pipeline job that regularly generates updated diagrams from your clusters and publishes them to your documentation site.

Output in Multiple Formats: By default, you’ll get a PNG image, but KubeDiagrams can also output SVG (vector graphics), PDF, JPG, or even GraphViz dot formats. This is handy depending on how you want to use the diagram – SVG for embedding in web pages with infinite zoom, PDF for slides, etc. It’s a small detail, but it shows the tool is designed to fit various workflows.

Figure: Example auto-generated architecture diagram by KubeDiagrams for the official WordPress+MySQL tutorial. Services (svc) connect to deployments (deploy), which use Persistent Volume Claims (pvc) and Secrets. Resources are grouped by Application (here everything labeled “wordpress” is grouped in one box) and by Namespace (default). The live state is reflected accurately – you can see both the WordPress frontend and MySQL backend components and their connections without manually drawing any of it.

By combining real-time data with smart grouping and rich support for Kubernetes resources, KubeDiagrams delivers diagrams that are both accurate and instantly informative. The days of chasing stale documentation are over – you can regenerate a fresh diagram whenever you need clarity.

Real-World Use Cases: Where KubeDiagrams Shines

It’s all well and good to have a nifty tool, but you might be wondering how this fits into your day-to-day as a DevOps engineer. Here are some practical scenarios where KubeDiagrams proves invaluable:

Keeping Environments in Sync: If your team maintains separate dev, staging, and production clusters, you’ve likely struggled to keep track of their differences. With KubeDiagrams, you can generate a diagram for each environment’s cluster state on demand. Put these diagrams side by side and you have an immediate visual diff of what’s deployed where. For example, you might spot that a new microservice is present in staging but hasn’t yet been promoted to prod, or that prod has an extra monitoring component not in dev. No need to manually update three separate diagrams; just run the tool against each cluster and compare. This ensures consistency across environments and makes reviews a breeze.
Onboarding and Knowledge Sharing: When a new engineer joins the team or when you need to brief stakeholders on the system architecture, an updated diagram is worth a thousand words. Instead of handing them a stale chart (or worse, expecting them to read dozens of YAML files), you can generate the latest architecture map of the system. This live diagram helps newcomers immediately grasp how the services, databases, and integrations in your cluster fit together. It’s also great for cross-team knowledge sharing – e.g., showing the Ops team how a particular application is architected in Kubernetes without them having to dive into kubectl themselves.
Troubleshooting & Incident Response: During an outage or firefight, having a clear picture of the system is crucial. An automatically generated diagram can quickly remind you of all the components involved. For instance, if a web application is down, the diagram will show if it relies on a particular ConfigMap, or which microservice connects to which database service. Visualizing the relationships makes it easier to pinpoint what might be broken. As one community member noted, a clear diagram makes troubleshooting and planning much easier in complex setups. Instead of guessing connections, you can see them. This can surface misconfigurations too – e.g., noticing that a Service has no corresponding Deployment (and thus no pods) because the diagram shows an orphan Service icon.
Architecture Reviews & Audits: Suppose you’re about to deploy a major new Helm chart or make significant changes. Before you apply it live, you can use KubeDiagrams to review the architecture. Run it on the Helm chart templates or Kustomize manifests to get a visual of what will be created. This is incredibly useful for catching unexpected components. Maybe the chart is going to install an extra LoadBalancer service you weren’t aware of, or multiple namespaces – seeing the diagram can highlight these things before they hit your cluster. Similarly for audits, if you need to provide documentation of “what’s running where” to an external auditor or another team, you can generate the diagrams as evidence of your deployment topology at a given time.
Continuous Documentation in CI/CD: You can integrate KubeDiagrams into your CI/CD pipeline to keep diagrams continuously up to date. For example, as part of a nightly job or a release pipeline, generate the latest cluster diagram and publish it to an internal wiki or repo. This way, documentation is never far behind the actual state. If anyone is unsure about the current architecture, they can refer to the latest generated diagram with confidence that it’s current. No more wading through outdated Confluence pages or Google Docs diagrams from last quarter.

In all these scenarios, the key benefit is accuracy with minimal effort. You get the insight of a detailed diagram without the labor of manually creating it. And because it’s quick to regenerate, the diagram becomes a living document rather than a historical artifact.

Getting Started with KubeDiagrams

Ready to give it a try? Getting started is super easy:

Install KubeDiagrams: You have two main options to install:
- Via pip (Python): Ensure you have Python 3 installed, then run pip install KubeDiagrams. This will install the kube-diagrams CLI along with its dependencies (like PyYAML and the Diagrams library).
- Via Docker: If you prefer not to install anything locally, you can use the Docker image. For example: docker pull philippemerle/kubediagrams. Then invoke the tool with docker run when needed (as shown below). This container approach is also great for CI pipelines.
Generate Your First Diagram: Decide what you want to visualize:
- Live cluster (current state): Use kubectl to fetch resources and pipe into KubeDiagrams. For example, to diagram everything in the “default” namespace:

kubectl get all -o yaml | kube-diagrams -o mycluster.png -

This will create mycluster.png in your working directory. Open it up, and you should see all the Deployments, Pods, Services, etc., laid out. If you want a whole cluster overview (all namespaces), add the --all-namespaces flag as mentioned earlier. You can also target a specific namespace by adding -n your-namespace in the kubectl command.

Helm chart or manifest files: If you have YAML files or a Helm chart, you can generate a diagram without a running cluster. For Helm, there’s the convenient helm-diagrams command included. For example:

helm-diagrams https://charts.jetstack.io/cert-manager

This fetches the Helm chart for Cert-Manager and generates its architecture diagram (so you can inspect what it will deploy). If you have a local chart or manifest, you could do helm template ./mychart | kube-diagrams -o mychart.png or simply kube-diagrams -o output.png my-manifest.yml. KubeDiagrams will parse the input manifests and create the diagram accordingly.

Customizing output: By default, the output is PNG. You can change the format with the -f flag (e.g., -f svg for an SVG vector graphic, or -f pdf for a PDF file). You can also provide a custom configuration file if you want to tweak how certain resources are displayed, but for most cases the defaults work great.

Explore the Diagram: Once generated, open the diagram file. You’ll likely see each namespace enclosed in its own box (unless you used the --without-namespace option to flatten it, and within those, groupings by application if your labels are set. Take a moment to appreciate that you didn’t have to draw any of this by hand! All the icons and connections are auto-arranged. If something looks off, it might reflect an actual issue in the setup (e.g., a missing link or mislabelled app). In my experience, seeing everything laid out visually can even reveal insights that are hard to spot in raw YAML or kubectl get outputs.
Iterate and Automate: Now that you have the tool working, consider integrating it into your routine. Maybe update your README with a recent architecture diagram by running KubeDiagrams periodically. Or add it to a script that developers can run before merging major changes (“update the arch diagram”). The fact that it’s so easy to run means it can actually be kept up to date, unlike those old manually-crafted diagrams.

Getting hands-on with KubeDiagrams is straightforward, and the value becomes apparent immediately when you see your own cluster drawn out in front of you with minimal effort.

Final Thoughts

What started as a frustrating documentation chore can now be largely automated. KubeDiagrams has become a handy addition to my DevOps toolkit. It turns the current state of a Kubernetes cluster into a visual architecture diagram with a single command, which is incredibly powerful for maintaining accurate documentation and understanding complex systems at a glance. By addressing the root problem of documentation drift, it allows us to focus on the actual engineering work rather than constantly updating diagrams.

If you’re interested in trying it out, check out the KubeDiagrams GitHub repository – it’s open source, well-documented, and actively maintained. You’ll find more examples of diagrams and detailed instructions there. I encourage you to give it a spin on your own cluster or even on a simple dev namespace. It’s oddly satisfying to see a fresh diagram that you know is 100% accurate because it’s generated from the source of truth.

No more guessing, no more outdated drawings stuffed in a corner of your wiki. With KubeDiagrams, your Kubernetes environment’s documentation can finally keep up with the speed of your deployments. So next time someone asks “do we have an updated architecture diagram?”, you can confidently say: “Give me one minute!” and deliver an up-to-date diagram, hassle-free.

Happy diagramming, and may your Kubernetes adventures be ever well-documented!