Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 13: CI und Betrieb

Ziel: Das Fleet-Repo bei jedem Push von GitHub Actions prüfen lassen, Flux im Betrieb untersuchen, überwachen, aktualisieren und wissen, wie man es wieder loswird. · Dauer: ca. 75 min · Voraussetzung: Tag 12

Briefing

  • Flux prüft Manifeste erst im Cluster, per Dry-Run. Ein Tippfehler fällt also erst auf, wenn er schon auf main liegt. Eine CI prüft vorher, bei jedem Push und jedem Pull Request.
  • Geprüft wird in drei Schritten: Kustomize baut jeden Ordner, flux envsubst setzt Variablen ein, und kubeconform prüft jedes Objekt gegen das Schema seiner Art. Für die Arten von Flux liefert das Flux-Projekt die Schemas mit.
  • Im Betrieb stellst du drei Fragen: Woher kommt dieses Objekt? Was ist gerade kaputt? Wie lange dauert der Abgleich? Die Flux-CLI hat für jede einen Befehl.

Drill 1: Was die CI prüfen soll

Bevor ein Workflow läuft, probierst du die Prüfung auf der VM:

cd /tmp
curl -fsSL https://github.com/yannh/kubeconform/releases/download/v0.8.0/kubeconform-linux-amd64.tar.gz \
  | tar xz -C ~/.local/bin kubeconform
mkdir -p /tmp/flux-schemas
curl -fsSL https://github.com/fluxcd/flux2/releases/download/v2.10.0/crd-schemas.tar.gz \
  | tar xz -C /tmp/flux-schemas
ls /tmp/flux-schemas | head -3

Erwartet:

_definitions.json
alert-notification-v1.json
alert-notification-v1beta3.json

kubeconform kennt die Kubernetes-Arten von selbst (default). Für alles andere bekommt es eine Vorlage, unter der es das Schema findet:

cd ~/flux-lab/fleet
S='-schema-location default -schema-location /tmp/flux-schemas/{{.ResourceKind}}{{.KindSuffix}}.json'
kubectl kustomize clusters/lab | kubeconform -strict -summary -skip Secret $S

Erwartet (gekürzt):

stdin - CustomResourceDefinition alerts.notification.toolkit.fluxcd.io failed validation: could not find schema for CustomResourceDefinition
...
Summary: 64 resources found parsing stdin - Valid: 50, Invalid: 0, Errors: 14, Skipped: 0

Die 14 Fehler sind die CRDs aus gotk-components.yaml. Für die Art CustomResourceDefinition gibt es kein Schema, also überspringst du sie wie die Secrets. Secrets lässt du aus, weil SOPS sie mit einem Feld sops erweitert, das Kubernetes nicht kennt.

kubectl kustomize clusters/lab \
  | kubeconform -strict -summary -skip Secret,CustomResourceDefinition $S

Erwartet:

Summary: 64 resources found parsing stdin - Valid: 50, Invalid: 0, Errors: 0, Skipped: 14

Jetzt die Overlays von notes:

kubectl kustomize apps/notes/overlays/prod | kubeconform -strict -summary -skip Secret $S

Erwartet (gekürzt):

stdin - Deployment notes is invalid: … at '/spec/replicas': got string, want null or integer
Summary: 3 resources found parsing stdin - Valid: 1, Invalid: 1, Errors: 0, Skipped: 1

Richtig erkannt: Im Ordner steht replicas: ${NOTES_REPLICAS:=1}, ein Text. Erst Flux setzt beim Abgleich eine Zahl ein. flux envsubst macht dasselbe lokal. Für NOTES_VERSION gibt es keinen Standardwert, die CI bekommt deshalb einen Platzhalter:

kubectl kustomize apps/notes/overlays/prod | NOTES_VERSION=0.0.0-ci flux envsubst --strict \
  | kubeconform -strict -summary -skip Secret $S

Erwartet:

Summary: 3 resources found parsing stdin - Valid: 2, Invalid: 0, Errors: 0, Skipped: 1

Ohne Platzhalter wäre die Zeile image: ghcr.io/thomaszachmann/notes-api: übrig geblieben, und der Doppelpunkt am Ende macht daraus kaputtes YAML.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der Workflow

Workflow-Dateien darf ein Token nur ändern, wenn er das Recht Workflows: Read and write hat (Tag 0). Fehlt es, lehnt GitHub den Push ab, und du ergänzt es im Browser beim Token flux-lab:

 ! [remote rejected] main -> main (refusing to allow a Personal Access Token to create or update workflow `.github/workflows/validate.yaml` without `workflow` scope)

Der Workflow ist eine Datei im Repo:

mkdir -p .github/workflows
cat > .github/workflows/validate.yaml <<'EOF'
name: validate
on:
  pull_request:
  push:
    branches: [main]
