Tag 6: HelmRelease
Ziel: notes-api als eigenes Helm-Chart verpacken, in die Registry schieben und von Flux installieren lassen, mit Werten aus Git, automatischen Chart-Updates und Drift-Korrektur. · Dauer: ca. 75 min · Voraussetzung: Tag 5
Briefing
- Viele Anwendungen kommen als Helm-Chart. Flux
installiert Charts mit dem helm-controller. Das Objekt
dafür heißt
HelmRelease. - Der HelmRelease sagt, welches Chart in welcher Version mit welchen
Werten installiert werden soll. Der helm-controller führt dann
helm installbzw.helm upgradeaus, ganz ohne Helm-CLI. - Das Chart kommt aus einer Source. Seit Flux 2.10
zeigt ein HelmRelease direkt per
chartRefauf eineOCIRepository. Für Charts in klassischen Helm-Repos gibt esHelmRepository(Tag 7).
helm push ──► Registry :30500/charts/notes:0.1.0, 0.2.0
▲
OCIRepository notes-chart (semver 0.x) ── chartRef ──► HelmRelease notes
values + valuesFrom
│ helm upgrade
▼
Namespace notes-helm, Port 30090
Drill 1: Ein Chart bauen
Das Chart ist bewusst klein: notes-api ohne Datenbank. Es liegt außerhalb des Fleet-Repos, denn ein Chart ist ein Produkt, das du baust und veröffentlichst, kein gewünschter Zustand.
mkdir -p ~/flux-lab/charts/notes/templates
cd ~/flux-lab/charts
cat > notes/Chart.yaml <<'EOF'
apiVersion: v2
name: notes
description: notes-api ohne Datenbank
version: 0.1.0
appVersion: "0.5.3"
EOF
cat > notes/values.yaml <<'EOF'
replicas: 1
image:
repository: ghcr.io/thomaszachmann/notes-api
tag: ""
apiKey: ""
nodePort: 30090
EOF
cat > notes/templates/secret.yaml <<'EOF'
apiVersion: v1
kind: Secret
metadata:
name: {{ .Release.Name }}-api
stringData:
apiKey: {{ required "apiKey fehlt" .Values.apiKey | quote }}
EOF
cat > notes/templates/deployment.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}
spec:
replicas: {{ .Values.replicas }}
selector:
matchLabels:
app: {{ .Release.Name }}
template:
metadata:
labels:
app: {{ .Release.Name }}
spec:
containers:
- name: api
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
ports:
- containerPort: 8080
env:
- name: NOTES_API_KEY
valueFrom:
secretKeyRef:
name: {{ .Release.Name }}-api
key: apiKey
readinessProbe:
httpGet:
path: /healthz
port: 8080
EOF
cat > notes/templates/service.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
name: {{ .Release.Name }}
spec:
type: NodePort
selector:
app: {{ .Release.Name }}
ports:
- port: 80
targetPort: 8080
nodePort: {{ .Values.nodePort }}
EOF
helm lint notesErwartet:
level=WARN msg="missing required values" message="apiKey fehlt"
==> Linting notes
[INFO] Chart.yaml: icon is recommended
1 chart(s) linted, 0 chart(s) failed
- Ohne Tag nimmt das Image die
appVersiondes Charts. Ein neues Chart bringt so eine neue notes-api mit. requiredlässt die Installation scheitern, wenn kein API-Key gesetzt ist. Die Warnung vonhelm lintmeint genau das.
Verpacken und in die Registry aus Tag 3 schieben:
helm package notes
helm push notes-0.1.0.tgz oci://localhost:30500/charts --plain-httpErwartet (der Digest weicht ab):
Successfully packaged chart and saved it to: /home/ubuntu/flux-lab/charts/notes-0.1.0.tgz
Pushed: localhost:30500/charts/notes:0.1.0
Digest: sha256:473d8ab7cd17f2c10c42ffcead92295d7eb0e06e0633488b0bdd029226b9c531
Fortschritt speichern? Kostenlos registrieren
Drill 2: Der HelmRelease
notes-helm bekommt einen eigenen Ordner mit Namespace, Quelle und
HelmRelease. Quelle und HelmRelease liegen im Namespace der Anwendung,
nicht in flux-system.
cd ~/flux-lab/fleet
mkdir -p apps/notes-helm
cd apps/notes-helm
printf 'apiVersion: v1\nkind: Namespace\nmetadata:\n name: notes-helm\n' > namespace.yaml
flux create source oci notes-chart --namespace=notes-helm \
--url=oci://registry.registry.svc.cluster.local:5000/charts/notes \
--tag-semver="0.x" --insecure --interval=5m \
--layer-selector=application/vnd.cncf.helm.chart.content.v1.tar+gzip:copy \
--export > source.yaml
cat source.yamlErwartet:
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
name: notes-chart
namespace: notes-helm
spec:
insecure: true
interval: 5m0s
layerSelector:
mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip
operation: copy
provider: generic
ref:
semver: 0.x
url: oci://registry.registry.svc.cluster.local:5000/charts/notes
Der layerSelector sagt Flux, welcher
Teil des OCI-Artefakts das Chart ist. Ein Helm-Chart in einer Registry
hat einen eigenen Medientyp, und copy übernimmt das Archiv
unverändert, so wie Helm es erwartet.
Die Werte schreibst du in eine Datei, flux create
übernimmt sie in den HelmRelease:
printf 'apiKey: lab-api-key-123\nnodePort: 30090\n' > /tmp/werte.yaml
flux create helmrelease notes --namespace=notes-helm \
--chart-ref=OCIRepository/notes-chart.notes-helm \
--values=/tmp/werte.yaml --interval=10m --export > release.yaml
rm /tmp/werte.yaml
cat release.yamlErwartet:
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: notes
namespace: notes-helm
spec:
chartRef:
kind: OCIRepository
name: notes-chart
namespace: notes-helm
interval: 10m0s
values:
apiKey: lab-api-key-123
nodePort: 30090
cat > kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- namespace.yaml
- source.yaml
- release.yaml
EOF
cd ~/flux-lab/fleet
flux create kustomization notes-helm --source=GitRepository/flux-system \
--path=./apps/notes-helm --prune=true --interval=10m --wait=true \
--export > clusters/lab/notes-helm.yaml
git add -A
git commit -m "notes per Helm"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helm
flux get helmreleases -AErwartet (gekürzt):
NAMESPACE NAME REVISION SUSPENDED READY MESSAGE
notes-helm notes 0.1.0+473d8ab7cd17 False True Helm install succeeded for release notes-helm/notes.v1 with chart [email protected]+473d8ab7cd17
- Die Revision
0.1.0+473d8ab7cd17ist die Chart-Version plus der Anfang des Digests. Wird dieselbe Version neu gepusht, bemerkt Flux es trotzdem. wait: truean der Kustomization wartet auch auf den HelmRelease. Flux kennt den Zustand seiner eigenen Objekte.
Für Helm selbst ist das eine ganz normale Installation:
helm -n notes-helm list
curl -s localhost:30090/versionErwartet (gekürzt):
NAME NAMESPACE REVISION UPDATED ... STATUS CHART APP VERSION
notes notes-helm 1 2026-11-12 ... deployed notes-0.1.0+473d8ab7cd17 0.5.3
0.5.3
Fortschritt speichern? Kostenlos registrieren
Drill 3: Werte aus einer Datei
Werte direkt im HelmRelease werden schnell unübersichtlich. Besser:
eine eigene values.yaml, aus der Kustomize eine ConfigMap
erzeugt.
cd ~/flux-lab/fleet/apps/notes-helm
printf 'replicas: 2\n' > values.yaml
cat >> kustomization.yaml <<'EOF'
configMapGenerator:
- name: notes-values
namespace: notes-helm
files:
- values.yaml
EOF
cat >> release.yaml <<'EOF'
valuesFrom:
- kind: ConfigMap
name: notes-values
EOF
cd ~/flux-lab/fleet
git add -A
git commit -m "notes-helm: Werte aus ConfigMap"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helmDie CLI wartet und wartet. Was ist los?
flux get helmreleases -n notes-helmErwartet:
NAME REVISION SUSPENDED READY MESSAGE
notes 0.1.0+473d8ab7cd17 False False could not resolve ConfigMap chart values reference 'notes-helm/notes-values' with key 'values.yaml': configmaps "notes-values" not found
Ctrl+C beendet das Warten. Der Grund steht in der gebauten Ausgabe:
kubectl kustomize apps/notes-helm | grep -E 'name: notes-values'Erwartet:
name: notes-values-k946m65mmb
name: notes-values
Kustomize hängt an erzeugte ConfigMaps einen Hash an. Ändert sich der Inhalt, ändert sich der Name, und alles, was auf die ConfigMap zeigt, wird angepasst. Allerdings nur Felder, die Kustomize kennt, wie die in einem Deployment. Ein HelmRelease ist für Kustomize unbekannt. Du bringst es ihm bei:
cd ~/flux-lab/fleet/apps/notes-helm
cat > kustomizeconfig.yaml <<'EOF'
nameReference:
- kind: ConfigMap
version: v1
fieldSpecs:
- path: spec/valuesFrom/name
kind: HelmRelease
EOF
cat >> kustomization.yaml <<'EOF'
configurations:
- kustomizeconfig.yaml
EOF
cd ~/flux-lab/fleet
kubectl kustomize apps/notes-helm | grep -A2 valuesFromErwartet:
valuesFrom:
- kind: ConfigMap
name: notes-values-k946m65mmb
git add -A
git commit -m "notes-helm: Hash-Namen auflösen"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helm
helm -n notes-helm history notesErwartet (gekürzt):
REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION
1 Thu Nov 12 16:20:06 2026 superseded notes-0.1.0+473d8ab7cd17 0.5.3 Install complete
2 Thu Nov 12 16:24:41 2026 deployed notes-0.1.0+473d8ab7cd17 0.5.3 Upgrade complete
Der Hash hat einen Vorteil: Jede Änderung an values.yaml
ändert den Namen, damit den HelmRelease, und löst sofort ein
Helm-Upgrade aus.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ein neues Chart, kein Commit
Die Quelle folgt semver: 0.x. Ein neues Chart in der
Registry genügt für ein Update:
cd ~/flux-lab/charts
sed -i 's/^version: 0.1.0/version: 0.2.0/; s/^appVersion: "0.5.3"/appVersion: "0.7.1"/' \
notes/Chart.yaml
helm package notes
helm push notes-0.2.0.tgz oci://localhost:30500/charts --plain-http
flux reconcile source oci notes-chart -n notes-helmErwartet (gekürzt):
Pushed: localhost:30500/charts/notes:0.2.0
...
✔ fetched revision 0.2.0@sha256:a8d3ddcf1a01dde67481c532decf21e1aee80725b010371ea020ff50bd592275
Ein paar Sekunden später:
flux get helmreleases -n notes-helm
curl -s localhost:30090/versionErwartet:
NAME REVISION SUSPENDED READY MESSAGE
notes 0.2.0+a8d3ddcf1a01 False True Helm upgrade succeeded for release notes-helm/notes.v3 with chart [email protected]+a8d3ddcf1a01
0.7.1
Das ist der Weg, über den Plattform-Teams Charts an viele Cluster
verteilen: Sie veröffentlichen ein Chart, und jeder Cluster mit einem
passenden SemVer-Bereich zieht nach. In Git steht dann allerdings nicht
mehr die genaue Version. Was wann installiert wurde, verrät nur noch
helm history.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Drift bei Helm
Wie bei der Kustomization in Tag 2 skaliert jemand von Hand:
kubectl -n notes-helm scale deploy notes --replicas=5
flux reconcile helmrelease notes -n notes-helm
kubectl -n notes-helm get deploy notesErwartet:
deployment.apps/notes scaled
✔ applied revision 0.2.0+a8d3ddcf1a01
NAME READY UP-TO-DATE AVAILABLE AGE
notes 5/5 5 5 5m25s
Fünf statt zwei, und Flux tut nichts. Der helm-controller vergleicht standardmäßig nur den HelmRelease mit dem letzten Helm-Release, nicht mit dem Cluster. Das ändert ein Feld:
cd ~/flux-lab/fleet
cat >> apps/notes-helm/release.yaml <<'EOF'
driftDetection:
mode: enabled
EOF
git commit -am "notes-helm: Drift korrigieren"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helm
kubectl -n notes-helm get deploy notes
flux events --for HelmRelease/notes -n notes-helm | tail -3Erwartet (gekürzt):
NAME READY UP-TO-DATE AVAILABLE AGE
notes 2/2 2 2 5m48s
... DriftCorrected HelmRelease/notes Cluster state of release notes-helm/notes.v3 has been corrected:
Deployment/notes-helm/notes configured
mode: warn würde die Abweichung nur melden und nicht
korrigieren. Das ist ein guter erster Schritt, wenn ein Team mit
Helm-Releases umzieht, an denen bisher jeder von Hand gedreht hat.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
flux get helmreleases -n notes-helmErwartet: notes mit Revision 0.2.0+…,
READY True.
curl -s localhost:30090/versionErwartet: 0.7.1.
diff -r ~/flux-lab/fleet/apps/notes-helm ~/flux-lab/code/loesung/tag06/apps/notes-helmErwartet: keine Ausgabe.
Challenge
Version 0.2.0 des Charts macht in Produktion Ärger. Hol notes-helm
zurück auf 0.1.x, ohne das Chart in der Registry zu löschen. Was zeigt
helm history danach?
Lösung
sed -i 's/semver: 0.x/semver: 0.1.x/' apps/notes-helm/source.yaml
git commit -am "notes-helm: Chart 0.1.x"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helm
helm -n notes-helm history notes
curl -s localhost:30090/versionErwartet (gekürzt):
REVISION UPDATED STATUS CHART APP VERSION DESCRIPTION
1 Thu Nov 12 16:20:06 2026 superseded notes-0.1.0+473d8ab7cd17 0.5.3 Install complete
2 Thu Nov 12 16:24:41 2026 superseded notes-0.1.0+473d8ab7cd17 0.5.3 Upgrade complete
3 Thu Nov 12 16:25:00 2026 superseded notes-0.2.0+a8d3ddcf1a01 0.7.1 Upgrade complete
4 Thu Nov 12 16:26:12 2026 deployed notes-0.1.0+473d8ab7cd17 0.5.3 Upgrade complete
0.5.3
Für Helm ist das kein Rollback, sondern ein Upgrade auf ein älteres Chart. Flux kennt nur den gewünschten Zustand: Steht in Git 0.1.x, wird 0.1.x installiert, egal was vorher lief.
Für die nächsten Tage stellst du wieder auf 0.x:
git revert --no-edit HEAD
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-helmFortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
valuesist nicht geheim. Der API-Key steht im HelmRelease im Klartext, und jeder mit Leserechten auf HelmReleases sieht ihn. Geheime Werte kommen übervaluesFromaus einem Secret, verschlüsselt in Git (Tag 8).- Chart-Versionen pinnen:
semver: 0.xist im Lab bequem. In Produktion pinnst du die genaue Version und lässt Updates per Pull Request kommen, damit Git zeigt, was läuft. - Fremde Charts spiegeln: Viele Firmen holen Charts nicht direkt aus dem Internet, sondern spiegeln sie in eine eigene Registry wie Harbor. Fällt die Quelle aus oder wird ein Tag überschrieben, laufen die Cluster weiter.