Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Bootstrap

Ziel: Flux mit einem einzigen Befehl installieren, das Fleet-Repo anlegen und verstehen, warum Flux sich ab jetzt selbst aus Git verwaltet. · Dauer: ca. 45 min · Voraussetzung: Tag 0

Briefing

  • flux bootstrap github erledigt vier Dinge auf einmal: Es legt das Repo an, schreibt die Flux-Manifeste hinein, installiert Flux im Cluster und verbindet beides über einen Deploy-Key, einen SSH-Schlüssel, der nur für dieses eine Repo gilt.
  • Flux besteht aus Controllern. Jeder kümmert sich um eine Sorte Objekte:
Controller Zuständig für
source-controller Quellen holen: GitRepository, OCIRepository, HelmRepository, Bucket
kustomize-controller Manifeste aus einer Quelle anwenden: Kustomization
helm-controller Helm-Charts installieren: HelmRelease
notification-controller Meldungen schicken und empfangen: Provider, Alert, Receiver
  • Nach dem Bootstrap gibt es genau eine Quelle und eine Kustomization, beide heißen flux-system. Sie zeigen auf clusters/lab im Fleet-Repo, und dort liegen auch die Manifeste von Flux selbst. Flux verwaltet sich also aus Git.
 GitHub: flux-fleet ─────────────────────────────────┐
  └─ clusters/lab/                                   │ jede Minute holen
      └─ flux-system/  (Flux selbst)                 ▼
                                    source-controller: GitRepository flux-system
                                                     │ Artefakt (tar.gz)
                                                     ▼
                                    kustomize-controller: Kustomization flux-system
                                                     │ alle 10 min anwenden
                                                     ▼
                                                  Cluster

Drill 1: Bootstrap

flux bootstrap github --owner=$GITHUB_USER --repository=flux-fleet \
  --branch=main --path=clusters/lab --personal --private=true

Erwartet (gekürzt, Hashes und Schlüssel weichen ab):

► connecting to github.com
✔ repository "https://github.com/<du>/flux-fleet" created
► cloning branch "main" from Git repository "https://github.com/<du>/flux-fleet.git"
✔ cloned repository
► generating component manifests
✔ generated component manifests
✔ committed component manifests to "main" ("05554f17511b194c00d5558b6f1cd8c13eca348d")
► pushing component manifests to "https://github.com/<du>/flux-fleet.git"
► installing components in "flux-system" namespace
✔ installed components
✔ reconciled components
► determining if source secret "flux-system/flux-system" exists
► generating source secret
✔ public key: ecdsa-sha2-nistp384 AAAAE2VjZHNhLXNoYTItbmlzdHAzODQAAAAIbmlz...
✔ configured deploy key "flux-system-main-flux-system-./clusters/lab" for "https://github.com/<du>/flux-fleet"
► applying source secret "flux-system/flux-system"
✔ reconciled source secret
► generating sync manifests
✔ generated sync manifests
✔ committed sync manifests to "main" ("3fb103a568d48a36a87ba45f05dfeada2fefa241")
► pushing sync manifests to "https://github.com/<du>/flux-fleet.git"
► applying sync manifests
✔ reconciled sync configuration
◎ waiting for GitRepository "flux-system/flux-system" to be reconciled
✔ GitRepository reconciled successfully
◎ waiting for Kustomization "flux-system/flux-system" to be reconciled
✔ Kustomization reconciled successfully
► confirming components are healthy
✔ helm-controller: deployment ready
✔ kustomize-controller: deployment ready
✔ notification-controller: deployment ready
✔ source-controller: deployment ready
✔ all components are healthy
  • --personal heißt: Das Repo gehört deinem Benutzer, nicht einer Organisation.
  • --path=clusters/lab ist der Ordner für diesen einen Cluster. Ein zweiter Cluster bekäme clusters/prod im selben Repo.
  • Der Token wird nur für den Bootstrap gebraucht: Repo anlegen, committen, den Deploy-Key hinterlegen. Im Cluster landet er nicht. Flux selbst liest das Repo ab jetzt über den Deploy-Key, und der darf nur lesen.

Wenn der Bootstrap scheitert

  • authorization failed: Write access to repository not granted: Dem Token fehlt Contents: Read and write.
  • GET …/keys: 403 Resource not accessible by personal access token: Dem Token fehlt Administration: Read and write.