jobs:
  manifests:
    runs-on: ubuntu-24.04
    env:
      NOTES_VERSION: 0.0.0-ci
      SCHEMAS: -schema-location default -schema-location /tmp/flux-schemas/{{.ResourceKind}}{{.KindSuffix}}.json
    steps:
      - uses: actions/checkout@v5
      - uses: fluxcd/flux2/[email protected]
        with:
          version: 2.10.0
      - name: kubeconform und Flux-Schemas
        run: |
          curl -fsSL https://github.com/yannh/kubeconform/releases/download/v0.8.0/kubeconform-linux-amd64.tar.gz | tar xz -C /usr/local/bin kubeconform
          mkdir -p /tmp/flux-schemas
          curl -fsSL https://github.com/fluxcd/flux2/releases/download/v2.10.0/crd-schemas.tar.gz | tar xz -C /tmp/flux-schemas
      - name: Cluster lab
        run: kubectl kustomize clusters/lab | kubeconform -strict -summary -skip Secret,CustomResourceDefinition $SCHEMAS
      - name: Apps und Infrastruktur
        run: |
          for d in $(find apps infrastructure -name kustomization.yaml -exec dirname {} \;); do
            echo "== $d"
            kubectl kustomize $d | flux envsubst --strict | kubeconform -strict -summary -skip Secret $SCHEMAS
          done
      - name: Mandanten
        run: kubeconform -strict -summary $SCHEMAS tenants
EOF
git add -A
git commit -m "CI: Manifeste prüfen"
git push
  • fluxcd/flux2/action installiert die Flux-CLI in der gewünschten Version.
  • Die Schleife findet jeden Ordner mit einer kustomization.yaml unter apps und infrastructure, auch neue, ohne dass jemand den Workflow anpassen muss.
  • tenants hat keine kustomization.yaml, also prüft kubeconform die Dateien direkt.

Auf GitHub erscheint unter flux-fleet → Actions ein Lauf validate. Ohne Browser siehst du dasselbe mit der GitHub-CLI auf deinem Laptop, falls du sie dort hast:

gh run list -R <du>/flux-fleet -L 1

Erwartet (gekürzt):

completed   success CI: Manifeste prüfen    validate    main    push    43275465547 15s …

Im Log des Schritts „Apps und Infrastruktur“ steht pro Ordner eine Zusammenfassung:

== apps/notes/overlays/prod
Summary: 3 resources found parsing stdin - Valid: 2, Invalid: 0, Errors: 0, Skipped: 1
...
== infrastructure/registry
Summary: 3 resources found parsing stdin - Valid: 3, Invalid: 0, Errors: 0, Skipped: 0

Rund 15 Sekunden für das ganze Repo. Am Commit erscheint ein grüner Haken, neben den Haken der Kustomizations aus Tag 11.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Woher kommt das?

Ein Kollege fragt: „Wer verwaltet eigentlich das Deployment notes?“

flux trace deployment notes -n notes

Erwartet (gekürzt):

Object:          Deployment/notes
Namespace:       notes
Status:          Managed by Flux
---
Kustomization:   notes
Namespace:       flux-system
Path:            ./apps/notes/overlays/prod
Revision:        main@sha1:3c42d9b575c2de949e5d2b925296bb4ee7271798
Status:          Last reconciled at 2026-11-12 17:17:20 +0000 UTC
Message:         Applied revision: main@sha1:3c42d9b575c2de949e5d2b925296bb4ee7271798
---
GitRepository:   flux-system
Namespace:       flux-system
URL:             ssh://[email protected]/<du>/flux-fleet
Branch:          main
...

Vom Objekt über die Kustomization und den Pfad bis zum Repo und Commit. flux tree geht den umgekehrten Weg, von der Kustomization zu ihren Objekten:

flux tree kustomization notes

Erwartet:

Kustomization/flux-system/notes
├── Secret/notes/notes-api
├── Service/notes/notes
└── Deployment/notes/notes

Fortschritt speichern? Kostenlos registrieren

Drill 4: Was ist kaputt?

Der schnellste Überblick über den ganzen Cluster:

flux get all -A --status-selector ready=false

Erwartet: keine Ausgabe. Alles, was hier erscheint, braucht Aufmerksamkeit.

flux stats -A

Erwartet (gekürzt):

RECONCILERS             RUNNING FAILING SUSPENDED   STORAGE
GitRepository           1       0       0           57.6 KiB
OCIRepository           4       0       0           2.9 KiB
...
Kustomization           12      0       0           -
HelmRelease             1       0       0           -
...

Die Logs eines Objekts, ohne dich durch die Logs des ganzen Controllers zu wühlen:

flux logs --kind=Kustomization --name=notes --since=10m | tail -3

Erwartet (gekürzt):

… info Kustomization/notes.flux-system - All dependencies are ready, proceeding with reconciliation
… info Kustomization/notes.flux-system - server-side apply completed
… info Kustomization/notes.flux-system - Reconciliation finished in 1.023620861s, next run in 5m0s

Fortschritt speichern? Kostenlos registrieren

Drill 5: Metriken

Jeder Controller liefert Metriken für Prometheus auf Port 8080. Ohne Prometheus kannst du sie über den API-Server abrufen:

P=$(kubectl -n flux-system get pod -l app=kustomize-controller \
  -o jsonpath='{.items[0].metadata.name}')
