Zum Inhalt springen
Trainingslager IT-Trainingslager

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 install bzw. helm upgrade aus, ganz ohne Helm-CLI.
  • Das Chart kommt aus einer Source. Seit Flux 2.10 zeigt ein HelmRelease direkt per chartRef auf eine OCIRepository. Für Charts in klassischen Helm-Repos gibt es HelmRepository (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 notes

Erwartet:

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 appVersion des Charts. Ein neues Chart bringt so eine neue notes-api mit.
  • required lässt die Installation scheitern, wenn kein API-Key gesetzt ist. Die Warnung von helm lint meint 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-http

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

Erwartet:

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

Erwartet:

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

Erwartet (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+473d8ab7cd17 ist die Chart-Version plus der Anfang des Digests. Wird dieselbe Version neu gepusht, bemerkt Flux es trotzdem.
  • wait: true an 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/version

Erwartet (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-helm

Die CLI wartet und wartet. Was ist los?

flux get helmreleases -n notes-helm

Erwartet:

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 valuesFrom

Erwartet:

  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 notes

Erwartet (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-helm

Erwartet (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/version

Erwartet:

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 notes

Erwartet:

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

Erwartet (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-helm

Erwartet: notes mit Revision 0.2.0+…, READY True.

curl -s localhost:30090/version

Erwartet: 0.7.1.

diff -r ~/flux-lab/fleet/apps/notes-helm ~/flux-lab/code/loesung/tag06/apps/notes-helm

Erwartet: 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/version

Erwartet (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-helm

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • values ist nicht geheim. Der API-Key steht im HelmRelease im Klartext, und jeder mit Leserechten auf HelmReleases sieht ihn. Geheime Werte kommen über valuesFrom aus einem Secret, verschlüsselt in Git (Tag 8).
  • Chart-Versionen pinnen: semver: 0.x ist 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.