Docs & Code Guide

Kubernetes manifest diagram: render Helm and Kustomize first, then diagram the effective state

Nobody runs the YAML you keep in the repo. Helm charts and Kustomize overlays are templates for manifests, and the values file or overlay you apply decides how many replicas exist, whether the ingress is enabled, and which sidecars ride along. A diagram generated from raw templates draws a system that never ran. Render first, diagram the rendered output, and rerun the render when the chart or overlay changes.

Try it free
8 min readFor platform teams whose deployments live in Helm charts or Kustomize overlays

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

241/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Render first: the effective manifests are the diagram input

helm template renders a chart with a given values file into plain manifests, exactly what helm install would send to the API server. kubectl kustomize, or kustomize build, does the same for an overlay: base plus patches, resolved. Everything a diagram needs, the Deployments, Services, Ingresses, and their wiring, exists only after this step, because the prod overlay and the dev overlay disagree about it by design.

Render with the same values and overlay your deploy pipeline uses. A diagram built from default values documents the chart author's demo, not your platform.

# Helm: render the chart exactly as the release would run
helm template payments ./charts/payments -f values/prod.yaml > effective.yaml

# Kustomize: build the overlay that production applies
kubectl kustomize overlays/prod > effective.yaml

# The running truth, straight from the cluster
kubectl get deploy,sts,svc,ingress -n payments -o yaml

Repo or cluster: pick your truth deliberately

With GitOps in place, Argo CD or Flux reconciles the repo into the cluster, and the two are supposed to converge. When sync is green they do, and the rendered repo manifests are the better diagram source: they are versioned, reviewable in a PR, and available to CI without cluster credentials. When someone has been kubectl-editing in production, or an Argo app sits in OutOfSync, the repo lies, and kubectl get -o yaml is the only honest answer, defaults filled in by the API server included.

A workable rule: generate the standing diagram from rendered repo manifests, because that is the state your team reviews and intends. Reach for the cluster query when investigating drift, and treat any difference between the two pictures as a finding in itself.

Namespaces as zones, selectors as edges

Namespaces map naturally onto diagram zones, and a multi-namespace map with zone boundaries answers the first question every reader has: what talks across the boundary. Inside a zone, Deployments and StatefulSets are the workload nodes, with StatefulSets and their PersistentVolumeClaims marking where the state lives.

The subtle edges are the label selectors. A Service does not name its pods; it selects them, and the edge exists because the selector app=api matches the labels in a Deployment's pod template. That indirection is invisible in any single manifest, which is exactly why it belongs on a diagram: it is the wiring a newcomer cannot see by reading files one at a time. Ingress to Service edges, and ConfigMap and Secret mounts into workloads, complete the picture.

The regeneration loop

For the first diagram, paste the rendered manifests into the Kubernetes diagram generator and shape it from there. Keeping it current is a render plus one agent call: Datadef's MCP server, registry name io.datadef/mcp, lets an agent such as Claude Code or Cursor read the freshly rendered output and update the existing diagram rather than draw a new one.

Datadef does not watch the repository, and no GitHub App detects that a chart changed. The trigger is yours: a CI job filtered on charts/** and overlays/** paths that renders and hands the output to the agent, or a request during review when a PR touches the topology. One command, invoked by the pipeline that already knows something changed. The API key the agent needs is created in settings, on paid plans.

What the manifests cannot show

Operators break the repo-only view. A Postgres operator turns one small custom resource into pods, services, and secrets the repo never names, so a rendered-manifest diagram shows the CR and none of its offspring. When operators run your stateful systems, the cluster query is the only source that sees their children; diagram the CR as the node and note what it expands into.

Rendered output is also big. A platform with twelve namespaces renders thousands of lines, and a diagram that draws every resource is as unreadable as the YAML. Scope the diagram to the namespaces a reader cares about and let zones summarize the rest. And if the result is embedded in a wiki through the live image URL, the project must be shared public, which is a real trade-off for private platform topologies.

FAQ

How do I visualize Kubernetes YAML manifests as a diagram?

Render the effective manifests first: helm template for charts, kubectl kustomize for overlays, with the same values production uses. Then generate the diagram from that output, mapping namespaces to zones, Deployments and StatefulSets to nodes, and Services, Ingresses, and label selectors to edges. Raw templates are the wrong input because values and patches change the graph.

Should I diagram the repo manifests or the live cluster state?

In a healthy GitOps setup they converge, and rendered repo manifests are the better standing source: versioned, reviewable, and available to CI without cluster access. Use kubectl get -o yaml when you suspect drift or need operator-created resources, and treat any gap between the two as something to investigate, not paper over.

How does a Service to Deployment relationship show up in a diagram?

As a selector edge. A Service selects pods by label rather than naming a Deployment, so the edge exists wherever the selector matches a pod template. Drawing that resolved match is one of the main reasons to diagram manifests at all, since no single file shows it.

Can the diagram update itself when our Helm chart changes?

Not by watching: Datadef has no repository integration that detects changes. The loop is a CI job with a paths filter on the chart and overlay directories that renders the manifests and asks an MCP-connected agent to update the diagram. The detection is your CI trigger; the redraw is one call.

What about resources created by operators?

Rendered repo manifests show the custom resource but not the pods, services, and secrets the operator creates from it. If operators run your databases or queues, pull the running state with kubectl get -o yaml for those namespaces, or draw the CR as a single node annotated with what it manages.