Flux CD auf Kubernetes installieren: GitOps mit GitLab einrichten

Mit flux bootstrap gitlab installierst du Flux CD auf deinem Kubernetes-Cluster und verbindest es mit einem GitLab-Projekt, aus dem Flux ab dann den Sollzustand des Clusters liest. Eine Beispielanwendung rollst du anschließend nur noch per Git-Commit aus, und Änderungen, die jemand direkt im Cluster vornimmt, setzt Flux beim nächsten Abgleich auf den Stand aus Git zurück. Am Ende entfernst du Flux und das Beispiel wieder vollständig und weißt, was dabei bestehen bleibt.

Die Anleitung nutzt Flux 2.9.6 vom 1. Oktober 2026 für Kubernetes 1.34 bis 1.36 und Flux 2.8.8 für Kubernetes 1.33 (Stand 9. Oktober 2026). Flux liest das GitLab-Projekt über ein nur lesendes Deploy Token. Der Ablauf gilt laut Flux-Dokumentation für gitlab.com und für selbst betriebene GitLab-Instanzen. Dieser Beitrag gehört zur Reihe über CI/CD auf Kubernetes: Wie CI-Jobs als Pods in deinem Cluster laufen, zeigt GitLab Runner auf Kubernetes installieren. Für Argo CD gibt es ein eigenes Tutorial.

Was ist Flux CD?

Flux CD ist ein offenes und erweiterbares Werkzeug für Continuous Delivery auf Kubernetes, das den Sollzustand eines Clusters aus einem Git-Repository liest und mit spezialisierten Controllern dafür sorgt, dass der Cluster diesem Stand entspricht.

Technisch besteht Flux aus dem GitOps Toolkit, einer Sammlung spezialisierter Controller und zusammensetzbarer APIs. Diese APIs sind Kubernetes Custom Resources. Eine GitRepository beschreibt, woher der Sollzustand kommt. Eine Kustomization legt fest, welche Manifeste daraus im Cluster angewendet werden. Eine HelmRelease steuert Helm-Releases. Alle Flux-Ressourcen im Cluster listest du laut Flux-Doku mit kubectl get fluxcd -A auf.

Der Unterschied zu einem Deployment aus der Pipeline liegt in der Richtung. Nicht die Pipeline schreibt mit kubectl apply in den Cluster, sondern Flux holt sich den Sollzustand aus Git. Nach dem Bootstrap lassen sich laut Flux-Doku alle Änderungen am Cluster, auch Upgrades von Flux selbst, per Git-Push erledigen, ohne direkt mit dem Cluster verbunden zu sein.

graph LR
  G["GitLab-Projekt"] -->|"liest per Deploy Token"| S["source-controller mit GitRepository"]
  S -->|"stellt Artefakt bereit"| K["kustomize-controller mit Kustomization"]
  K -->|"wendet Manifeste an und korrigiert Drift"| C["Objekte im Cluster"]

Flux ist ein Projekt der Cloud Native Computing Foundation (CNCF). Es wurde dort am 15. Juli 2019 aufgenommen und hat am 30. November 2022 den Reifegrad Graduated erreicht.

Flux CD oder Argo CD: Was ist der Unterschied?

Flux CD und Argo CD sind beide deklarative GitOps-Werkzeuge für Kubernetes, unterscheiden sich laut ihrer Dokumentation aber im Aufbau, in der Bedienung und in der Installation.

Die Tabelle stellt nur Merkmale gegenüber, die die jeweilige Projektdokumentation selbst nennt (Stand 9. Oktober 2026):

Daraus folgt keine Rangfolge. Argo CD liegt nahe, wenn dein Team Deployments vor allem in der mitgelieferten Weboberfläche verfolgen und synchronisieren will, wie sie die Argo-CD-Doku beschreibt. Flux liegt nahe, wenn ihr per Bootstrap auch Installation und Upgrades des Werkzeugs aus Git steuern wollt und die Arbeit über Kommandozeile und Commits läuft. Beide Wege folgen demselben Prinzip: Git ist die Quelle des Sollzustands.

Voraussetzungen