Rechte nachtragen (Token → Edit → Update) und denselben Befehl noch einmal ausführen. Der Bootstrap ist wiederholbar: Was schon da ist, lässt er stehen und meldet zum Beispiel component manifests are up to date.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Was im Repo liegt

Du klonst das Fleet-Repo in die VM. Damit git sich bei GitHub anmeldet, ohne den Token in eine Datei zu schreiben, bekommt es einen kleinen Helfer, der die beiden Umgebungsvariablen aus Tag 0 liest:

git config --global user.name "Flux Lab"
git config --global user.email "[email protected]"
git config --global credential.helper \
  '!f() { echo username=$GITHUB_USER; echo password=$GITHUB_TOKEN; }; f'
cd ~/flux-lab
git clone -q https://github.com/$GITHUB_USER/flux-fleet.git fleet
cd fleet
git log --oneline

Erwartet (die Hashes weichen ab):

3fb103a Add Flux sync manifests
05554f1 Add Flux v2.10.0 component manifests
find clusters -type f

Erwartet:

clusters/lab/flux-system/gotk-components.yaml
clusters/lab/flux-system/gotk-sync.yaml
clusters/lab/flux-system/kustomization.yaml
  • gotk-components.yaml (gotk = GitOps Toolkit) enthält alles, was Flux braucht: CRDs, Controller, Rechte. Rund 6.600 Zeilen, erzeugt von flux bootstrap. Du bearbeitest sie nie von Hand.
  • gotk-sync.yaml enthält die beiden Objekte, die Flux mit dem Repo verbinden:
cat clusters/lab/flux-system/gotk-sync.yaml

Erwartet:

# This manifest was generated by flux. DO NOT EDIT.
---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: main
  secretRef:
    name: flux-system
  url: ssh://[email protected]/<du>/flux-fleet
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: flux-system
  namespace: flux-system
spec:
  interval: 10m0s
  path: ./clusters/lab
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
Feld Bedeutung
GitRepository.spec.interval: 1m0s Jede Minute nachsehen, ob main einen neuen Commit hat
secretRef: flux-system Der private Teil des Deploy-Keys liegt in diesem Secret
url: ssh://… Flux liest über SSH, nicht über HTTPS
Kustomization.spec.interval: 10m0s Alle 10 Minuten den Cluster mit Git abgleichen, auch ohne neuen Commit
path: ./clusters/lab Diesen Ordner anwenden, mit allen Unterordnern
prune: true Was aus Git verschwindet, verschwindet auch im Cluster

Neben der Flux-Kustomization gibt es im Ordner auch eine kustomization.yaml. Die Namen sind leicht zu verwechseln:

  • kustomization.yaml ist eine Datei für das Werkzeug Kustomize (Tag 0). Sie zählt auf, welche Dateien zusammengehören.
  • Kustomization (kustomize.toolkit.fluxcd.io) ist ein Objekt im Cluster. Es sagt Flux, welchen Ordner aus welcher Quelle es anwenden soll.

Auf GitHub siehst du den Deploy-Key unter flux-fleet → Settings → Deploy keys, mit dem Hinweis „Read-only“.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Flux ansehen

kubectl -n flux-system get pods

Erwartet (Namen und Alter weichen ab):

NAME                                       READY   STATUS    RESTARTS   AGE
helm-controller-7879bfd657-csxff           1/1     Running   0          3m
kustomize-controller-6cbbc9f58d-9c8nl      1/1     Running   0          3m
notification-controller-7f7c8ccffc-g9fql   1/1     Running   0          3m
source-controller-648554b6c9-4wvvx         1/1     Running   0          3m

flux get zeigt die Flux-Objekte mit ihrem Zustand:

flux get all

Erwartet:

NAME                        REVISION            SUSPENDED   READY   MESSAGE
gitrepository/flux-system   main@sha1:3fb103a5  False       True    stored artifact for revision 'main@sha1:3fb103a5'

NAME                        REVISION            SUSPENDED   READY   MESSAGE
kustomization/flux-system   main@sha1:3fb103a5  False       True    Applied revision: main@sha1:3fb103a5
  • REVISION ist der Commit, den Flux zuletzt geholt bzw. angewendet hat. Stimmen beide Zeilen mit git log überein, ist der Cluster auf dem Stand von Git.
  • stored artifact: Der source-controller hat den Commit als Archiv in seinem Speicher abgelegt. Der kustomize-controller holt es sich dort ab, er spricht nie selbst mit GitHub.
flux check

Erwartet (gekürzt):

