Charts, templates and values¶
Status: AI draft, 2026-11-16. Not yet verified by me. Written from the Helm documentation (Helm 4); the Helm commands were not run for this page, so they have no sample output. Run them on a chart from
helm createto check.
In one line¶
A Helm chart is a folder of Kubernetes manifest templates plus default values; helm template or helm install renders the Go templates with values merged from the chart's values.yaml, any -f files and any --set flags (later wins), producing plain YAML that Helm applies and tracks as a release.
The plain idea¶
Plain YAML repeats itself. The same app in three environments needs three copies differing in a replica count, an image tag and a hostname, and copies drift. Helm treats the manifests as templates with holes, and fills the holes from values:
- the chart author writes
replicas: {{ .Values.replicaCount }}once; - each environment supplies its own values file;
- Helm renders, applies, and remembers what it applied as a release, so it can upgrade, roll back and uninstall as a unit (Releases, hooks and debugging).
A chart is also a package: versioned, published to a repository or an OCI registry, and installable by others with their own values.
How it works¶
Chart layout¶
sample-app/
├── Chart.yaml name, version (the chart's), appVersion (the app's), dependencies
├── values.yaml default values
├── charts/ dependency charts (subcharts)
├── templates/
│ ├── _helpers.tpl named templates; files starting with _ render nothing themselves
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── NOTES.txt printed after install
│ └── tests/ test pods run by helm test
└── .helmignore files to leave out of the package
apiVersion: v2 in Chart.yaml marks a chart that needs Helm 3 or later; version must be SemVer and changes with every chart change; appVersion is just a label for the application version.
From values to YAML¶
flowchart TD
V1["values.yaml in the chart<br/>(lowest precedence)"] --> M["Merged values"]
V2["Parent chart's values,<br/>for a subchart"] --> M
V3["-f my-values.yaml,<br/>later files win"] --> M
V4["--set key=value<br/>(highest precedence)"] --> M
M --> R["Template engine: Go templates<br/>plus Sprig functions"]
T["templates/*.yaml"] --> R
R --> Y["Plain Kubernetes YAML"]
Template basics¶
| Construct | Meaning |
|---|---|
{{ .Values.image.tag }} |
A value |
{{ .Release.Name }}, {{ .Release.Namespace }}, {{ .Chart.Name }}, {{ .Chart.AppVersion }} |
Built-in objects |
{{ default .Chart.AppVersion .Values.tag }} |
A default when the value is empty |
{{ required "image.repository is required" .Values.image.repository }} |
Fail the render with a message if missing |
{{ quote .Values.name }} |
Wrap in quotes, so yes or 1.0 stay strings |
{{- if .Values.ingress.enabled }} ... {{- end }} |
Conditional block; {{- trims whitespace before |
{{- range $k, $v := .Values.env }} ... {{- end }} |
Loop over a list or map |
{{- with .Values.resources }} ... {{- end }} |
Change . to that value, and skip the block if it is empty |
{{- nindent 12 (toYaml .) }} |
Insert a value as YAML, indented 12 spaces on a new line |
{{ include "sample-app.labels" . }} |
Call a named template and get its output as a string, so it can be piped |
Functions are usually written with pipes, which pass the left side as the last argument: {{ .Values.tag | default .Chart.AppVersion }} is the same as {{ default .Chart.AppVersion .Values.tag }}, and {{ toYaml . | nindent 12 }} the same as {{ nindent 12 (toYaml .) }}.
A Deployment template fragment, in the style helm create generates:
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "sample-app.fullname" . }}
labels:
{{- include "sample-app.labels" . | nindent 4 }}
spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
selector:
matchLabels:
{{- include "sample-app.selectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "sample-app.selectorLabels" . | nindent 8 }}
spec:
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
{{- with .Values.resources }}
resources:
{{- toYaml . | nindent 12 }}
{{- end }}
The if not .Values.autoscaling.enabled around replicas is the chart-side fix for the HPA fighting the manifest (Autoscaling).
Named templates¶
_helpers.tpl defines reusable snippets:
{{- define "sample-app.selectorLabels" -}}
app.kubernetes.io/name: {{ include "sample-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
- Names are global across the chart and its subcharts, so prefix them with the chart name.
- Use
includerather thantemplate:includereturns a string you can pipe intonindent. - Pass the right scope (usually
.); insiderangeorwith,.has changed, and$still means the root.
Values precedence, concretely¶
values.yaml says replicaCount: 1; prod.yaml says replicaCount: 3; the command adds --set replicaCount=5. The result is 5. Maps merge key by key; lists are replaced whole, so overriding one item of a list means repeating the full list.
A concrete example¶
One chart for sample-app, three environments:
values.yaml image.repository, resources, probes: the shared defaults
values-dev.yaml replicaCount: 1, ingress host dev.example.com
values-prod.yaml replicaCount: 3, autoscaling.enabled: true, host www.example.com
helm lint ./sample-app -f values-prod.yaml
helm template sample-app ./sample-app -f values-prod.yaml --set image.tag=1.4.2 > rendered.yaml
helm upgrade --install sample-app ./sample-app -n team-a -f values-prod.yaml --set image.tag=1.4.2
CI renders with helm template and checks the YAML (policy, schema) before anything reaches a cluster (Quality and security gates); a GitOps tool can render the same chart from Git instead of running helm upgrade (Argo CD architecture).
Why not just...?¶
- ...keep three copies of the YAML? They drift: a probe fixed in one environment stays broken in the others. One template with per-environment values keeps the differences small and visible.
- ...template everything, every field a value? Charts with hundreds of values are harder to read than the YAML they generate. Expose what really varies; for one-off changes, patch the output (Kustomize, and Helm vs Kustomize).
- ...use
--setfor everything in CI? Long--setlists are hard to review and escape (commas, dots and lists need special syntax). Put values in files under version control; use--setfor the one thing that changes per build, such as the image tag.
Commands to know¶
These were not run for this page.
| Command | What it does |
|---|---|
helm create sample-app |
A starter chart with the layout above. |
helm lint ./sample-app -f values-prod.yaml |
Checks chart structure and that templates render. |
helm template <release> ./sample-app -f values.yaml |
Renders locally to stdout; no cluster needed. |
helm template ... --show-only templates/deployment.yaml |
Renders one template. |
helm template ... --debug |
Shows the rendered output even when YAML parsing fails, to find the broken line. |
helm show values <chart> |
A published chart's default values. |
helm dependency update ./sample-app |
Downloads dependencies listed in Chart.yaml into charts/. |
helm package ./sample-app |
Builds the versioned .tgz. |
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
error converting YAML to JSON |
Rendering | helm template --debug |
Wrong indentation from toYaml without nindent, or a missing {{- |
nil pointer evaluating interface {}.tag |
Values | The values path | A parent key is missing; use default or check with if or with |
A value like yes or 1.10 changes meaning |
YAML typing | Rendered output | Not quoted; use quote |
--set override ignored |
Precedence or path | helm get values |
Wrong key path, or a later -f file; lists replaced, not merged |
| Every environment got the prod setting | Values files | Order of -f |
Later files win; the order on the command line matters |
| Template change has no effect in a subchart | Scope | Values nesting | Subchart values must sit under the subchart's name in the parent |
Interview questions¶
1. What problem does Helm solve, and what is a chart?
Answer
- Reusing manifests across environments and sharing applications as packages, and managing them as releases.
- A chart is a versioned folder of templates, default values and metadata.
- Helm renders templates with values into plain YAML and tracks the result.
2. What is the order of values precedence?
Answer
- The chart's
values.yaml, then a parent chart's values for a subchart, then-ffiles in order, then--set. - Later sources override earlier ones.
- Maps merge; lists are replaced whole.
3. What is the difference between include and template?
Answer
- Both call a named template.
includereturns the output as a string, so it can be piped tonindent,quoteorindent.templatewrites it straight out, so it cannot be indented, which breaks YAML.
4. How do you debug a chart that fails with a YAML parse error?
Answer
helm template --debugto see the rendered output and the failing template.- Look for indentation from
toYamlwithoutnindent, or whitespace trimming mistakes. - Render a single file with
--show-only.
5. How would you make a value mandatory?
Answer
required "message" .Values.pathfails rendering when it is missing.- Or a
values.schema.jsonthat validates types and required keys before rendering. - Both fail early in CI instead of producing broken manifests.
6. How do you stop a chart's replica count fighting an HPA?
Answer
- Render
replicasonly when autoscaling is disabled:{{- if not .Values.autoscaling.enabled }}. - Otherwise every upgrade resets the count the HPA chose.
- The same applies to GitOps tools comparing the field.
Try it¶
If you have Helm installed (it is not part of these notes' toolchain):
helm create sample-app, thenhelm template demo ./sample-app | less, and find wherereplicaCountappears.- Predict the replica count, then check:
helm template demo ./sample-app --set replicaCount=4 --show-only templates/deployment.yaml | grep replicas. - Break
templates/deployment.yamlby replacing annindent 12withindent 12, and read the error fromhelm template --debug.
Without Helm, read the fragment above and write down the YAML it produces for replicaCount: 2, autoscaling.enabled: false, image.tag empty and appVersion: "1.4.2".
Zoom out¶
Helm is the packaging layer between your manifests and the cluster: templates and values on one side, releases on the other (Releases, hooks and debugging). Kustomize solves the same multi-environment problem by patching instead of templating (Kustomize, and Helm vs Kustomize), and GitOps tools can drive either (GitOps principles).