• Kubernetes-Cluster, zum Beispiel ein Managed-Kubernetes-Cluster von centron, mit einer Version aus der Tabelle unten. Du brauchst laut Flux-Doku Cluster-Admin-Rechte auf dem Ziel-Cluster.
• kubectl mit Zugriff auf den Cluster. Wenn kubectl noch fehlt, hilft kubectl installieren und Kubernetes-Cluster verwalten. Die flux-Befehle nutzen denselben aktuellen Kontext deiner kubeconfig, mit --context wählst du einen anderen.
• Linux oder macOS mit curl (oder wget) und sha256sum (oder shasum). Das Installationsskript der Flux-CLI unterstützt laut Quellcode diese beiden Betriebssysteme auf amd64, arm64 und arm.
• GitLab-Konto auf gitlab.com oder auf einer eigenen GitLab-Instanz. Du musst laut Flux-Doku Owner des Projekts sein oder Admin-Rechte in der GitLab-Gruppe haben. Das Projekt muss noch nicht existieren, Flux legt es beim Bootstrap als privates Projekt an.
• Git auf deinem Rechner, um das Projekt zu klonen und Änderungen zu pushen.
• Ausgehender HTTPS-Zugriff vom Cluster auf deine GitLab-Instanz und auf die Registries der Images. Die Flux-Controller kommen standardmäßig aus ghcr.io/fluxcd, das Beispiel-Image nginx:1.30.5 von Docker Hub.

Passende Flux-Version wählen

Lies zuerst die Kubernetes-Version deines Clusters ab. Maßgeblich ist die Zeile Server Version:

$ kubectl version

Wähle dann die Flux-Version nach den Kompatibilitätstabellen in den Release Notes von Flux 2.9.0 und Flux 2.8.0:

Zwei Grenzfälle: Kubernetes 1.34.0 liegt unter dem Mindestwert beider Reihen (jeweils 1.34.1), hebe den Cluster dann zuerst auf einen neueren Patch. Kubernetes 1.37 steht in keiner der beiden Tabellen (Stand 9. Oktober 2026).

Das Flux-Projekt unterstützt laut seiner Release-Dokumentation die jeweils letzten drei Minor-Versionen von Flux und testet nicht gegen Kubernetes-Versionen, deren Upstream-Unterstützung beendet ist. Kubernetes 1.33 hat laut Kubernetes-Projekt am 28. Juni 2026 das Ende der Upstream-Unterstützung erreicht, Kubernetes 1.34 erreicht es am 27. Oktober 2026. Für solche Versionen sagt das Flux-Projekt nicht zu, dass künftige Flux-Releases noch funktionieren. Der Weg mit 2.8.8 ist deshalb eine Übergangslösung. Plane den Wechsel auf eine gepflegte Minor-Version ein, sobald sie für deinen Cluster verfügbar ist. Alle Befehle in dieser Anleitung sind für 2.9.6 und 2.8.8 gleich, die Flags von flux bootstrap gitlab sind im Quellcode beider Versionen identisch definiert.

GitLab-Token anlegen

Für den Bootstrap braucht die CLI einen Personal Access Token (PAT) mit vollem Lese- und Schreibzugriff auf die GitLab-API. In GitLab entspricht das dem Scope api. So legst du ihn laut GitLab-Dokumentation an (Stand der Doku am 9. Oktober 2026, auf älteren selbst betriebenen Instanzen können Menünamen abweichen):

1. Oben rechts auf deinen Avatar klicken und Edit profile wählen.
2. In der linken Seitenleiste Access > Personal access tokens öffnen.
3. Im Menü Generate token den Eintrag Legacy token wählen.
4. Einen Namen vergeben, zum Beispiel flux-bootstrap, und unter Expiration date ein nahes Ablaufdatum setzen. Ohne eigene Angabe setzt GitLab das Ablaufdatum auf 365 Tage ab heute.
5. Den Scope api auswählen und Generate token klicken. Den Token sofort sicher ablegen, denn GitLab zeigt ihn nach dem Verlassen der Seite nicht mehr an.