► checking version in cluster
✔ distribution: flux-v2.10.0
✔ bootstrapped: true
► checking controllers
✔ helm-controller: deployment ready
► ghcr.io/fluxcd/helm-controller:v1.7.1
...
✔ all checks passed

Fortschritt speichern? Kostenlos registrieren

Drill 4: Flux heilt sich selbst

Flux steht in Git, also stellt Flux sich auch selbst wieder her. Lösche einen Controller:

kubectl -n flux-system delete deploy notification-controller

Erwartet:

deployment.apps "notification-controller" deleted from flux-system namespace

Spätestens nach zehn Minuten wäre er wieder da. So lange musst du nicht warten:

flux reconcile kustomization flux-system --with-source

Erwartet:

► annotating GitRepository flux-system in flux-system namespace
✔ GitRepository annotated
◎ waiting for GitRepository reconciliation
✔ fetched revision main@sha1:3fb103a568d48a36a87ba45f05dfeada2fefa241
► annotating Kustomization flux-system in flux-system namespace
✔ Kustomization annotated
◎ waiting for Kustomization reconciliation
✔ applied revision main@sha1:3fb103a568d48a36a87ba45f05dfeada2fefa241
  • reconcile heißt: jetzt abgleichen, nicht erst beim nächsten Intervall. Die CLI setzt dafür nur eine Annotation am Objekt, den Rest macht der Controller.
  • --with-source holt vorher den neuesten Commit. Ohne die Option wendet Flux den zuletzt geholten Stand noch einmal an.
kubectl -n flux-system get deploy notification-controller

Erwartet:

NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
notification-controller   1/1     1            1           14s

Was Flux getan hat, steht in den Events:

flux events --for Kustomization/flux-system

Erwartet (gekürzt):

14s   Normal  Progressing             Kustomization/flux-system  Deployment/flux-system/notification-controller created
1s    Normal  ReconciliationSucceeded Kustomization/flux-system  Reconciliation finished in 15.641814202s, next run in 10m0s

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

flux get kustomizations

Erwartet: eine Zeile flux-system mit READY True.

git -C ~/flux-lab/fleet log --oneline | wc -l

Erwartet: 2.

kubectl -n flux-system get secret flux-system -o jsonpath='{.data}' | grep -o '"[a-z_.-]*":'

Erwartet:

"identity":
"identity.pub":
"known_hosts":

Das Secret enthält den privaten Schlüssel (identity), den öffentlichen und die Host-Schlüssel von github.com. Die Werte selbst zeigst du nicht an.

Challenge

Wie viele Kubernetes-Objekte hat die Kustomization flux-system angelegt? Finde die Zahl, ohne gotk-components.yaml zu zählen.

Hinweis: Jede Kustomization führt im Status ein Inventar der Objekte, die sie verwaltet.

Lösung

kubectl -n flux-system get kustomization flux-system \
  -o jsonpath='{.status.inventory.entries[*].id}' | wc -w

Erwartet (die Zahl kann je nach Version abweichen):

34

Das Inventar ist der Grund, warum prune funktioniert: Flux weiß genau, was es selbst angelegt hat, und löscht nur das, nie fremde Objekte.

flux tree zeigt dasselbe Inventar als Baum:

flux tree kustomization flux-system | head -5

Erwartet:

Kustomization/flux-system/flux-system
├── CustomResourceDefinition/alerts.notification.toolkit.fluxcd.io
├── CustomResourceDefinition/buckets.source.toolkit.fluxcd.io
├── CustomResourceDefinition/externalartifacts.source.toolkit.fluxcd.io
├── CustomResourceDefinition/gitrepositories.source.toolkit.fluxcd.io

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Deploy-Keys statt Token im Cluster: Ein Deploy-Key gilt nur für ein Repo und darf hier nur lesen. Wird der Cluster kompromittiert, kann der Angreifer nichts ins Repo schreiben. Den Token aus Tag 0 brauchst du danach nur noch für Bootstrap-Läufe.
  • Bootstrap ist wiederholbar: Ein Flux-Upgrade ist derselbe Befehl mit einer neueren
    1. Er schreibt eine neue gotk-components.yaml ins Repo, und Flux zieht sich selbst nach (Tag 13).
  • Ohne Bootstrap: flux install installiert nur die Controller, ohne Repo. Manche Firmen trennen das bewusst und installieren Flux per Helm-Chart oder mit dem Flux Operator, um Flux selbst nicht aus dem Fleet-Repo zu verwalten.