KubeDiagrams Documentation

KubeDiagrams is a tool for generating Kubernetes architecture diagrams from various sources, including:

• Kubernetes manifest files
• Kustomization files
• Helm charts
• Helmfile descriptors
• Actual cluster state

It supports a wide range of output formats such as D2, DOT, draw.io, GIF, JPEG, Mermaid, PDF, PNG, SVG, and TIFF. Key features include support for built-in and custom Kubernetes resources, customizable resource clustering, and an interactive diagram viewer.

A dedicated plugin is available for JetBrains IDEs to integrate KubeDiagrams functionality directly into your development environment.

Download it from the JetBrains Marketplace.

While KubeDiagrams automatically generates diagrams from manifests, Helm charts, or cluster state, you can declaratively add custom elements (clusters, nodes, and edges) to your diagrams. This allows you to represent external infrastructure (e.g., AWS, external users) alongside your Kubernetes resources.

Custom diagram definitions are written in .kd files. Examples of custom diagram usage can be found in the examples/ directory (e.g., examples/wordpress/custom_diagram.kd).

To visualize a live cluster, first export your Kubernetes resources (including all, service accounts, config maps, secrets, PVCs, PVs, and storage classes) to a YAML file, then pass that file to kube-diagrams.

1. Export resources:

$ kubectl get all,sa,cm,secret,pvc,pv,sc -o=yaml > namespace_default.yml

2. Generate diagram:

$ kube-diagrams namespace_default.yml

You can generate Kubernetes architecture diagrams for specific Helm charts by running the provided generation script. This example demonstrates how to process charts like cert-manager, elasticsearch, kibana, fission-all, and jenkins.

$ ./generate.sh

If you prefer not to use Docker, you can set up the backend and frontend manually.

Backend Setup

Requires Python 3.8+, pip, and venv.

1. cd backend
2. python3 -m venv venv
3. source venv/bin/activate (Windows: venv\Scripts\activate)
4. pip install -r requirements.txt
5. python3 app.py (Runs on http://localhost:5000)

Frontend Setup

Requires Node.js 18+ and npm.

1. cd frontend
2. npm install (or npm ci)
3. npm run dev (Runs on http://localhost:5173)

To generate the Kubernetes architecture diagrams for the TeaStore example, run the provided generation script from your terminal. This will produce diagrams for both the TeaStore manifests and the TeaStore Helm Chart, including customized versions.

$ generate.sh

By default, KubeDiagrams represents each workload as a single graphical node. To visualize the internal structure of workloads—including pods, volumes, containers, mounted volumes, and referenced config maps or secrets—you must use a specific configuration file with the -c flag.

Use the following commands to generate diagrams with internal workload structures:

For Kubernetes manifests:

kube-diagrams -c inside-workloads.kdc <your manifests>

For Helm charts:

helm-diagrams -c inside-workloads.kdc <URL of your Helm chart>

The following command-line tools must be installed and available in your system PATH for the web application to function correctly:

• kube-diagrams/helm-diagrams: Required for generating diagrams from Kubernetes manifests and Helm charts.
• helmfile: Required specifically for the Helmfile tab functionality.

To verify the installation and functionality, follow these steps:

1. Start both the backend and frontend servers.
2. Navigate to http://localhost:8080 (if using Docker) or http://localhost:5173 (if running manually).
3. Select the Manifest tab.
4. Load an example (e.g., "Redis StatefulSet").
5. Click Generate Diagram.
6. Verify the diagram is generated and can be downloaded.

You can view and manipulate Kubernetes diagrams interactively using the dot_json format.

1. Export your diagrams to dot_json format:

   kube-diagrams examples/wordpress/*.yaml -o wordpress.dot_json

2. Open the interactive viewer:

   open interactive_viewer/index.html

3. Load your wordpress.dot_json file in the browser.

Features:

• Zoom in/out.
• View tooltips for clusters, nodes, and edges.
• Open/close clusters.
• Interactively move clusters and nodes.
• Filter displayed resource kinds.
• Save diagrams as PNG or JPG images.

Once your Kubernetes cluster (e.g., Minikube) is running with the required addons, you can generate architecture diagrams by executing the provided generation script.

$ ./generate.sh