Ein kurzes Ablaufdatum begrenzt das Risiko, falls der Token in falsche Hände gerät. Im Cluster legt Flux mit der Option --deploy-token-auth aus dem übernächsten Abschnitt nicht diesen PAT ab, sondern ein eigenes Deploy Token.

Flux-CLI installieren und Cluster prüfen

Die Flux-CLI installierst du in genau der Version, die laut Tabelle zu deinem Cluster passt, und prüfst danach mit flux check --pre, ob der Cluster die Mindestanforderung der CLI erfüllt.

Setze die Version als Variable. Für einen Cluster mit Kubernetes 1.33 trägst du hier 2.8.8 ein:

$ export FLUX_VERSION=2.9.6
$ curl -s https://fluxcd.io/install.sh | bash

Das Installationsskript liest die Variable FLUX_VERSION und lädt dann genau dieses Release statt des neuesten. Es lädt die Prüfsummendatei des Releases mit und bricht ab, wenn die SHA-256-Prüfsumme des heruntergeladenen Archivs nicht passt. In seiner Ausgabe nennt es die verwendete Version in der Zeile mit as release. Die Binary landet in /usr/local/bin/flux. Ist das Verzeichnis für dich nicht beschreibbar, ruft das Skript für diesen einen Schritt selbst sudo auf. Die Flux-Doku zeigt den Aufruf mit sudo bash. Hier läuft bash ohne sudo, weil sudo Umgebungsvariablen je nach Konfiguration nicht weiterreicht.

Öffnest du später eine neue Shell, ist FLUX_VERSION dort nicht mehr gesetzt. Für die übrigen Schritte brauchst du die Variable nicht, für eine erneute Installation setzt du sie neu.

Prüfe jetzt den Cluster:

$ flux check --pre

Die Vorprüfung liest die Kubernetes-Version des Clusters und vergleicht sie mit der Mindestanforderung der CLI. Laut Flux-Doku endet sie bei Erfolg mit prerequisites checks passed.

Wichtig für die Versionswahl: flux check --pre akzeptiert in 2.9.6 wie in 2.8.8 jede Kubernetes-Version ab 1.33.0 (Quellcode check.go beider Versionen). Ein bestandener Check heißt also nicht, dass deine Kubernetes-Version in der Kompatibilitätstabelle der installierten Flux-Version steht. Maßgeblich ist die Tabelle oben.

Mit 2.8.8 meldet flux check zusätzlich eine Zeile mit dem Hinweis new CLI version is available, please upgrade. Laut Quellcode bricht das die Prüfung nicht ab. Bei einem Cluster mit Kubernetes 1.33 bleibst du trotzdem bei 2.8.8. Denselben Hinweis zeigt auch 2.9.6, sobald eine neuere Flux-Version erscheint. Prüfe dann zuerst deren Kompatibilitätstabelle, bevor du aktualisierst.

Flux mit GitLab bootstrappen

Beim Bootstrap installiert die Flux-CLI die Controller im Namespace flux-system, legt deren Manifeste in deinem GitLab-Projekt ab und richtet Flux so ein, dass es sich danach selbst aus diesem Projekt aktualisiert.

Token bereitstellen

Die CLI liest den PAT aus der Umgebungsvariablen GITLAB_TOKEN. Ist sie nicht gesetzt, fragt flux bootstrap gitlab beim Start interaktiv nach dem Token. Das ist der einfachste Weg, damit der Token nicht in der Shell-History landet. Willst du die Variable trotzdem setzen, etwa weil du den Befehl mehrfach ausführst:

$ export GITLAB_TOKEN=<gitlab-pat>

<gitlab-pat> ersetzt du durch den Token aus den Voraussetzungen. Auf diesem Weg steht er im Klartext in deiner Shell-History. Schreib ihn nicht in Skripte und nicht in das Repository, und entferne ihn nach dem Bootstrap mit unset GITLAB_TOKEN aus der Sitzung.

Bootstrap für ein Projekt in deinem Benutzerkonto

$ flux bootstrap gitlab \
  --deploy-token-auth \
  --owner=<gitlab-benutzer> \
  --repository=<projekt> \
  --branch=main \
  --path=clusters/<cluster-name> \
  --personal

