Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: Das eigene Chart – Aufbau und Chart.yaml

Ziel: Das Chart notes von Hand anlegen, paketieren und als Release notes installieren – und wissen, welche Datei wohin gehört und welche Version was bedeutet. · Dauer: ca. 45 min · Voraussetzung: Tag 1

Briefing

  • Ein Chart ist ein Ordner mit festen Namen: Chart.yaml (Ausweis), values.yaml (Standardwerte, ab Tag 3), templates/ (wird gerendert), charts/ (Subcharts).
  • In templates/ wird alles gerendert – außer Dateien, die mit _ beginnen. NOTES.txt erscheint nach der Installation.
  • version ist die SemVer-Version des Charts, appVersion die der App. Sie sind unabhängig.
  • Heute noch ohne Werte: Die Manifeste sind fertiges YAML, nur NOTES.txt nutzt schon die eingebauten Objekte .Chart und .Release. Ab Tag 3 kommen Werte.
 notes/
 ├── Chart.yaml        Name, version 0.1.0, appVersion "0.7.1", kubeVersion
 ├── .helmignore       was nicht ins Paket soll
 ├── README.md
 └── templates/
     ├── NOTES.txt     Text nach install/upgrade
     ├── deployment.yaml
     └── service.yaml

Drill 1: helm create ansehen und wegwerfen

helm create liefert ein Gerüst mit allem, was Charts üblicherweise haben. Zum Lernen ist es zu viel – du schaust es dir einmal an.

