Flux Cheatsheet OMNI52™ GmbH

Neu in Flux 2.9image- und notification-v1beta2-APIs entfernt · Helm-Post-Render-Default wechselt auf combined · Server-Side-Apply-Ignore-RegelnAlle Neuerungen →

Flux
auf einem Blatt.

Dichte Referenz für Senior Platform Engineers und SREs zu Flux, dem CNCF-graduated GitOps-Werkzeug für Kubernetes. GitOps-Toolkit, Bootstrap, Kustomization, HelmRelease, Image Automation, Multi-Tenancy, SOPS-Secrets, Diagnose und Anti-Patterns. Keine Einsteiger-Folien.

Vorschau (2 Seiten A4 quer + Brand-Rückseite)

Flux Cheatsheet Seite 1: GitOps-Toolkit, Neu in v2.9, Bootstrap, Sources, Kustomization, HelmRelease

Flux Cheatsheet Seite 2: HelmRelease, Reconciliation, Image Automation, Multi-Tenancy, SOPS, Diagnose, Anti-Patterns

PDF herunterladen

Direkter Download, keine Mail-Adresse nötig. CC BY-SA 4.0: kopieren, drucken, weiterverteilen ist ausdrücklich erlaubt, solange die Quellenangabe sichtbar bleibt.

Flux Cheatsheet (PDF, ~100 KB)

Was drin steht

GitOps-Toolkit

Pull statt Push, Controller-Landschaft (source, kustomize, helm, notification; optional image-* und source-watcher), flux bootstrap als idempotenter Install- und Upgrade-Pfad.

Sources

GitRepository, OCIRepository (inkl. cosign/notation-Verify), HelmRepository (HTTP/S; OCI-Charts per OCIRepository), Bucket (S3, GCS, Azure Blob), ExternalArtifact. ref per branch/tag/semver/commit/digest.

Kustomization

path, prune, dependsOn, wait/healthChecks, retryInterval, serviceAccountName, targetNamespace, postBuild.substituteFrom für cluster-spezifische Werte.

HelmRelease

Chart-Referenz via sourceRef/chartRef, SemVer-Ranges als kontrolliertes Auto-Update, install/upgrade-Remediation, driftDetection, Helm 4 (SSA, kstatus, postRenderStrategy).

Automation & Tenancy

ImageRepository/ImagePolicy/ImageUpdateAutomation mit Setters-Markern. Multi-Tenancy-Lockdown: no-cross-namespace-refs, no-remote-bases, Default-ServiceAccount.

Secrets & Diagnose

SOPS/age-Verschlüsselung im Repo, Decryption im kustomize-controller. flux check/get/trace/events/logs, suspend/resume. Anti-Patterns aus der Praxis.

Cheatsheet im Volltext

Derselbe Inhalt wie im PDF, zum Mitlesen, Durchsuchen und direkten Kopieren der YAML-Snippets. Stand: Flux v2.9.5 (Edition 2026.10).

Architektur & GitOps-Toolkit

Pull statt Push

Flux zieht den deklarierten Zustand aus Git, OCI-Registries oder Buckets und wendet ihn kontinuierlich an. Quelle = Wahrheit: was nicht im Repo steht, gehört nicht in den Cluster. Jede Ressource trägt ihr eigenes interval; Änderungen laufen über Git-Push, nicht über kubectl.

Controller & CRDs

source-controller: GitRepository, OCIRepository, HelmRepository, HelmChart, Bucket. kustomize-controller: Kustomization (inkl. SOPS-Decryption). helm-controller: HelmRelease.

notification-controller: Provider, Alert, Receiver (Webhooks). image-reflector-/image-automation-controller (optional): ImageRepository, ImagePolicy, ImageUpdateAutomation.

source-watcher (optional): ArtifactGenerator (v1beta1), erzeugt ExternalArtifact (source.toolkit.fluxcd.io/v1). Optionale Controller per --components-extra zuschalten.

flux check              # Prereqs + Controller-Status
flux get all -A         # Status aller Flux-Ressourcen
kubectl get fluxcd -A   # alle Flux-CRs (Resource-Kategorie)