Die Platzhalter:

• <gitlab-benutzer>: dein GitLab-Benutzername.
• <projekt>: der Name des GitLab-Projekts, in dem Flux seine Manifeste ablegt. Existiert es noch nicht, legt Flux es privat an.
• <cluster-name>: ein frei gewählter Name für diesen Cluster, zum Beispiel staging. Flux synchronisiert nur diesen Pfad, so kann ein Projekt später mehrere Cluster in eigenen Verzeichnissen enthalten.

Die Flags im Einzelnen, laut CLI-Referenz und Bootstrap-Anleitung für GitLab:

Weitere Standardwerte, die du hier nicht setzen musst: --visibility steht auf private, --hostname auf gitlab.com und --interval, also das Intervall, in dem die GitRepository flux-system das Projekt auf neue Commits prüft, auf eine Minute.

Was der Befehl tut:

1. Er installiert die Controller source-controller, kustomize-controller, helm-controller und notification-controller im Namespace flux-system.
2. Er committet deren Manifeste in den angegebenen Branch, unterhalb von clusters/<cluster-name>/flux-system/.
3. Er erzeugt das Deploy Token und legt es als Secret im Cluster ab.
4. Er richtet eine GitRepository und eine Kustomization mit dem Namen flux-system ein, die den Pfad clusters/<cluster-name> aus dem Projekt abgleichen.

Der Bootstrap ist laut Flux-Doku idempotent. Sind die Controller schon im Cluster, führt ein erneuter Lauf bei Bedarf ein Upgrade durch. Für jeden späteren Lauf von flux bootstrap gitlab brauchst du wieder einen gültigen PAT, denn der Befehl liest ihn bei jedem Start ein.

Warum --deploy-token-auth statt --token-auth: Mit --token-auth schreibt die CLI laut Quellcode (bootstrap_gitlab.go, Tag v2.9.6) den PAT selbst als Passwort in das Secret flux-system. Dann läge ein Token mit vollem API-Zugriff im Cluster. Beide Optionen zusammen lehnt die CLI ab. Das Deploy Token ist laut GitLab-Doku nicht an dein Benutzerkonto gebunden und läuft ohne gesetztes Ablaufdatum nicht ab. Weil es nur lesen darf, funktioniert damit keine Image Automation, die Änderungen zurück nach Git schreibt. Dafür beschreibt die Flux-Doku einen Deploy Key mit Schreibrechten.

Variante: Projekt in einer GitLab-Gruppe

Gehört das Projekt einer Gruppe, lässt du --personal weg und gibst die Gruppe als Owner an. Untergruppen trennst du mit Schrägstrich, also <gitlab-gruppe>/<untergruppe>:

$ flux bootstrap gitlab \
  --deploy-token-auth \
  --owner=<gitlab-gruppe> \
  --repository=<projekt> \
  --branch=main \
  --path=clusters/<cluster-name>

Variante: eigene GitLab-Instanz

Für eine selbst betriebene Instanz ergänzt du --hostname mit dem Hostnamen deiner Instanz, zum Beispiel gitlab.example.com:

$ flux bootstrap gitlab \
  --deploy-token-auth \
  --hostname=<gitlab-host> \
  --owner=<gitlab-gruppe> \
  --repository=<projekt> \
  --branch=main \
  --path=clusters/<cluster-name>

Nutzt deine Instanz ein selbst signiertes Zertifikat, gibst du mit --ca-file=<ca-datei> den Pfad zur CA-Datei an. Die CLI nimmt das Zertifikat dann auch in das Secret flux-system auf.

Für andere Git-Server als GitLab beschreibt die Flux-Installationsdoku eigene Bootstrap-Varianten und ein allgemeines Verfahren für beliebige Git-Server.

Prüfen, ob Flux läuft

Ob der Bootstrap geklappt hat, siehst du an vier Stellen, nämlich an der Installationsprüfung der CLI, am Status von Quelle und Kustomization, an den Pods im Namespace flux-system und an den neuen Dateien im GitLab-Projekt.

