Kubernetes Guide

Kubernetes YAML to diagram: manifests and Helm charts, straight from the repo

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The tools in this space mostly work the same way: paste a manifest or point a CLI at a chart, get a rendered graph back, save the image somewhere. KubeDiagrams, kubeviz, and the browser pasteboards all do a decent job of that. The part none of them solve is the second week, when the chart changed and the image did not. A repository connection changes which problem you are solving.

Try it free
7 min readFor platform engineers whose cluster is defined by YAML in a git repository

See it as a diagram

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

190/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The rule that decides which YAML counts

A repository is full of YAML that has nothing to do with the cluster: linter config, dependabot, issue templates, feature flags. The selector uses a simple, checkable rule instead of guessing. A .yml or .yaml file is treated as a deployment manifest when it sits under a directory named k8s, kube, kubernetes, manifests, charts, or helm.

That covers the layouts teams actually use. k8s/base and k8s/overlays for a kustomize repo. charts/myapp/Chart.yaml, charts/myapp/values.yaml, and everything under charts/myapp/templates for a Helm repo. manifests/production for a plain apply repo. A kustomization.yaml sitting at the repository root, outside any of those directories, is not picked up, so keep the cluster YAML in a cluster-named folder.

Helm templates are read as text, Go templating and all. That is enough for the generator to see which workloads exist, what images they run, which services front them, and what the values file switches on. It is not a render, and the diagram does not claim to show a specific release with values applied.

Classified as deployment manifests
  k8s/base/deployment.yaml
  k8s/overlays/prod/patch.yaml
  charts/api/values.yaml
  charts/api/templates/statefulset.yaml
  manifests/production/ingress.yaml

Not classified
  kustomization.yaml            (repo root, no cluster-named parent)
  .github/dependabot.yml        (CI-adjacent config, different class)
  config/features.yaml          (application config)

The manifests are not read alone

This is where a repo connection separates from a YAML pasteboard. The same corpus that carries the manifests also carries every Dockerfile in the repository, the docker-compose file when there is one, the CI workflows, and the dependency manifests. So the diagram can show not only that a deployment named worker exists, but what image it is built from, what the pipeline does before it ships, and what the service depends on at build time.

The manifest class takes up to 12 files by default and 14 when the diagram is set to the architecture focus, because on a cluster repo those files are the subject rather than the context; under the content focus it drops to 3. Files inside a class are fetched shallow-first and then alphabetically, so charts/api/values.yaml is read before charts/api/templates/deployment.yaml, and a base overlay is read before a deep environment patch. That ordering is worth knowing when a chart has more templates than the ceiling allows.

The first sync states what it found in one deterministic sentence, composed from the counts without a model call. A cluster repo typically reads as: Mostly Kubernetes manifests and CI pipelines (23 files) with no data model or API files. That points at the architecture focus, which draws what runs, what it talks to, and how it is deployed.

No cluster access, and that is the point

There is no kubeconfig, no service account, no read against the API server. The connection is read-only repository access on GitHub, GitLab, or Azure DevOps, which means the diagram can be produced for a cluster that does not exist yet, for a branch under review, or for a client environment you will never be given credentials to.

The trade is that this draws intent rather than state. Resources somebody applied by hand, or a controller created dynamically, are not in the repository and so are not in the diagram. For teams doing GitOps that gap is close to zero by design, and for everyone else the difference between the repo and the cluster is itself worth knowing.

Real icons, not colored rectangles

The catalog carries 41 Kubernetes marks, one per resource kind from Deployment, StatefulSet and DaemonSet down to NetworkPolicy, PersistentVolumeClaim and ServiceAccount, inside a catalog of more than 2000 icons that also covers the databases, queues and cloud services around the cluster. See the canvas documentation.

What you keep after the first render

A pasted-YAML render gives you an image. A connected repo gives you a project that redraws on a daily sync, skips commits that changed nothing, keeps hand-moved nodes where you put them, and can be embedded in the README or a runbook as a live image that follows the branch.

It also gives you an architecture doc regenerated from the same files, covering the components, the infrastructure, and the build and deployment steps the manifests and pipelines declare. And an agent can trigger a refresh over MCP right after a chart change merges, so the picture updates in the same session as the code.

FAQ

Which YAML files in my repo are treated as Kubernetes manifests?

Any .yml or .yaml file under a directory named k8s, kube, kubernetes, manifests, charts, or helm. That covers kustomize base and overlay layouts, Helm charts including their values and templates, and plain apply directories. YAML outside those directories is treated as ordinary config and is not fetched as a manifest.

Are Helm templates rendered before being read?

No. Templates are read as source text with their Go templating intact, together with the chart values file. That is enough to identify the workloads, images, services, and switches the chart declares, but the diagram represents the chart rather than one rendered release.

Does it need access to the cluster?

No kubeconfig, no service account, and no API server access. The only requirement is read access to the repository, which means a diagram can be produced for a branch under review or an environment you have no credentials for.

How is this different from a YAML-to-diagram web tool?

A pasteboard renders the files you give it, once. A repository connection reads the manifests together with the Dockerfiles, compose file, and CI pipelines, redraws daily from the branch, keeps node positions across regenerations, and serves the current picture through an embed URL that does not need an account to view.

What happens to resources created outside the repo?

They do not appear. The diagram reflects what the repository declares, so a resource somebody applied by hand and an object a controller created at runtime are both outside its scope. For a GitOps repository that difference is close to zero by design, and everywhere else the gap between the repo and the cluster is itself worth knowing about.