Neu in v2.9

Highlights

CLI-Plugin-System (flux plugin): Mirror spiegelt Charts, OCI-Artefakte und Images zwischen Registries, Schema validiert Manifeste gegen JSON-Schema und CEL.

Field-Ignore für Server-Side-Apply (Kustomization.spec.ignore): einzelne Felder aus Drift-Check und Apply ausnehmen, damit HPA, Mesh-Injection u.a. sie besitzen.

Helm Post-Render-Strategien inkl. Chart-Hooks.

SOPS mit Age Post-Quantum-Cipher, Workload-Identity für OpenBao/Vault, Git-Commit-Signing/-Verify per SSH-Key (GitRepository, ImageUpdateAutomation), AWS CodeCommit per Workload Identity, secret-lose OIDC-Receiver.

# Felder fremder Controller aus Drift ausnehmen
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
spec:
  ignore:
    - target: {kind: Deployment}
      paths: ["/spec/replicas"]   # HPA besitzt replicas

Breaking & EOL

Default von postRenderStrategy wechselt von nohooks auf combined: Hook-Manifeste laufen jetzt durch die Post-Renderer. Altes Verhalten per postRenderStrategy: nohooks je HelmRelease.

Entfernt (EOL): image.toolkit.fluxcd.io/v1beta2 und notification.toolkit.fluxcd.io/v1beta2; auf v1 bzw. v1beta3 migrieren: flux migrate (Storage im Cluster, vor dem Upgrade) und flux migrate -f <dir> (Manifeste im Repo, Ziel 2.9 erst ab CLI v2.9.4).

GCR-Receiver brauchen email und audience im Secret (CVE-2026-40109).

Seit v2.9.5: kubeconfig-Secrets aus spec.kubeConfig (Kustomization, HelmRelease) müssen Token und Zertifikate inline tragen, Verweise auf lokale Dateien lehnt der Controller ab.

Stand v2.9.5 (31.08.2026): source-/kustomize-controller v1.9.5, helm-controller v1.6.4 auf Helm 4.2.4. Kubernetes 1.34.1 bis 1.36; 1.37 ist für 2.9 nicht freigegeben.

Bootstrap

flux bootstrap

Installiert source-, kustomize-, helm- und notification-controller nach flux-system (Image Automation per --components-extra), pusht die eigenen Manifeste unter --path ins Repo und synct sich ab dann selbst. Idempotent: erneuter Lauf mit gleichen Argumenten ist der Upgrade-Pfad. Danach läuft jede Änderung am Cluster, inkl. Flux-Upgrades, per Git-Push.

Ohne --token-auth legt bootstrap einen read-only Deploy-Key an (Image Automation braucht --read-write-key=true); mit --token-auth landet der PAT als Secret flux-system im Cluster.

Alternative zu flux bootstrap: Flux Operator (Open Source, Flux-Ökosystem) mit FluxInstance (fluxcd.controlplane.io/v1); .spec.cluster.multitenant: true schaltet den Lockdown.

export GITHUB_TOKEN=<pat>
flux bootstrap github \
  --owner=example-org --repository=fleet \
  --branch=main --path=clusters/prod

Repo-Layout pro Cluster

--path=clusters/<name> gibt jedem Cluster einen eigenen Einstiegspunkt im selben Repo. Infrastruktur (CRDs, Operatoren, Ingress) und Apps als getrennte Kustomizations verketten, dependsOn erzwingt die Reihenfolge.

Sources

GitRepository & OCIRepository

url + interval + ref: Git per branch, tag, semver oder commit; OCI per tag, semver oder digest. Auth via secretRef oder provider: Git azure/aws, OCI aws/azure/gcp per Workload Identity, Git github per GitHub App (App-Key im secretRef). OCIRepository liefert Manifeste als OCI-Artefakt inkl. Signatur-Prüfung (verify: cosign/notation).

HelmRepository & Bucket