$ flux check
$ flux get sources git
$ flux get kustomizations
$ kubectl -n flux-system get pods

Woran du den Erfolg erkennst:

• flux check prüft Kubernetes-Version, Controller und CRDs und endet bei Erfolg mit all checks passed. Für jeden Controller listet es das Container-Image auf. Bei Flux 2.9.6 gehören dazu laut Release Notes source-controller und kustomize-controller in Version v1.9.6 sowie helm-controller in v1.6.5.
• flux get sources git zeigt die GitRepository mit dem Namen flux-system, in der Spalte READY steht True.
• flux get kustomizations zeigt die Kustomization flux-system mit READY auf True und SUSPENDED auf False. Die Spalte MESSAGE nennt die angewendete Revision aus dem Branch main.
• kubectl -n flux-system get pods listet die Pods der vier Controller im Status Running.
• Im GitLab-Projekt liegt das Verzeichnis clusters/<cluster-name>/flux-system/. Laut Flux-Doku enthält es die Dateien gotk-components.yaml, gotk-sync.yaml und kustomization.yaml. Unter Settings > Repository > Deploy tokens siehst du das aktive Deploy Token.

Wie rollt Flux eine Anwendung aus Git aus?

Flux rollt eine Anwendung aus Git aus, indem eine Flux-Kustomization auf ein Verzeichnis im Repository zeigt und der kustomize-controller die dortigen Manifeste im festgelegten Intervall baut, prüft und auf den Cluster anwendet.

Als Beispiel dient ein kleiner Webserver mit dem Namen gitops-demo in einem eigenen Namespace. Die Manifeste liegen unter apps/gitops-demo/, die Flux-Kustomization, die sie anwendet, unter clusters/<cluster-name>/. Das Projekt sieht danach so aus:

apps/
  gitops-demo/
    namespace.yaml
    deployment.yaml
clusters/
  <cluster-name>/
    flux-system/
    gitops-demo.yaml

Klone zuerst das Projekt mit deinem gewohnten Git-Zugang. Für ein Projekt in deinem Benutzerkonto auf gitlab.com:

$ git clone https://gitlab.com/<gitlab-benutzer>/<projekt>.git
$ cd <projekt>
$ mkdir -p apps/gitops-demo

Bei einer Gruppe oder einer eigenen Instanz passt du Host und Pfad in der URL an.

Lege die Datei apps/gitops-demo/namespace.yaml an:

apiVersion: v1
kind: Namespace
metadata:
  name: gitops-demo

Lege die Datei apps/gitops-demo/deployment.yaml an. Sie startet zwei Replikate von nginx:1.30.5:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitops-demo
  namespace: gitops-demo
  labels:
    app.kubernetes.io/name: gitops-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: gitops-demo
  template:
    metadata:
      labels:
        app.kubernetes.io/name: gitops-demo
    spec:
      containers:
        - name: nginx
          image: nginx:1.30.5
          ports:
            - containerPort: 80

Der Namespace steht als eigenes Manifest im selben Verzeichnis. So gehört er zur Kustomization, und Flux entfernt ihn beim Rückbau zusammen mit dem Deployment. Eine kustomization.yaml brauchst du in apps/gitops-demo/ nicht. Fehlt sie, erzeugt der kustomize-controller sie für alle Manifeste im Verzeichnis. Dafür muss jede YAML-Datei dort ein gültiges Kubernetes-Manifest sein.

Lege jetzt die Flux-Kustomization in clusters/<cluster-name>/gitops-demo.yaml an:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: gitops-demo
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: flux-system
  path: ./apps/gitops-demo
  prune: true
  wait: true
  timeout: 2m

Die Felder laut Kustomization-Spezifikation (kustomize-controller v1.9.6):

Ein Feld suspend steht absichtlich nicht in der Datei. Dazu mehr im nächsten Abschnitt.

Warum zwei Ebenen: Die Kustomization flux-system gleicht nur den Pfad clusters/<cluster-name> ab. Sie findet dort die neue Datei gitops-demo.yaml und legt die Kustomization gitops-demo im Cluster an. Diese wendet dann die Manifeste aus apps/gitops-demo/ an.

