Skip to content
Hands-on IT IT Drills

Day 4: Built-in Objects and Template Basics

Goal: Render with .Release, .Chart, .Template and .Capabilities, read dot and pipe confidently – and know why helm template renders 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 default the fallback value comes first.
  • helm template does not ask any cluster. .Capabilities then 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.yaml

Expected:

---
# 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 --validate is deprecated in Helm 4 and reports use '--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.yaml

Expected:

---
# 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.yaml

Expected:

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=server does not send the objects to the API for validation. It only asks the cluster for lookup and .Capabilities. The type error is caught only by kubectl 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 REVISION

Expected:

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.yaml

Expected:

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

  1. Render the ConfigMap as if it were an upgrade in notes. Target time: 20 s
  2. Show which Kubernetes version helm template assumes without a cluster. Target time: 20 s
  3. Read the current revision from the ConfigMap in the cluster. Target time: 20 s
  4. 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 kube

Expected (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 notes

Expected: 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/templates

Expected: 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 gleich

Expected:

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, .Release and so on; range and with change it (Day 5).
  • How do you make a chart fit for several Kubernetes versions? With .Capabilities.APIVersions.Has and .Capabilities.KubeVersion in the template, plus kubeVersion in Chart.yaml as a hard limit.
  • Does helm install --dry-run=server validate the manifests? No, it only enables cluster queries. Validation against the API is done by kubectl apply --dry-run=server.

Enterprise Note

  • CI renders with --kube-version and --api-versions of the target cluster; otherwise it tests a different result from what gets installed.
  • In addition, run helm template | kubectl apply --dry-run=server against 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.