HelmRepository: HTTP/S-Index; type: oci ist im Wartungsmodus, OCI-Charts per OCIRepository + chartRef. Bucket: S3-kompatibel, per provider auch GCS und Azure Blob. Jede Source produziert ein versioniertes Artefakt, auf das Kustomization/HelmRelease per sourceRef zeigen.

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata: {name: platform, namespace: flux-system}
spec:
  interval: 1m
  url: https://github.com/example-org/platform
  ref: {branch: main}   # oder tag/semver/commit
  secretRef: {name: git-auth}
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata: {name: manifests, namespace: flux-system}
spec:
  interval: 5m
  url: oci://ghcr.io/example-org/manifests
  ref: {semver: ">=1.0.0 <2.0.0"}

Kustomization

Spec-Kern

path: Verzeichnis im Source-Artefakt. prune: true: Garbage-Collection gelöschter Manifeste. sourceRef: GitRepository, OCIRepository, Bucket oder ExternalArtifact.

retryInterval steuert Fehler-Retries getrennt vom regulären interval; serviceAccountName erzwingt Impersonation (RBAC-Grenze), targetNamespace zwingt alle Objekte in einen Namespace.

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata: {name: apps, namespace: flux-system}
spec:
  interval: 10m
  retryInterval: 2m
  path: ./apps/production
  prune: true            # Garbage Collection
  sourceRef: {kind: GitRepository, name: platform}
  dependsOn:
    - name: infrastructure
  wait: true             # Health aller Objekte
  timeout: 5m
  postBuild:
    substituteFrom:
      - kind: ConfigMap
        name: cluster-vars

Health & Reihenfolge

wait: true prüft die Health aller applizierten Objekte, healthChecks gezielt einzelne (Deployment, HelmRelease, …). dependsOn gated nachgelagerte Kustomizations, bis die Abhängigkeit Ready ist. Standard-Muster: infrastructure vor apps.

postBuild-Substitution

postBuild.substituteFrom ersetzt ${var}-Platzhalter aus ConfigMaps/Secrets, cluster-spezifische Werte (Domain, Zone, Replicas) ohne Overlay-Wildwuchs. optional: true toleriert fehlende Quellen.

HelmRelease

Chart-Referenz

chart.spec + sourceRef auf HelmRepository/GitRepository/Bucket, oder chartRef direkt auf OCIRepository/HelmChart/ExternalArtifact. version nimmt SemVer-Ranges (6.x, >=0.2.0 <1.0.0): Flux wählt automatisch die höchste passende Version, kontrolliertes Auto-Update pro Range.

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata: {name: podinfo, namespace: apps}
spec:
  interval: 30m
  chart:
    spec:
      chart: podinfo
      version: ">=6.0.0 <7.0.0"  # SemVer-Range
      sourceRef:
        kind: HelmRepository
        name: podinfo
        namespace: flux-system
  install: {remediation: {retries: 3}}
  upgrade: {remediation: {retries: 3, strategy: rollback}}
  driftDetection: {mode: enabled}
  valuesFrom: [{kind: Secret, name: podinfo-values}]
  values:
    replicaCount: 2

Remediation & Drift

install.remediation.retries / upgrade.remediation.retries: automatische Wiederholung fehlgeschlagener Releases; strategy: rollback oder uninstall. driftDetection.mode: enabled erkennt und korrigiert manuelle Änderungen am Release-Inventar (warn meldet nur). test.enable führt Helm-Tests nach Install/Upgrade aus.

Helm 4 (seit 2.8)

helm-controller arbeitet mit dem Helm-4-SDK (v2.9.5: 4.2.4). Neue Releases laufen per Server-Side Apply (install.serverSideApply, Default true), bestehende bleiben auf Client-Side Apply, bis upgrade.serverSideApply: enabled (Default auto) sie umstellt. Health-Checks laufen für alle Releases über kstatus (waitStrategy.name: poller); je Release zurück per waitStrategy: {name: legacy} bzw. postRenderStrategy: nohooks, global per Feature-Gate UseHelm3Defaults.