Committe und pushe die drei Dateien:

$ git add apps/gitops-demo clusters/<cluster-name>/gitops-demo.yaml
$ git commit -m "gitops-demo hinzufügen"
$ git push

Ohne weiteres Zutun übernimmt Flux den Commit, sobald die GitRepository ihn im Intervall von einer Minute abgeholt hat. Um nicht zu warten, stößt du den Abgleich selbst an. --with-source holt dabei zuerst den neuen Stand aus GitLab, und der Befehl wartet, bis der Abgleich fertig ist:

$ flux reconcile kustomization flux-system --with-source
$ flux get kustomizations --watch

Mit --watch verfolgst du den Status laufend, bis du mit Strg+C abbrichst. Sobald die Kustomization gitops-demo in der Spalte READY den Wert True zeigt, prüfst du das Deployment:

$ kubectl -n gitops-demo get deployment gitops-demo

In der Spalte READY steht 2/2.

Änderungen per Git ausrollen und Drift beobachten

Ab jetzt änderst du die Anwendung nur noch über Git, und Flux sorgt dafür, dass der Cluster dem Stand im Repository entspricht, auch wenn jemand direkt mit kubectl eingreift.

Änderung per Commit

Setze in apps/gitops-demo/deployment.yaml den Wert replicas von 2 auf 3, committe und pushe die Änderung und stoße den Abgleich an. --with-source holt auch hier zuerst den neuen Commit aus der Quelle flux-system:

$ git commit -am "gitops-demo: 3 Replikate"
$ git push
$ flux reconcile kustomization gitops-demo --with-source
$ kubectl -n gitops-demo get deployment gitops-demo

Das Deployment zeigt jetzt 3/3.

Drift zurücksetzen lassen

Ändere das Deployment nun direkt im Cluster, an Git vorbei:

$ kubectl -n gitops-demo scale deployment gitops-demo --replicas=1
$ kubectl -n gitops-demo get deployment gitops-demo

Kurz darauf läuft nur noch ein Replikat. Laut Kustomization-Spezifikation setzt Flux Änderungen, die mit kubectl an verwalteten Objekten gemacht wurden, beim nächsten Abgleich auf den Stand aus Git zurück. Das passiert beim nächsten Durchlauf im konfigurierten Intervall von zehn Minuten oder sofort, wenn du den Abgleich selbst anstößt:

$ flux reconcile kustomization gitops-demo
$ kubectl -n gitops-demo get deployment gitops-demo

Das Deployment steht wieder auf drei Replikaten.

Abgleich pausieren und fortsetzen

Manchmal willst du im Cluster bewusst etwas ausprobieren, ohne dass Flux es gleich zurücksetzt. Dafür pausierst du die Kustomization:

$ flux suspend kustomization gitops-demo
$ flux get kustomizations
$ kubectl -n gitops-demo scale deployment gitops-demo --replicas=1

In der Spalte SUSPENDED steht für gitops-demo jetzt True. Solange die Kustomization pausiert ist, wendet Flux weder neue Commits an noch korrigiert es Drift, das eine Replikat bleibt also bestehen. Mit resume hebst du die Pause auf. Der Befehl stößt sofort einen Abgleich an und wartet, bis er fertig ist:

$ flux resume kustomization gitops-demo
$ kubectl -n gitops-demo get deployment gitops-demo

Das Deployment steht wieder auf dem Stand aus Git, also auf drei Replikaten.

Das ist der Grund, warum gitops-demo.yaml kein Feld suspend enthält: Laut Kustomization-Spezifikation würde ein in Git gesetztes suspend: false eine Pause per CLI beim nächsten Abgleich wieder überschreiben, weil der in Git deklarierte Stand gewinnt. Fehlt das Feld, bleibt flux suspend wirksam.

Fehlerbehebung

Die meisten Probleme zeigen sich in drei Befehlen: flux get kustomizations, flux get sources git und flux events. Die folgenden Fehlerbilder stammen aus der Flux-Dokumentation und dem Quellcode der CLI.

flux check --pre lehnt die Kubernetes-Version ab