# auf prod
mkdir -p ~/helm/tag02 && cd ~/helm/tag02
helm create demo
tree -a demo
cat demo/templates/*.yaml demo/templates/_helpers.tpl demo/values.yaml | wc -l
helm template demo ./demo | grep '^kind:'

Erwartet:

Creating demo
demo
├── .helmignore
├── Chart.yaml
├── charts
├── templates
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── hpa.yaml
│   ├── httproute.yaml
│   ├── ingress.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   └── tests
│       └── test-connection.yaml
└── values.yaml

4 directories, 12 files
442
kind: ServiceAccount
kind: Service
kind: Deployment
kind: Pod

442 Zeilen für ein nginx. Neu in Helm 4 ist httproute.yaml für die Gateway API. Das kind: Pod ist ein Test-Hook. Jeden dieser Bausteine baust du in den nächsten Tagen selbst – dann verstehst du ihn.

# auf prod
rm -rf demo

Fortschritt speichern? Kostenlos registrieren

Drill 2: Chart.yaml von Hand

Das Chart lebt im git-Repo aus Tag 0.

# auf prod
mkdir -p ~/helm/charts/notes/templates && cd ~/helm/charts
cat > notes/Chart.yaml <<'EOF'
# notes/Chart.yaml – Stand Tag 02
apiVersion: v2
name: notes
description: Notiz-API mit PostgreSQL – Übungschart aus „Helm Charts zum Anfassen“
type: application
version: 0.1.0
appVersion: "0.7.1"
kubeVersion: ">=1.33.0-0"
maintainers:
  - name: Helm Lab
    email: [email protected]
EOF
helm lint notes
helm show chart notes

Erwartet:

==> Linting notes
[INFO] Chart.yaml: icon is recommended
[INFO] values.yaml: file does not exist

1 chart(s) linted, 0 chart(s) failed
apiVersion: v2
appVersion: 0.7.1
description: Notiz-API mit PostgreSQL – Übungschart aus „Helm Charts zum Anfassen“
kubeVersion: '>=1.33.0-0'
maintainers:
- email: [email protected]
  name: Helm Lab
name: notes
type: application
version: 0.1.0
Feld Bedeutung
apiVersion: v2 Chart-Format von Helm 3 und 4
type application oder library (Tag 10)
version Chart-Version, SemVer, steigt bei jeder Änderung am Chart
kubeVersion Welche Kubernetes-Versionen das Chart verträgt

Das -0 in >=1.33.0-0 lässt auch Vorabversionen durch, wie sie Managed-Cluster melden (v1.36.4-gke.1043002). Build-Suffixe wie +k3s1 stören ohnehin nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die ersten Templates

Noch fertiges YAML ohne Platzhalter. Ohne NOTES_DB_URL speichert notes-api im Speicher – die Datenbank kommt in Tag 9. Den API-Key schreibst du heute direkt hinein; ab Tag 8 kommt er aus einem Secret.

# auf prod
cat > notes/templates/deployment.yaml <<'EOF'
# notes/templates/deployment.yaml – Stand Tag 02
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notes-api
  labels: {app.kubernetes.io/name: notes-api}
spec:
  replicas: 2
  selector:
    matchLabels: {app.kubernetes.io/name: notes-api}
  template:
    metadata:
      labels: {app.kubernetes.io/name: notes-api}
    spec:
      containers:
        - name: notes-api
          image: ghcr.io/thomaszachmann/notes-api:0.7.1
          ports: [{name: http, containerPort: 8080}]
          env:
            - {name: NOTES_API_KEY, value: lab-key-123}
          readinessProbe:
            httpGet: {path: /healthz, port: http}
EOF
cat > notes/templates/service.yaml <<'EOF'
# notes/templates/service.yaml – Stand Tag 02
apiVersion: v1
kind: Service
metadata:
  name: notes-api
  labels: {app.kubernetes.io/name: notes-api}
spec:
  selector: {app.kubernetes.io/name: notes-api}
  ports: [{name: http, port: 80, targetPort: http}]
EOF
helm template notes ./notes | grep -E '^(# Source|kind)'
helm template notes ./notes -s templates/service.yaml

Erwartet:

# Source: notes/templates/service.yaml
kind: Service
# Source: notes/templates/deployment.yaml
kind: Deployment
---
# Source: notes/templates/service.yaml
# notes/templates/service.yaml – Stand Tag 02
apiVersion: v1
kind: Service
metadata:
  name: notes-api
  labels: {app.kubernetes.io/name: notes-api}
spec:
  selector: {app.kubernetes.io/name: notes-api}
  ports: [{name: http, port: 80, targetPort: http}]

Helm sortiert nach Art: Der Service kommt vor dem Deployment, egal wie die Dateien heißen. # Source: zeigt, aus welcher Datei ein Dokument stammt. -s (--show-only) zeigt nur eine Datei – dein Messgerät für den Rest des Buchs.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ordnerregeln

Was passiert mit Dateien, die nicht nach Manifest aussehen?

# auf prod
cat > notes/templates/_entwurf.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata: {name: entwurf}
EOF
echo "Hier kommt später die Doku hin." > notes/templates/liesmich.txt
helm template notes ./notes | grep '^kind:'

Erwartet:

Error: YAML parse error on notes/templates/liesmich.txt: error unmarshaling JSON: while
decoding JSON: json: cannot unmarshal string into Go value of type util.SimpleHead

Use --debug flag to render out invalid YAML

Die Endung ist egal: Helm rendert jede Datei in templates/ und erwartet ein Kubernetes-Objekt. Die ConfigMap in _entwurf.yaml dagegen taucht nie auf – der Unterstrich heißt „nur Bausteine“. Doku gehört nach README.md neben Chart.yaml.

# auf prod
rm notes/templates/liesmich.txt
helm template notes ./notes | grep '^kind:'
cat > notes/templates/NOTES.txt <<'EOF'
{{- /* notes/templates/NOTES.txt – Stand Tag 02 */ -}}
notes {{ .Chart.AppVersion }} ist als Release {{ .Release.Name }} installiert.
Test: kubectl -n {{ .Release.Namespace }} port-forward svc/notes-api 8080:80
EOF
cat > notes/README.md <<'EOF'
# notes

Übungschart aus „Helm Charts zum Anfassen“. Werte siehe values.yaml (ab Tag 3).
EOF

Erwartet:

kind: Service
kind: Deployment

NOTES.txt ist die einzige Ausnahme: Sie wird gerendert, aber nicht an den Cluster geschickt, sondern nach install und upgrade ausgegeben.

Fortschritt speichern? Kostenlos registrieren

Drill 5: .helmignore, Paket und Release

# auf prod
mkdir -p notes/entwurf && echo "alte Idee" > notes/entwurf/idee.txt
cat > notes/.helmignore <<'EOF'
# notes/.helmignore – Stand Tag 02
.git/
*.swp
*~
entwurf/
EOF
helm package notes -d ~/helm/tag02
tar -tzf ~/helm/tag02/notes-0.1.0.tgz
helm show chart ~/helm/tag02/notes-0.1.0.tgz | grep -E '^(name|version|appVersion)'

Erwartet:

Successfully packaged chart and saved it to: /home/ubuntu/helm/tag02/notes-0.1.0.tgz
notes/Chart.yaml
notes/templates/NOTES.txt
notes/templates/_entwurf.yaml
notes/templates/deployment.yaml
notes/templates/service.yaml
notes/.helmignore
notes/README.md
appVersion: 0.7.1
name: notes
version: 0.1.0