Reconciliation & Betrieb

Intervalle & Trigger

Jede Ressource reconciled periodisch (interval); flux reconcile … --with-source stößt sofort an, inklusive frischem Source-Fetch. Push statt Polling: Receiver (notification-controller) nimmt Webhooks von GitHub/GitLab an; Provider/Alert melden Events an Chat- oder Webhook-Endpunkte.

suspend / resume

flux suspend hält die Reconciliation an (Incident-Freeze, Wartungsfenster), flux resume nimmt sie wieder auf. Suspendierte Objekte driften still, Freeze immer zeitlich begrenzen.

flux reconcile kustomization apps --with-source
flux reconcile source git platform
flux suspend kustomization apps
flux resume kustomization apps
flux get kustomizations --watch

Image Automation

Drei CRDs

ImageRepository scannt Registry-Tags, ImagePolicy wählt den Ziel-Tag (semver.range, alphabetisch/numerisch, filterTags mit Pattern/Extract), ImageUpdateAutomation schreibt den neuen Tag per Commit zurück ins Repo (Strategie: Setters-Marker im Manifest).

apiVersion: image.toolkit.fluxcd.io/v1
kind: ImagePolicy
metadata: {name: podinfo, namespace: flux-system}
spec:
  imageRepositoryRef: {name: podinfo}
  policy:
    semver: {range: 6.x}
# Setters-Marker (gleiche Zeile!) im Ziel-Manifest:
#  tag: 6.9.0 # {"$imagepolicy": "flux-system:podinfo:tag"}

Multi-Tenancy

Lockdown: Flags am Controller

--no-cross-namespace-refs=true auf kustomize-, helm-, notification- und image-Controllern: Tenants können keine Sources außerhalb ihres Namespaces referenzieren. --no-remote-bases=true (kustomize-controller) sperrt Kustomize-Remote-Bases. --default-service-account=default: Kustomizations/HelmReleases ohne serviceAccountName laufen mit dem unprivilegierten Default-Account des Tenant-Namespaces, Rechte kommen ausschließlich per RBAC. Die flux-system-Kustomization bekommt dann serviceAccountName: kustomize-controller, sonst läuft der Bootstrap selbst ohne Rechte.

# clusters/prod/flux-system/kustomization.yaml
patches:
  - patch: |
      - op: add
        path: /spec/template/spec/containers/0/args/-
        value: --no-cross-namespace-refs=true
    target:
      kind: Deployment
      name: "(kustomize|helm|notification|image-.*)-controller"
  - patch: |
      - op: add
        path: /spec/template/spec/containers/0/args/-
        value: --no-remote-bases=true
    target: {kind: Deployment, name: kustomize-controller}
  - patch: |
      - op: add
        path: /spec/template/spec/containers/0/args/-
        value: --default-service-account=default
    target: {kind: Deployment, name: "(kustomize|helm)-controller"}
  - patch: |
      - op: add
        path: /spec/serviceAccountName
        value: kustomize-controller
    target: {kind: Kustomization, name: flux-system}

Secrets: SOPS & age

Verschlüsselt ins Repo

Secrets liegen SOPS-verschlüsselt im Git; der kustomize-controller entschlüsselt beim Apply (decryption.provider: sops). Private Key als Secret sops-age in flux-system (Key-Datei muss auf .agekey enden). Nur data/stringData verschlüsseln, die Manifest-Struktur bleibt diff-bar.

age-keygen -o age.agekey
cat age.agekey | kubectl create secret generic \
  sops-age --namespace=flux-system \
  --from-file=age.agekey=/dev/stdin
sops --age=<public-key> --encrypt \
  --encrypted-regex '^(data|stringData)$' \
  --in-place basic-auth.yaml

# Kustomization-Ausschnitt:
spec:
  decryption:
    provider: sops
    secretRef: {name: sops-age}

Diagnose (flux CLI)

Vom Symptom zur Quelle

flux trace zeigt für ein beliebiges Cluster-Objekt, welche Kustomization/HelmRelease und welche Source es verwaltet, der schnellste Einstieg, wenn unklar ist, woher ein Objekt kommt.

