Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: Eingebaute Objekte und Template-Grundlagen

Ziel: Mit .Release, .Chart, .Template und .Capabilities rendern, Punkt und Pipe sicher lesen – und wissen, warum helm template anders rendert als der Cluster. · Dauer: ca. 45 min · Voraussetzung: Tag 3

Briefing

  • Alles zwischen {{ }} ist eine Action. Der Punkt ist der aktuelle Kontext, oben im Template die Wurzel mit allen eingebauten Objekten.
  • Eine Pipe reicht ihren Wert als letztes Argument weiter. Darum steht bei default zuerst der Ersatzwert.
  • helm template fragt keinen Cluster. .Capabilities kommt dann aus eingebauten Standards – CI rendert womöglich anders als die Installation.
Objekt Beispiele
.Values alle zusammengeführten Werte
.Release .Name, .Namespace, .Revision, .IsInstall, .IsUpgrade, .Service
.Chart / .Template alles aus Chart.yaml / .Name, .BasePath der Datei
.Capabilities / .Files .KubeVersion, .APIVersions.Has / weitere Dateien (Tag 8)

Drill 1: Eine ConfigMap aus eingebauten Objekten

# auf 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

Erwartet:

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

Ohne Cluster nimmt helm template an: Namespace default, Revision 1, Installation, Kubernetes v1.37.0. {{/* … */}} ist ein Template-Kommentar – er taucht im Ergebnis nicht auf. .Revision braucht quote, weil ConfigMap-Daten Strings sein müssen.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Install oder Upgrade?

# auf 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'

Erwartet:

  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 schaltet nur den Schalter um, die Revision bleibt beim Rendern 1. Im Cluster stehen die echten Werte: Revision 10, die genaue k3s-Version. So erkennt ein Template, ob es zum ersten Mal läuft – nützlich für einmalige Aktionen (Tag 7, 11).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Was kann der Cluster?

.Capabilities.APIVersions.Has fragt, ob eine API da ist. k3s 1.37 bringt die Gateway-API-CRDs mit (Tag 0, Drill 5). Du ergänzt zwei Zeilen am Ende der ConfigMap:

# auf 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'

Erwartet:

  gatewayAPI: "false"
  httpRoute: "false"
  gatewayAPI: "true"
  httpRoute: "true"
  gatewayAPI: "true"
  httpRoute: "false"

Ohne Cluster: nichts da. Mit --dry-run=server fragt helm template den echten Cluster. Mit -a (--api-versions) gibst du APIs vor – aber group/version und group/version/Kind sind getrennte Einträge. Eine Action darf über mehrere Zeilen gehen, so bleibt die Zeile kurz.

Tipp: Das alte helm template --validate ist in Helm 4 veraltet und meldet use '--dry-run=server' instead.

# auf 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"}'

Erwartet:

REVISION: 11
true

Fortschritt speichern? Kostenlos registrieren

Drill 4: Punkt und Pipe

Für Experimente legst du eine Spielwiese an, die du am Ende wieder löschst.

# auf 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

Erwartet:

---
# 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 und b sind gleich: einmal als Fließband von links nach rechts, einmal verschachtelt von innen nach außen. c zeigt die Regel: Der Pipe-Wert x landet als letztes Argument von printf. e ist die Falle: YAML hat 1.20 schon beim Einlesen von spiel.yaml zur Zahl 1.2 gemacht – quote kommt zu spät. Versionen schreibst du schon in der Werte-Datei in Anführungszeichen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die quote-Falle im Cluster

d: true ist ein Boolean, ConfigMap-Daten müssen Strings sein. Wer merkt das?

# auf 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

Erwartet:

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}

Achtung: helm install --dry-run=server schickt die Objekte nicht zur Prüfung an die API. Es fragt den Cluster nur für lookup und .Capabilities. Den Typfehler findet erst kubectl apply --dry-run=server – oder die echte Installation.

Strings bekommen immer | quote. Zahlen wie Ports und Replikas lässt du ohne, sonst lehnt Kubernetes sie als String ab.

# auf 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

Erwartet:

release "spiel" uninstalled
namespace "tag04" deleted
REVISION: 12

Die gescheiterte Installation blieb als Release im Status failed stehen – darum das uninstall.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Kaputtes YAML finden

# auf 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

Erwartet:

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

Ohne --debug siehst du nur die Zeilennummer im gerenderten Dokument, nicht im Template. Mit --debug gibt Helm das kaputte YAML aus, und du siehst die Stelle.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Rendere die ConfigMap so, als wäre es ein Upgrade in notes. Zeitziel: 20 s
  2. Zeig, welche Kubernetes-Version helm template ohne Cluster annimmt. Zeitziel: 20 s
  3. Lies die aktuelle Revision aus der ConfigMap im Cluster. Zeitziel: 20 s
  4. Rendere die ConfigMap für Kubernetes 1.36.4. Zeitziel: 20 s

Lösung

# auf 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

Erwartet (gekürzt):

  installOderUpgrade: upgrade
  kube: v1.37.0
12
  kube: v1.36.4

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

# auf prod
helm list -n notes

Erwartet: notes mit Revision 12, notes-0.3.0, deployed.

# auf prod
kubectl -n notes get configmap notes-info -o jsonpath='{.data.chart} {.data.httpRoute}'

Erwartet: notes-0.3.0 true

# auf prod
ls notes/templates

Erwartet: NOTES.txt configmap.yaml deployment.yaml service.yaml – keine Spielwiese mehr.

Challenge

Deine CI-Pipeline hat keinen Zugang zum Cluster, soll aber genau so rendern wie --dry-run=server. Erzeuge eine Liste aller APIs samt Kinds aus dem Cluster und beweise mit diff, dass helm template damit dasselbe Ergebnis liefert.

Hinweis: kubectl api-versions liefert nur group/version, die Kinds stehen in kubectl api-resources.

Lösung

# auf 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

Erwartet:

gateway.networking.k8s.io/v1/HTTPRoute
gleich

$(NF-2) ist die Spalte APIVERSION, $NF die Spalte KIND – von hinten gezählt, weil SHORTNAMES oft leer ist. Die Datei apis.txt legst du pro Zielcluster ins Repo und aktualisierst sie bei jedem Cluster-Upgrade.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

# auf prod
git add -A
git commit -qm "Tag 04: eingebaute Objekte, notes 0.3.0"

Interview-Notiz

  • Was bedeutet der Punkt in einem Template? Der aktuelle Kontext. Oben ist es die Wurzel mit .Values, .Release usw.; range und with setzen ihn um (Tag 5).
  • Wie machst du ein Chart für mehrere Kubernetes-Versionen fit? Mit .Capabilities.APIVersions.Has und .Capabilities.KubeVersion im Template plus kubeVersion in Chart.yaml als harte Grenze.
  • Prüft helm install --dry-run=server die Manifeste? Nein, es aktiviert nur Cluster-Abfragen. Validieren gegen die API macht kubectl apply --dry-run=server.

Enterprise-Notiz

  • CI rendert mit --kube-version und --api-versions des Zielclusters, sonst testet sie ein anderes Ergebnis als das, was installiert wird.
  • Zusätzlich helm template | kubectl apply --dry-run=server gegen einen Staging-Cluster – fängt Typfehler, die Helm durchlässt (Tag 17).
  • Distributionen unterscheiden sich in mitgelieferten CRDs (Gateway API in k3s, Routen in OpenShift). Charts fragen nach der API, nicht nach der Distribution.