kubectl get --raw /api/v1/namespaces/flux-system/pods/$P:8080/proxy/metrics \
  | grep '^gotk_reconcile_duration_seconds_count' | head -3

Erwartet (gekürzt):

gotk_reconcile_duration_seconds_count{kind="Kustomization",name="apps",namespace="team-blau"} 4
gotk_reconcile_duration_seconds_count{kind="Kustomization",name="apps",namespace="team-gruen"} 3
...

gotk_reconcile_duration_seconds zeigt, wie oft und wie lange jedes Objekt abgeglichen wird. Steigt die Dauer, wird ein Repo zu groß oder ein Health-Check hängt.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Upgrade

Ein Flux-Upgrade ist ein Bootstrap mit einer neueren CLI. Du hast schon die neueste, also prüfst du, dass ein Bootstrap nichts kaputt macht, vor allem nicht die Patches aus Tag 12:

flux bootstrap github --owner=$GITHUB_USER --repository=flux-fleet \
  --branch=main --path=clusters/lab --personal --private=true \
  --components-extra=image-reflector-controller,image-automation-controller \
  --read-write-key

Erwartet (gekürzt):

✔ component manifests are up to date
...
✔ source secret up to date
...
✔ sync manifests are up to date
git pull
grep -c 'op: add' clusters/lab/flux-system/kustomization.yaml

Erwartet:

3

Der Bootstrap schreibt nur gotk-components.yaml und gotk-sync.yaml neu. Die kustomization.yaml daneben mit deinen Patches bleibt, wie sie ist.

Für ein echtes Upgrade lädst du die neue Flux-Version wie in Tag 0 herunter, ersetzt ~/.local/bin/flux und führst denselben Befehl aus. Lies vorher die Release Notes. Flux 2.10 hat zum Beispiel die Notification-APIs auf v1 gehoben.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Deinstallation

Was passiert, wenn du Flux entfernst? Ein Probelauf zeigt es:

flux uninstall --dry-run --silent | grep -v 'deleted (dry run)'

Erwartet:

► deleting components in flux-system namespace
► deleting toolkit.fluxcd.io finalizers in all namespaces
► deleting toolkit.fluxcd.io custom resource definitions
✔ uninstall finished

Die Reihenfolge ist entscheidend: Erst entfernt Flux die Finalizer, dann die CRDs. Ohne Finalizer räumt keine Kustomization beim Löschen ihre Objekte ab. notes, Postgres und die Teams laufen also weiter, nur verwaltet sie niemand mehr.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

flux get all -A --status-selector ready=false

Erwartet: keine Ausgabe.

diff ~/flux-lab/fleet/.github/workflows/validate.yaml \
  ~/flux-lab/code/loesung/tag13/.github/workflows/validate.yaml

Erwartet: keine Ausgabe.

Challenge

Ein Kollege pusht einen Tippfehler: replicas: zwei im Deployment von notes-db. Wer merkt es zuerst, die CI oder Flux? Und was sieht man auf GitHub?

Lösung

cd ~/flux-lab/fleet
sed -i 's/replicas: 1/replicas: zwei/' apps/notes-db/base/deployment.yaml
git commit -am "notes-db: zwei Replicas"
git push

Nach etwa 15 Sekunden ist der Lauf validate rot. Im Log des Schritts „Apps und Infrastruktur“:

== apps/notes-db/base
stdin - Deployment notes-db is invalid: problem validating schema. … at '/spec/replicas': got string, want null or integer
##[error]Process completed with exit code 1.

Innerhalb einer Minute meldet auch Flux den Fehler:

flux get kustomization notes-db

Erwartet (gekürzt):

NAME        REVISION            SUSPENDED   READY   MESSAGE
notes-db    main@sha1:9a6e2ef2  False       False   Deployment/notes/notes-db dry-run failed: … .spec.replicas: expected numeric (int or float), got string
  • Die CI war schneller, aber beide haben den Fehler gefunden, und kaputt ging nichts. Flux prüft per Dry-Run und wendet nichts an.
  • Der eigentliche Gewinn kommt mit Pull Requests: Die CI prüft vor dem Merge. Mit Branch-Schutz und der Regel „Status validate muss grün sein“ erreicht ein solcher Commit main gar nicht erst.
git revert --no-edit HEAD
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes-db

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • flux diff im Pull Request: Mit Zugang zu einem Cluster zeigt flux diff kustomization im Pull Request, was sich ändern würde. Dafür braucht die CI Leserechte auf den Cluster. Viele Teams geben ihr ein eigenes kubeconfig mit Nur-Lese-Rechten.
  • Monitoring: Das Flux-Projekt pflegt ein Beispiel (flux2-monitoring-example) mit Prometheus, kube-state-metrics und fertigen Grafana-Dashboards. Daraus kommt die Metrik gotk_resource_info mit dem Zustand jedes Flux-Objekts, die beste Grundlage für Alarme.
  • Flux Operator: Statt flux bootstrap verwaltet der Flux Operator die Installation über ein einziges Objekt FluxInstance, mit automatischen Upgrades innerhalb einer Versionsreihe. Für viele Cluster ist das der einfachere Weg.