Lesson 2 · Helm fundamentals
Chart anatomy
The handful of files that make a chart — and how tiny a service chart is here.
Your win: know what's in a chart directory — Chart.yaml,
templates/, values.yaml, helpers, .helmignore — and
read this repo's application vs library chart distinction.
The standard chart layout
mychart/
├── Chart.yaml # metadata: name, version, type, dependencies
├── values.yaml # default values (.Values)
├── templates/ # rendered through the template engine → K8s manifests
│ ├── _helpers.tpl # partials (leading _ = NOT a manifest)
│ ├── deployment.yaml
│ └── NOTES.txt # printed after install
├── charts/ # fetched subchart dependencies (if any)
└── .helmignore # files to exclude from helm package
When Helm evaluates a chart, it runs every file in templates/ through
the engine and collects the resulting manifests — except files starting with
_ (helpers) and NOTES.txt (post-install message).1
Chart.yaml — the metadata
The one required file. Key fields:2
| Field | Meaning |
|---|---|
apiVersion | v2 for Helm 3 |
name, version | chart name + the chart's own SemVer |
appVersion | version of the app it deploys (informational) |
type | application (installable) or library (templates only) |
dependencies | subcharts to fetch into charts/ (optional) |
Anchor — a service chart is tiny
deployments/helm/backend/bob/Chart.yaml:1-6:
apiVersion: v2, type: application, version: 0.1.0,
an appVersion, and no dependencies: block. The
whole chart is: Chart.yaml, a values.yaml, the
{env}-{org}-values.yaml files, secrets/, configs/, and
a templates/app.yaml that is literally one line —
{{- include "util.appWithToggle" . -}}. All the real object templates live
elsewhere (Lesson 6). spike and conversationmgmt look identical in
shape.
application vs library
A
type: application chart is installable — it produces objects. A
type: library chart produces nothing on its own; it only defines
reusable named templates for other charts to use. This repo's
libs/util/Chart.yaml is type: library — hold that
thought; it's the heart of Lesson 6.
values.yaml — the defaults
values.yaml supplies the chart's default .Values, overridable at
install time (Lesson 4).
Anchor — defaults + a shared global file
backend/bob/values.yaml holds the service defaults —
enabled, ports (grpcPort: 5050, httpPort: 5080),
migrationEnabled, resources, Istio routes. Separately,
backend/values.yaml is a shared file that is entirely
a global: block (image repo/tag, VPA defaults, Hasura settings) — values every
service chart can see. You'll see how those layer in Lesson 4.
Helpers & NOTES
Anchor — no
_helpers.tpl here
Convention puts partials in _helpers.tpl, but this repo splits them:
libs/util/templates/_name.tpl (util.fullname),
_label.tpl (util.labels), _env.tpl,
_check.tpl — all leading-underscore, so none render to a manifest (Lesson 5).
NOTES.txt exists only in platform charts, not backend services; and every chart
has a .helmignore.
Read this next
Helm docs — Charts (the file format)
Chart.yaml fields, the templates/ directory rules, and the
application-vs-library type.
Check yourself (from memory)
Q1. A file named _helpers.tpl in templates/…
Leading
_ means "not a manifest" — it's for
named templates other files include.
Q2. A type: library chart…
Library charts only provide reusable named templates; they
render no objects. Repo:
libs/util.
Q3. In this repo, a backend service's templates/app.yaml is…
{{- include "util.appWithToggle" . -}} — the
object templates live in the shared library (Lesson 6).
What files make a chart, and what's special about this repo's service charts?
recall, then click to reveal
A CHART =
Chart.yaml (metadata: apiVersion v2, name,
version, appVersion, type, dependencies?) + values.yaml (default
.Values) + templates/ (rendered to manifests; leading-underscore
files = partials, NOTES.txt = post-install msg) + charts/
(subcharts) + .helmignore. TYPE: application (installable) vs
library (templates only, renders nothing). REPO: service charts are TINY —
type: application, version 0.1.0, NO deps; bob/values.yaml holds
defaults, shared backend/values.yaml is all global:;
templates/app.yaml is one line calling util.appWithToggle. Helpers
split across _name/_label/_env.tpl (no _helpers.tpl).
libs/util is type: library.
Want to walk the full
bob/ directory tree, or see where configs/
and secrets/ get used? Ask me.