Day 4: Built-in Objects and Template Basics
Goal: Render with
.Release,.Chart,.Templateand.Capabilities, read dot and pipe confidently – and know whyhelm templaterenders differently from the cluster. · Duration: approx. 45 min · Prerequisite: Day 3
Briefing
- Everything between
{{ }}is an action. The dot is the current context; at the top of the template it is the root with all built-in objects. - A pipe passes its value on as the last argument.
That is why with
defaultthe fallback value comes first. helm templatedoes not ask any cluster..Capabilitiesthen comes from built-in defaults – CI may render differently from the installation.
| Object | Examples |
|---|---|
.Values |
all merged values |
.Release |
.Name, .Namespace, .Revision,
.IsInstall, .IsUpgrade,
.Service |
.Chart / .Template |
everything from Chart.yaml / .Name,
.BasePath of the file |
.Capabilities / .Files |
.KubeVersion, .APIVersions.Has / other
files (Day 8) |
Drill 1: A ConfigMap from built-in objects
# on prod
mkdir -p ~/helm/tag04 && cd ~/helm/charts
cat > notes/templates/configmap.yaml <<'EOF'
{{/* notes/templates/configmap.yaml – Stand Tag 04 */}}
apiVersion: v1
kind: ConfigMap
metadata:
name: notes-info
data:
release: {{ .Release.Name }}
namespace: {{ .Release.Namespace }}
revision: {{ .Release.Revision | quote }}
installOderUpgrade: {{ ternary "upgrade" "install" .Release.IsUpgrade }}
chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
app: {{ .Chart.AppVersion | quote }}
template: {{ .Template.Name }}
basePath: {{ .Template.BasePath }}
kube: {{ .Capabilities.KubeVersion.Version }}
helm: {{ .Capabilities.HelmVersion.Version }}
EOF
sed -i 's/^version: .*/version: 0.3.0/; s/Tag 03/Tag 04/' notes/Chart.yaml
helm template notes ./notes -s templates/configmap.yamlExpected:
---
# Source: notes/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: notes-info
data:
release: notes
namespace: default
revision: "1"
installOderUpgrade: install
chart: "notes-0.3.0"
app: "0.7.1"
template: notes/templates/configmap.yaml
basePath: notes/templates
kube: v1.37.0
helm: v4.3.2
(The key installOderUpgrade means “installOrUpgrade”.)
Without a cluster, helm template assumes: namespace
default, revision 1, installation, Kubernetes v1.37.0.
{{/* … */}} is a template comment – it does not show up in
the result. .Revision needs quote because
ConfigMap data must be strings.
Save your progress? Sign up for free
Drill 2: Install or upgrade?
# on prod
helm template notes ./notes -s templates/configmap.yaml --is-upgrade -n notes \
| grep -E 'namespace|revision|install'
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISION
kubectl -n notes get configmap notes-info -o yaml | yq '.data'Expected:
namespace: notes
revision: "1"
installOderUpgrade: upgrade
REVISION: 10
app: 0.7.1
basePath: notes/templates
chart: notes-0.3.0
helm: v4.3.2
installOderUpgrade: upgrade
kube: v1.37.2+k3s1
namespace: notes
release: notes
revision: "10"
template: notes/templates/configmap.yaml
--is-upgrade only flips the switch; when rendering, the
revision stays 1. The cluster holds the real values: revision 10, the
exact k3s version. This is how a template knows whether it is running
for the first time – useful for one-off actions (Days 7, 11).
Save your progress? Sign up for free
Drill 3: What can the cluster do?
.Capabilities.APIVersions.Has asks whether an API is
present. k3s 1.37 ships the Gateway API CRDs (Day 0, Drill 5). You add
two lines at the end of the ConfigMap:
# on prod
cat >> notes/templates/configmap.yaml <<'EOF'
gatewayAPI: {{ .Capabilities.APIVersions.Has "gateway.networking.k8s.io/v1" | quote }}
httpRoute: {{ .Capabilities.APIVersions.Has "gateway.networking.k8s.io/v1/HTTPRoute"
| quote }}
EOF
helm template notes ./notes -s templates/configmap.yaml | grep -E 'gateway|http'
helm template notes ./notes -s templates/configmap.yaml --dry-run=server \
| grep -E 'gateway|http'
helm template notes ./notes -s templates/configmap.yaml \
-a gateway.networking.k8s.io/v1 | grep -E 'gateway|http'Expected:
gatewayAPI: "false"
httpRoute: "false"
gatewayAPI: "true"
httpRoute: "true"
gatewayAPI: "true"
httpRoute: "false"
Without a cluster: nothing there. With --dry-run=server,
helm template asks the real cluster. With -a
(--api-versions) you specify APIs yourself – but
group/version and group/version/Kind are
separate entries. An action may span several lines; that keeps the line
short.
Tip: The old
helm template --validateis deprecated in Helm 4 and reportsuse '--dry-run=server' instead.
# on prod
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISION
kubectl -n notes get configmap notes-info -o jsonpath='{.data.gatewayAPI}{"\n"}'Expected:
REVISION: 11
true
Save your progress? Sign up for free
Drill 4: Dot and pipe
For experiments you create a playground (spielwiese)
that you delete again at the end.
# on prod
cat > notes/templates/spielwiese.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: spielwiese
data:
a: {{ .Values.env.NOTES_LOG_LEVEL | default "info" | upper | quote }}
b: {{ quote (upper (default "info" .Values.env.NOTES_LOG_LEVEL)) }}
c: {{ "x" | printf "%s-%s" "a" | quote }}
d: {{ .Values.debug }}
e: {{ .Values.version | quote }}
EOF
cat > ~/helm/tag04/spiel.yaml <<'EOF'
debug: true
version: 1.20
env:
NOTES_LOG_LEVEL: warn
EOF
helm template notes ./notes -s templates/spielwiese.yaml -f ~/helm/tag04/spiel.yamlExpected:
---
# Source: notes/templates/spielwiese.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: spielwiese
data:
a: "WARN"
b: "WARN"
c: "a-x"
d: true
e: "1.2"
a and b are the same: once as an assembly
line from left to right, once nested from the inside out. c
shows the rule: the pipe value x ends up as the last
argument of printf. e is the trap: YAML
already turned 1.20 into the number 1.2 when reading
spiel.yaml – quote comes too late. Put
versions in quotes already in the values file.
Save your progress? Sign up for free
Drill 5: The quote trap in the cluster
d: true is a boolean, but ConfigMap data must be
strings. Who notices?
# on prod
helm install spiel ./notes -n tag04 --create-namespace -f ~/helm/tag04/spiel.yaml \
--dry-run=server | grep STATUS
helm template x ./notes -s templates/spielwiese.yaml -f ~/helm/tag04/spiel.yaml \
| kubectl apply --dry-run=server -n default -f -
helm install spiel ./notes -n tag04 --create-namespace -f ~/helm/tag04/spiel.yamlExpected:
STATUS: pending-install
Error from server (BadRequest): error when creating "STDIN": ConfigMap in version "v1"
cannot be handled as a ConfigMap: json: cannot unmarshal bool into Go struct field
ConfigMap.data of type string
Error: INSTALLATION FAILED: server-side apply failed for object tag04/spielwiese
/v1, Kind=ConfigMap: failed to create typed patch object (tag04/spielwiese;
/v1, Kind=ConfigMap): .data.d: expected string, got
&value.valueUnstructured{Value:true}
Warning:
helm install --dry-run=serverdoes not send the objects to the API for validation. It only asks the cluster forlookupand.Capabilities. The type error is caught only bykubectl apply --dry-run=server– or by the real installation.
Strings always get | quote. Numbers such as ports and
replicas you leave without it, otherwise Kubernetes rejects them as
strings.
# on prod
helm uninstall spiel -n tag04
kubectl delete namespace tag04
rm notes/templates/spielwiese.yaml
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISIONExpected:
release "spiel" uninstalled
namespace "tag04" deleted
REVISION: 12
The failed installation stayed behind as a release with status
failed – hence the uninstall.
Save your progress? Sign up for free
Drill 6: Find broken YAML
# on prod
cat > ~/helm/tag04/kaputt.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
name: kaputt
data:
level: {{ .Values.env.NOTES_LOG_LEVEL | quote }}
falsch: eingerueckt
EOF
cp ~/helm/tag04/kaputt.yaml notes/templates/
helm template notes ./notes -s templates/kaputt.yaml
helm template notes ./notes -s templates/kaputt.yaml --debug 2>&1 | grep -v level=DEBUG
rm notes/templates/kaputt.yamlExpected:
Error: YAML parse error on notes/templates/kaputt.yaml: error converting YAML to JSON:
yaml: line 6: did not find expected key
Use --debug flag to render out invalid YAML
---
# Source: notes/templates/kaputt.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: kaputt
data:
level: "info"
falsch: eingerueckt
Error: YAML parse error on notes/templates/kaputt.yaml: error converting YAML to JSON:
yaml: line 6: did not find expected key
(kaputt means “broken”, falsch: eingerueckt
“wrong: indented”.) Without --debug you only see the line
number in the rendered document, not in the template.
With --debug, Helm prints the broken YAML, and you see the
spot.
Save your progress? Sign up for free
Exercise: Speed Drills
- Render the ConfigMap as if it were an upgrade in
notes. Target time: 20 s - Show which Kubernetes version
helm templateassumes without a cluster. Target time: 20 s - Read the current revision from the ConfigMap in the cluster. Target time: 20 s
- Render the ConfigMap for Kubernetes 1.36.4. Target time: 20 s
Solution
# on prod
helm template notes ./notes -s templates/configmap.yaml --is-upgrade -n notes
helm template notes ./notes -s templates/configmap.yaml | grep kube
kubectl -n notes get configmap notes-info -o jsonpath='{.data.revision}{"\n"}'
helm template notes ./notes -s templates/configmap.yaml --kube-version 1.36.4 \
| grep kubeExpected (abridged):
installOderUpgrade: upgrade
kube: v1.37.0
12
kube: v1.36.4
Save your progress? Sign up for free
Checkpoint
# on prod
helm list -n notesExpected: notes with revision 12,
notes-0.3.0, deployed.
# on prod
kubectl -n notes get configmap notes-info -o jsonpath='{.data.chart} {.data.httpRoute}'Expected: notes-0.3.0 true
# on prod
ls notes/templatesExpected:
NOTES.txt configmap.yaml deployment.yaml service.yaml –
no playground any more.
Challenge
Your CI pipeline has no access to the cluster but should render
exactly like --dry-run=server. Generate a list of all APIs
including kinds from the cluster and prove with diff that
helm template produces the same result with it.
Hint: kubectl api-versions only returns
group/version; the kinds are in
kubectl api-resources.
Solution
# on prod
cd ~/helm/tag04
kubectl api-versions > apis.txt
kubectl api-resources --no-headers | awk '{print $(NF-2)"/"$NF}' >> apis.txt
grep HTTPRoute apis.txt
KV=$(kubectl version -o json | jq -r .serverVersion.gitVersion)
cd ~/helm/charts
diff <(helm template notes ./notes -n notes --kube-version $KV \
-a "$(paste -sd, ~/helm/tag04/apis.txt)") \
<(helm template notes ./notes -n notes --dry-run=server) && echo gleichExpected:
gateway.networking.k8s.io/v1/HTTPRoute
gleich
(gleich means “same”.) $(NF-2) is the
APIVERSION column, $NF the KIND
column – counted from the end, because SHORTNAMES is often
empty. You keep the file apis.txt in the repo per target
cluster and update it with every cluster upgrade.
Save your progress? Sign up for free
Cleanup
# on prod
git add -A
git commit -qm "Tag 04: eingebaute Objekte, notes 0.3.0"Interview Note
- What does the dot mean in a template? The current context.
At the top it is the root with
.Values,.Releaseand so on;rangeandwithchange it (Day 5). - How do you make a chart fit for several Kubernetes
versions? With
.Capabilities.APIVersions.Hasand.Capabilities.KubeVersionin the template, pluskubeVersioninChart.yamlas a hard limit. - Does
helm install --dry-run=servervalidate the manifests? No, it only enables cluster queries. Validation against the API is done bykubectl apply --dry-run=server.
Enterprise Note
- CI renders with
--kube-versionand--api-versionsof the target cluster; otherwise it tests a different result from what gets installed. - In addition, run
helm template | kubectl apply --dry-run=serveragainst a staging cluster – it catches type errors that Helm lets through (Day 17). - Distributions differ in the CRDs they ship (Gateway API in k3s, Routes in OpenShift). Charts ask for the API, not for the distribution.