Meldet die Vorprüfung Kubernetes version … does not match >=1.33.0-0, ist der Cluster älter als 1.33. Diese Anleitung deckt solche Cluster nicht ab. Hebe den Cluster zuerst auf eine Minor-Version aus der Tabelle in den Voraussetzungen.

Bootstrap bricht mit einem Token- oder Rechtefehler ab

Prüfe der Reihe nach:

• Scope: Der PAT braucht vollen Lese- und Schreibzugriff auf die API, also den Scope api. Ein Token, der nur read_api oder read_repository hat, deckt das nicht ab.
• Ablaufdatum: Abgelaufene Tokens lassen sich laut GitLab-Doku nicht reaktivieren. Lege einen neuen an.
• Rechte: Du musst Owner des Projekts sein oder Admin-Rechte in der Gruppe haben.
• --personal: Liegt das Projekt in deinem Benutzerkonto, gehört das Flag dazu. Liegt es in einer Gruppe, muss es fehlen. Ohne --personal sucht die CLI den Owner als Gruppe.
• Projektname: Meldet die CLI is an invalid project name for gitlab, enthält der Name unzulässige Zeichen. Erlaubt sind laut Fehlermeldung Buchstaben, Ziffern, Emojis, _, ., Bindestrich und Leerzeichen. Am Anfang muss ein Buchstabe, eine Ziffer, ein Emoji oder _ stehen.
• Beide Auth-Optionen gesetzt: --token-auth und --deploy-token-auth schließen sich aus.

Kustomization wird nicht bereit

Zeigt flux get kustomizations für gitops-demo in READY den Wert False, liefern die Events den Grund:

$ flux events --for Kustomization/gitops-demo
$ kubectl -n flux-system describe kustomization gitops-demo

flux events zeigt die Events der Kustomization im Namespace flux-system und die ihrer Quelle. Häufige Ursachen laut Kustomization-Spezifikation:

• Pfad falsch: Die Meldung enthält kustomization path not found. Prüfe path in gitops-demo.yaml gegen das Verzeichnis im Repository, einschließlich Groß- und Kleinschreibung.
• Build schlägt fehl: Eine Datei unter apps/gitops-demo/ ist kein gültiges Kubernetes-Manifest, etwa wegen eines Einrückungsfehlers.
• Bereitschaftsprüfung schlägt fehl: Mit wait: true wartet Flux, bis das Deployment ausgerollt ist. Kann der Cluster das Image nicht laden, etwa weil der ausgehende Zugriff auf Docker Hub fehlt, endet die Prüfung nach dem timeout mit einem Fehler. Die Ursache zeigt kubectl -n gitops-demo get pods.
• Namespace fehlt: Setzt du statt metadata.namespace das Feld targetNamespace in der Kustomization, muss der Namespace vorher existieren oder als Manifest in derselben Kustomization stehen. Der kustomize-controller legt ihn nicht selbst an.

Nach einem Fehler versucht Flux den Abgleich laut Spezifikation weiter, mit wachsenden Abständen, bis er gelingt. Nach einer Korrektur in Git stößt du ihn mit flux reconcile kustomization gitops-demo --with-source sofort an.

Die Quelle flux-system ist nicht bereit

Zeigt flux get sources git für flux-system in READY den Wert False, kann Flux das Projekt nicht lesen. Prüfe, ob der Cluster deine GitLab-Instanz per HTTPS erreicht, und ob das Deploy Token unter Settings > Repository > Deploy tokens noch aktiv ist. Details liefert flux events --for GitRepository/flux-system.

Flux und Beispiel entfernen

Entferne zuerst die Beispielanwendung über Git und erst danach Flux selbst, denn flux uninstall lässt Objekte, die Flux angewendet hat, im Cluster stehen.

Beispielanwendung über Git entfernen

Lösche die Manifeste und die Kustomization aus dem Repository:

$ git rm -r apps/gitops-demo clusters/<cluster-name>/gitops-demo.yaml
$ git commit -m "gitops-demo entfernen"
$ git push
$ flux reconcile kustomization flux-system --with-source