entwurf/ fehlt im Paket, _entwurf.yaml ist drin – sie liegt in templates/ und ist nicht ignoriert, erzeugt aber kein Objekt. Der Dateiname notes-0.1.0.tgz kommt aus name und version. Jetzt der Release, der dich durchs Buch begleitet:

# auf prod
helm install notes ~/helm/tag02/notes-0.1.0.tgz -n notes --create-namespace \
  --wait --timeout 3m
kubectl -n notes port-forward svc/notes-api 8080:80 >/dev/null 2>&1 &
sleep 3
curl -s localhost:8080/healthz
curl -s -X POST -H 'X-API-Key: lab-key-123' -H 'Content-Type: application/json' \
  -d '{"text":"Tag 2"}' localhost:8080/notes
kill %1

Erwartet (gekürzt):

NAME: notes
NAMESPACE: notes
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
NOTES:
notes 0.7.1 ist als Release notes installiert.
Test: kubectl -n notes port-forward svc/notes-api 8080:80
ok
{"id":"a48b87ce-b86e-4d34-a50a-5ca6ffd1731b","text":"Tag 2"}

Die Notiz liegt nur im Speicher eines der beiden Pods. Das ändert sich mit der Datenbank in Tag 9.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Versionen, die keine sind

YAML rät Typen. Was wird aus appVersion: 2.10 ohne Anführungszeichen?

# auf prod
sed -i 's/^appVersion: "0.7.1"/appVersion: 2.10/' notes/Chart.yaml
helm lint notes | grep ERROR
helm show chart notes | grep appVersion
helm package notes -d /tmp/x | tail -1
sed -i 's/^appVersion: 2.10/appVersion: "0.7.1"/' notes/Chart.yaml

Erwartet:

[ERROR] Chart.yaml: appVersion should be of type string but it's of type float64
appVersion: "2.1"
Successfully packaged chart and saved it to: /tmp/x/notes-0.1.0.tgz

Aus 2.10 wird die Zahl 2.1. helm lint meldet einen Fehler, helm package packt trotzdem. Bei version ist es ähnlich lax:

# auf prod
for v in '"0.1"' 'v0.1.0' 'eins' '1.0.0+build.7'; do
  sed -i "s/^version: .*/version: $v/" notes/Chart.yaml
  echo "== $v"; helm package notes -d /tmp/x 2>&1 | tail -1
done
sed -i 's/^version: .*/version: 0.1.0/' notes/Chart.yaml
rm -rf /tmp/x

Erwartet:

== "0.1"
Successfully packaged chart and saved it to: /tmp/x/notes-0.1.tgz
== v0.1.0
Successfully packaged chart and saved it to: /tmp/x/notes-v0.1.0.tgz
== eins
Error: validation: chart.metadata.version "eins" is invalid
== 1.0.0+build.7
Successfully packaged chart and saved it to: /tmp/x/notes-1.0.0+build.7.tgz

Nur völliger Unsinn scheitert. "0.1" gibt bei helm lint nur eine Warnung (not a valid SemVerV2), v0.1.0 nicht einmal das. Halte dich trotzdem an MAJOR.MINOR.PATCH: Patch für Fehlerbehebungen, Minor für neue Optionen, Major, wenn Nutzer ihre Werte anpassen müssen. Das +build-Suffix begegnet dir in Tag 15 wieder.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Chart v3 – nur ein Blick

Helm 4 bringt ein experimentelles Chart-Format apiVersion: v3 mit.

# auf prod
cd ~/helm/tag02
helm create v3demo --chart-api-version v3
HELM_EXPERIMENTAL_CHART_V3=1 helm create v3demo --chart-api-version v3
grep '^apiVersion' v3demo/Chart.yaml
HELM_EXPERIMENTAL_CHART_V3=1 helm template x ./v3demo
rm -rf v3demo
cd ~/helm/charts

Erwartet:

Creating v3demo
Error: this feature has been marked as experimental and is not enabled by default.
Please set HELM_EXPERIMENTAL_CHART_V3=1 in your environment to use this feature
Creating v3demo
apiVersion: v3
Error: invalid chart apiVersion

In Helm 4.3.2 lässt sich ein v3-Chart nur anlegen, nicht rendern oder installieren – auch mit gesetzter Variable nicht. Für alles im Buch und in der Praxis gilt apiVersion: v2; bestehende Charts laufen unter Helm 4 unverändert.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Zeig, welche Dateien im Paket notes-0.1.0.tgz stecken. Zeitziel: 10 s
  2. Zeig Chart- und App-Version des installierten Releases. Zeitziel: 20 s
  3. Rendere nur das Deployment. Zeitziel: 15 s
  4. Zeig die NOTES des Releases noch einmal. Zeitziel: 10 s