Status & Events

flux get pro Kind oder all, --watch für Live-Status. flux events filtert Kubernetes-Events auf Flux-Ressourcen (--for Kind/name). flux logs aggregiert die Controller-Logs (--level=error).

flux check
flux get all -A
flux trace -n apps deployment my-app
flux events --for Kustomization/apps
flux logs --level=error --all-namespaces

Anti-Patterns

Was du nicht tun solltest

kubectl apply am Repo vorbei: die nächste Reconciliation überschreibt den Hotfix still. Änderungen gehören ins Repo; Notfall-Stopp ist flux suspend.

prune: false als Dauerzustand: gelöschte Manifeste bleiben als Waisen im Cluster stehen: Drift, den niemand mehr sieht.

Eine Mega-Kustomization: CRDs, Operatoren und deren Custom Resources in einem Apply racen gegeneinander. Aufteilen + dependsOn/healthChecks.

Mutable Tags ohne Digest: ImagePolicy wählt per Tag-Sortierung, ein neu gepushtes latest bliebe unbemerkt. Besser unveränderliche SemVer-Tags. Muss es latest sein: filterTags.pattern: '^latest$' + policy.alphabetical, digestReflectionPolicy: Always + interval, Setter-Marker :digest.

Klartext-Secrets im Repo: SOPS/age gehört vor das erste Secret-Commit ins Setup, nicht danach.

Multi-Tenant ohne Lockdown: ohne --no-cross-namespace-refs und Default-ServiceAccount greift jeder Tenant auf fremde Sources zu.

Lizenz & Weiterverteilung

CC BY-SA 4.0. Du darfst dieses Cheatsheet kopieren, weiterverteilen, ausdrucken und in eigenen Materialien zitieren. Bedingung: Quellenangabe „Flux Cheatsheet, OMNI52 GmbH, flux-cheatsheet.de“ bleibt sichtbar, und abgeleitete Werke stehen unter der gleichen Lizenz (Share-Alike).

Nicht erlaubt: Logo, Marken oder den Eindruck zu vermitteln, dass der Inhalt von dir/euch stammt oder dass OMNI52 GmbH die Weiterverwendung sponsort.

Volltext der Lizenz: creativecommons.org/licenses/by-sa/4.0/deed.de.

Flux is a trademark of The Linux Foundation. Kubernetes is a registered trademark of The Linux Foundation. OMNI52™ is a trademark of OMNI52 GmbH (filed, not yet registered). This website is operated by OMNI52 GmbH and is not affiliated with, endorsed by, or sponsored by The Linux Foundation or the Cloud Native Computing Foundation. “Flux” is used in a nominative / descriptive sense to indicate the technology this cheatsheet documents.

Fluxauf einem Blatt.

Vorschau (2 Seiten A4 quer + Brand-Rückseite)

PDF herunterladen

Was drin steht

GitOps-Toolkit

Sources

Kustomization

HelmRelease

Automation & Tenancy

Secrets & Diagnose

Cheatsheet im Volltext

Architektur & GitOps-Toolkit

Pull statt Push

Controller & CRDs

Neu in v2.9

Highlights

Breaking & EOL

Bootstrap

flux bootstrap

Repo-Layout pro Cluster

Sources

GitRepository & OCIRepository

HelmRepository & Bucket

Kustomization

Spec-Kern

Health & Reihenfolge

postBuild-Substitution

HelmRelease

Chart-Referenz

Remediation & Drift

Helm 4 (seit 2.8)

Reconciliation & Betrieb

Intervalle & Trigger

suspend / resume

Image Automation

Drei CRDs

Multi-Tenancy

Lockdown: Flags am Controller

Secrets: SOPS & age

Verschlüsselt ins Repo

Diagnose (flux CLI)

Vom Symptom zur Quelle

Status & Events

Anti-Patterns

Was du nicht tun solltest

Verwandte Cheatsheets

Lizenz & Weiterverteilung

Flux
auf einem Blatt.