Anatomy of a Chart

Every file in a Helm chart and what it does. Chart.yaml metadata, values.yaml defaults, templates/, _helpers.tpl named templates, NOTES.txt, CRDs, and chart types.

Overview

A chart is a strict layout

A Helm chart is a directory (or .tgz archive) with a strictly defined layout. Knowing every file and its role is the foundation for debugging charts, writing templates correctly and designing chart structures for your team.

What gets rendered

Only Chart.yaml and templates/ are required. Everything else is optional, but each file has a semantic role Helm enforces.

templates/*.yaml — Yes
templates/_*.tpl (underscore prefix) — No: defines named templates
templates/NOTES.txt — Rendered and printed, not applied
crds/ — Never rendered; plain YAML only
README.md, LICENSE — Informational only

Two version fields

version — The chart's own SemVer version — Must be incremented on every chart change
appVersion — The deployed application's version — Informational only

> [!WARNING] Conflating version and appVersion is a frequent chart-maintenance bug; it confuses nearly every Helm newcomer.

The crds/ constraints

These constraints exist because CRDs are cluster-global resources. Helm cannot safely manage them with the same CRUD lifecycle as namespace-scoped objects.

Library charts

A library chart (type: library) packages named templates that other charts consume as dependencies. It cannot be installed directly, because it has no resources to apply.

> [!TIP] Library charts shine in large estates: standard resource naming, labels and sidecar injection patterns shared across dozens of application charts.

Key concepts

Chart.yaml: version vs appVersion: version is the chart's own SemVer version — increment on any chart change. appVersion is the application version the chart deploys — informational only. Helm uses version for dependency resolution; appVersion appears in helm list output but drives no Helm logic.
apiVersion: v2: The chart API version required for Helm 3 and Helm 4. Enables the dependencies field in Chart.yaml (Helm 2 used a separate requirements.yaml). Also enables the type field (application vs library). A chart with apiVersion: v1 is a Helm 2 legacy chart.
templates/_helpers.tpl: The conventional file for named template definitions ({{ define }} blocks). Files prefixed with underscore are not rendered as Kubernetes manifests. Named templates are called with {{ include "chart.helper" . }} from other template files. helm create generates _helpers.tpl with common naming and label helpers.
crds/ directory constraints: CRD YAML files here cannot be templated (plain YAML only), are installed before templates render, are never deleted on helm uninstall, and are never automatically reinstalled or upgraded. Designed to protect cluster-global resources from lifecycle accidents.
NOTES.txt: A Go template file in templates/ that renders to a human-readable post-install message (not a Kubernetes manifest). Printed to CLI after helm install or helm upgrade. Has access to .Values, .Release, and all template helpers. Use it to show service URLs, next steps, and configuration reminders.
Library charts (type: library): Charts containing only named template definitions. Not directly installable. Listed as dependencies in application charts that call their templates. Used for platform-wide helper sharing: standard resource naming, common label sets, sidecar injection boilerplate.

When to use it

Any time you write or debug a chart — understanding the file layout prevents the class of "file renders when it should not" or "template not found" errors
When building a chart scaffold for a new service — helm create gives the standard layout; know what to keep and what to remove
When deciding between charts/ and crds/ for CRD management — the immutability constraints of crds/ mean manual CRD management in large-cluster estates
When building a library chart for shared helpers across a platform team's chart collection

Interview questions

Describe the complete directory structure of a Helm chart and the role of each file.
What is the purpose of _helpers.tpl and how are named templates called?
Why are CRDs in the crds/ directory, and what are the implications for upgrade management?
How does values.schema.json work and what does it validate?
What does helm create generate and what would you typically remove or modify?