Lösung

# auf prod
tar -tzf ~/helm/tag02/notes-0.1.0.tgz
helm get metadata notes -n notes | grep -E '^(VERSION|APP_VERSION)'
helm template notes ./notes -s templates/deployment.yaml
helm get notes notes -n notes

Erwartet (gekürzt):

notes/Chart.yaml
...
VERSION: 0.1.0
APP_VERSION: 0.7.1
# Source: notes/templates/deployment.yaml
...
NOTES:
notes 0.7.1 ist als Release notes installiert.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

# auf prod
helm list -n notes

Erwartet:

NAME   NAMESPACE  REVISION  UPDATED  STATUS    CHART        APP VERSION
notes  notes      1         ...      deployed  notes-0.1.0  0.7.1
# auf prod
kubectl -n notes get deploy notes-api

Erwartet: READY 2/2.

# auf prod
helm lint notes | tail -1

Erwartet: 1 chart(s) linted, 0 chart(s) failed

Challenge

Was passiert, wenn kubeVersion deinen Cluster ausschließt? Setze >=1.38.0-0 und probiere helm lint, helm template und ein Upgrade mit --dry-run=server. Bring helm template dazu, trotzdem zu rendern.

Hinweis: helm template kennt deinen Cluster nicht und nimmt eine eingebaute Kubernetes-Version an.

Lösung

# auf prod
sed -i 's/^kubeVersion: .*/kubeVersion: ">=1.38.0-0"/' notes/Chart.yaml
helm lint notes | tail -1
helm template notes ./notes > /dev/null
helm upgrade notes ./notes -n notes --dry-run=server 2>&1 | head -1
helm template notes ./notes --kube-version 1.38.0 | grep -c '^kind:'
sed -i 's/^kubeVersion: .*/kubeVersion: ">=1.33.0-0"/' notes/Chart.yaml

Erwartet:

1 chart(s) linted, 0 chart(s) failed
Error: chart requires kubeVersion: >=1.38.0-0 which is incompatible with Kubernetes
v1.37.0
Error: UPGRADE FAILED: chart requires kubeVersion: >=1.38.0-0 which is incompatible
with Kubernetes v1.37.2+k3s1
2

helm lint prüft kubeVersion nicht. helm template nimmt ohne Cluster v1.37.0 an – die Version, mit der Helm 4.3 gebaut ist. Mit --kube-version gibst du sie vor. Das Upgrade fragt den echten Cluster. Dass CI und Cluster verschiedene Versionen sehen, vertieft Tag 4.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

Entwurf und Experimente fliegen raus, der Stand kommt ins git-Repo.

# auf prod
cd ~/helm/charts
rm -r notes/templates/_entwurf.yaml notes/entwurf
git add notes
git commit -qm "Tag 02: notes 0.1.0 ohne Templates"
git log --oneline

Erwartet:

beabaab Tag 02: notes 0.1.0 ohne Templates
eeb85c7 Tag 00: leeres Chart-Repo

„Ohne Templates“ heißt hier: Die Manifeste haben noch keine Platzhalter. NOTES.txt nutzt schon .Chart und .Release.

Interview-Notiz

  • Wozu dient der Unterstrich in _helpers.tpl? Dateien mit _ erzeugen kein Manifest, sie enthalten nur benannte Templates. Alle anderen Dateien in templates/ werden gerendert und müssen Kubernetes-Objekte ergeben.
  • Wann erhöhst du welche Stelle der Chart-Version? Bei jeder Änderung am Chart mindestens Patch, Minor bei neuen Optionen, Major, wenn Nutzer etwas anpassen müssen.
  • version oder appVersion? version gehört zum Chart und bestimmt das Paket, appVersion beschreibt die App und dient oft als Standard-Image-Tag.

Enterprise-Notiz

  • helm lint als Pflichtschritt in CI – helm package allein lässt Fehler wie appVersion: 2.10 durch.
  • Eine veröffentlichte Chart-Version ist unveränderlich. Jede Änderung, auch an der README, bekommt eine neue Version (Tag 18 prüft das mit ct lint).
  • kubeVersion ehrlich pflegen: Es ist die einzige Sperre, die Nutzer vor einem Chart für eine zu alte oder zu neue Kubernetes-Version schützt.
  • Eigene Gerüste über helm create --starter statt jedes Team mit dem nginx-Beispiel anfangen zu lassen.