Tag 2: Das eigene Chart – Aufbau und Chart.yaml
Ziel: Das Chart
notesvon Hand anlegen, paketieren und als Releasenotesinstallieren – 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.txterscheint nach der Installation. versionist die SemVer-Version des Charts,appVersiondie der App. Sie sind unabhängig.- Heute noch ohne Werte: Die Manifeste sind fertiges YAML, nur
NOTES.txtnutzt schon die eingebauten Objekte.Chartund.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 demoFortschritt 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 notesErwartet:
==> 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.yamlErwartet:
# 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).
EOFErwartet:
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 %1Erwartet (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.yamlErwartet:
[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/xErwartet:
== "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/chartsErwartet:
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
- Zeig, welche Dateien im Paket
notes-0.1.0.tgzstecken. Zeitziel: 10 s - Zeig Chart- und App-Version des installierten Releases. Zeitziel: 20 s
- Rendere nur das Deployment. Zeitziel: 15 s
- 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 notesErwartet (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 notesErwartet:
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-apiErwartet: READY 2/2.
# auf prod
helm lint notes | tail -1Erwartet:
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.yamlErwartet:
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 --onelineErwartet:
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 intemplates/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?
versiongehört zum Chart und bestimmt das Paket,appVersionbeschreibt die App und dient oft als Standard-Image-Tag.
Enterprise-Notiz
helm lintals Pflichtschritt in CI –helm packageallein lässt Fehler wieappVersion: 2.10durch.- 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). kubeVersionehrlich 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 --starterstatt jedes Team mit dem nginx-Beispiel anfangen zu lassen.