Weil die Datei gitops-demo.yaml aus dem abgeglichenen Pfad verschwunden ist, löscht Flux die Kustomization gitops-demo. Da sie mit prune: true arbeitet, entfernt Flux dabei alle Objekte, die sie angewendet hat, also Deployment und Namespace. Das geschieht im Hintergrund und kann einen Moment dauern. Prüfe das Ergebnis:

$ flux get kustomizations
$ kubectl get namespace gitops-demo

Die Kustomization gitops-demo taucht nicht mehr auf, und kubectl meldet, dass der Namespace nicht gefunden wurde.

Flux deinstallieren

Mit --dry-run siehst du zuerst, welche Objekte gelöscht würden. Danach deinstallierst du Flux:

$ flux uninstall --dry-run
$ flux uninstall
$ kubectl get namespace flux-system

Ohne --silent fragt der Befehl vorher nach einer Bestätigung. Der letzte Befehl prüft das Ergebnis: kubectl meldet, dass der Namespace flux-system nicht gefunden wurde. Steht er noch auf Terminating, warte einen Moment und wiederhole den Befehl.

flux uninstall löscht laut Flux-Doku die Controller und ihre Services, die Network Policies von Flux, die RBAC-Objekte, die Finalizer der Flux-Ressourcen, die CRDs mit allen Custom Resources und den Namespace flux-system. Deinstalliere Flux nicht, indem du Deployments und Namespace mit kubectl löschst. Das unterstützt das Flux-Projekt nicht.

Zugänge in GitLab widerrufen

1. Deploy Token: Im Projekt unter Settings > Repository > Deploy tokens im Bereich Active Deploy Tokens neben dem Token Revoke wählen. Dafür brauchst du die Rolle Maintainer oder Owner im Projekt.
2. PAT: Avatar > Edit profile > Access > Personal access tokens, neben dem Token über das Drei-Punkte-Menü Revoke wählen und bestätigen. Ein widerrufener Token ist laut GitLab-Doku sofort ungültig.

Was bestehen bleibt

• Das GitLab-Projekt mit dem Verzeichnis clusters/<cluster-name>/flux-system/ und der gesamten Commit-Historie. Lösche es in GitLab, wenn du es nicht mehr brauchst, oder behalte es für einen späteren Bootstrap.
• Objekte im Cluster, die Flux angewendet hat und die du nicht vorher über Git entfernt hast. flux uninstall lässt sie unverändert stehen.
• Die Flux-CLI unter /usr/local/bin/flux und dein lokaler Klon des Projekts. Die CLI entfernst du bei Bedarf mit sudo rm /usr/local/bin/flux.
• Die Tokens, solange du sie nicht wie oben widerrufen hast. Der PAT läuft zu seinem Ablaufdatum ab, ein Deploy Token ohne gesetztes Ablaufdatum nicht.

Nächste Schritte

• Images aus der Pipeline: Damit neue Versionen deiner Anwendung entstehen, baut eine CI-Pipeline die Images. Die Grundlage dafür beschreibt GitLab Runner auf Kubernetes installieren. Den neuen Image-Tag trägst du dann per Commit in die deployment.yaml ein, und Flux rollt ihn aus.
• Secrets: Zugangsdaten gehören laut Kustomization-Spezifikation weder im Klartext noch base64-kodiert in ein Git-Repository. Flux entschlüsselt dafür Secrets, die mit SOPS verschlüsselt sind. Wie Secrets im Cluster grundsätzlich funktionieren, zeigt Kubernetes Secrets erstellen und verwenden.
• Alternative: Wenn dein Team eine mitgelieferte Weboberfläche für Deployments bevorzugt, sieh dir Argo CD auf Kubernetes installieren und absichern an.
• Grundlagen: Begriffe wie Namespace, Deployment und Controller erklärt der Glossareintrag Kubernetes.

Flux kann darüber hinaus Helm-Charts über HelmRelease ausrollen, Benachrichtigungen verschicken und mit Image Automation neue Image-Tags selbst nach Git schreiben. Für Letzteres braucht Flux Schreibzugriff auf das Repository, das nur lesende Deploy Token aus dieser Anleitung reicht dafür nicht.