Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 0: Das Trainingsgelände

Ziel: Eine Labor-VM mit k3s, der Flux-CLI und Helm, ein GitHub-Token und notes-api einmal von Hand im Cluster, damit du siehst, welches Problem Flux löst. · Dauer: ca. 45 min · Voraussetzung: ein Konto auf github.com

Briefing

  • GitOps heißt: Der gewünschte Zustand des Clusters steht in einem Git-Repo. Ein Programm im Cluster liest das Repo und gleicht den Cluster laufend daran an. Wer etwas ändern will, ändert Git, nicht den Cluster.
  • Flux ist so ein Programm. Es besteht aus mehreren kleinen Controllern, die im Namespace flux-system laufen. Gesteuert wird es über eigene Kubernetes-Objekte wie GitRepository oder Kustomization.
  • Die Flux-CLI flux installiert Flux, legt diese Objekte an und zeigt ihren Zustand. Nötig ist sie nicht, alles geht auch mit kubectl. Sie spart aber viel Tipparbeit.
  • Das Repo heißt in diesem Buch Fleet-Repo (flux-fleet). Es liegt privat in deinem GitHub-Konto.
 Laptop ──ssh──► VM flux
                  └─ k3s
                      ├─ flux-system: Flux-Controller (ab Tag 1)
                      └─ notes:       notes-api (heute von Hand, ab Tag 2 aus Git)
                         ▲
 github.com/<du>/flux-fleet ── Flux holt ──┘
 curl ─► http://<VM-IP>:30080  notes-api

Drill 1: Die Labor-VM

Auf dem Laptop (Multipass von multipass.run):

multipass launch 24.04 --name flux --cpus 2 --memory 4G --disk 30G
multipass exec flux -- bash -c "echo '$(cat ~/.ssh/id_ed25519.pub)' \
  >> ~/.ssh/authorized_keys"
multipass info flux | grep IPv4
ssh ubuntu@<IP aus der Ausgabe>
  • 4 GB reichen für Flux, notes-api, eine kleine Registry und später kro. Die Flux-Controller zusammen brauchen rund 300 MB.
  • Jede andere Linux-VM mit sudo und Internetzugang tut es auch. Die VM muss github.com erreichen, umgekehrt muss GitHub die VM nicht erreichen.

Ab hier läuft alles in der VM.

Fortschritt speichern? Kostenlos registrieren

Drill 2: k3s

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.37.2+k3s1 \
  sh -s - --disable traefik --disable servicelb

Erwartet (gekürzt):

[INFO]  Using v1.37.2+k3s1 as release
...
[INFO]  systemd: Enabling k3s unit
[INFO]  systemd: Starting k3s
  • get.k3s.io ist das offizielle Installationsskript. Es lädt k3s, legt den Dienst an und verlinkt kubectl.
  • --disable traefik --disable servicelb: Einen Ingress-Controller und einen Load-Balancer brauchst du nicht, alles läuft über NodePorts.

Die Zugangsdaten gehören root. Du machst dir eine Kopie:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown "$(id -u):$(id -g)" ~/.kube/config
chmod 600 ~/.kube/config
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc
export KUBECONFIG=~/.kube/config
kubectl get nodes

Erwartet:

NAME   STATUS   ROLES           AGE   VERSION
flux   Ready    control-plane   20s   v1.37.2+k3s1

KUBECONFIG ist bei k3s Pflicht. Ohne die Variable liest dessen kubectl immer /etc/rancher/k3s/k3s.yaml und scheitert mit permission denied. Die Flux-CLI liest dieselbe Variable.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Flux-CLI und Helm

Beide Programme kommen als fertige Binärdatei von GitHub:

mkdir -p ~/.local/bin ~/flux-lab
cd ~/flux-lab
curl -fsSLO https://github.com/fluxcd/flux2/releases/download/v2.10.0/flux_2.10.0_linux_amd64.tar.gz
tar xzf flux_2.10.0_linux_amd64.tar.gz -C ~/.local/bin flux
rm flux_2.10.0_linux_amd64.tar.gz

Helm brauchst du ab Tag 6, um ein Chart zu verpacken:

curl -fsSLO https://get.helm.sh/helm-v4.3.1-linux-amd64.tar.gz
tar xzf helm-v4.3.1-linux-amd64.tar.gz
mv linux-amd64/helm ~/.local/bin/
rm -r linux-amd64 helm-v4.3.1-linux-amd64.tar.gz

Ubuntu nimmt ~/.local/bin beim Anmelden in den PATH auf, sobald der Ordner existiert. Meldest du dich einmal ab und wieder an, findet die Shell beide Programme:

exit
ssh ubuntu@<VM-IP>
flux version --client

Erwartet:

flux: v2.10.0
helm version --short

Erwartet:

v4.3.1+gc0d08d0

Die Flux-CLI ergänzt Befehle mit der Tab-Taste, wenn du sie einmal einschaltest:

echo 'source <(flux completion bash)' >> ~/.bashrc
source ~/.bashrc

Jetzt prüft flux, ob dein Cluster passt:

flux check --pre

Erwartet:

► checking prerequisites
✔ Kubernetes 1.37.2+k3s1 >=1.35.0-0
✔ prerequisites checks passed

Flux 2.10 unterstützt die drei neuesten Kubernetes-Versionen, also 1.35 bis 1.37.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Der GitHub-Token

Flux legt morgen in deinem Konto ein Repo an und schreibt hinein. Dafür braucht es einen Token. Du legst ihn im Browser an:

  1. github.com → Profilbild → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.
  2. Name flux-lab, Ablauf 30 Tage.
  3. Repository access: All repositories. Das Repo gibt es ja noch nicht.
  4. Permissions → Repository permissions:
    • Administration: Read and write (Repo anlegen, Deploy-Key hinterlegen)
    • Contents: Read and write (Dateien committen)
    • Commit statuses: Read and write (ab Tag 11)
    • Workflows: Read and write (für die CI an Tag 13)
  5. Generate token und den Token kopieren. GitHub zeigt ihn nur einmal.

In der VM legst du ihn in eine Datei, die nur du lesen darfst. read -s zeigt beim Einfügen nichts an, und der Token landet nicht in der Shell-Historie:

read -s T && echo "$T" > ~/.github-token && chmod 600 ~/.github-token

Token einfügen, Enter drücken. Dann gehören dein Benutzername und der Token in Umgebungsvariablen, denn genau dort sucht sie die Flux-CLI. Ersetze <du> durch deinen GitHub-Benutzernamen:

echo 'export GITHUB_USER=<du>' >> ~/.bashrc
echo 'export GITHUB_TOKEN=$(cat ~/.github-token)' >> ~/.bashrc
source ~/.bashrc
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user \
  | grep '"login"'

Erwartet (mit deinem Namen):

  "login": "<du>",

Siehst du stattdessen "message": "Bad credentials", ist der Token falsch kopiert. Fehlt dem Token später ein Recht, merkst du es erst beim Bootstrap. Tag 1 zeigt die Meldungen dazu.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Der Begleitcode

git clone -q https://github.com/thomaszachmann/flux-zum-anfassen.git ~/flux-lab/code
ls ~/flux-lab/code ~/flux-lab/code/loesung

Erwartet:

/home/ubuntu/flux-lab/code:
LICENSE  loesung  README.md  wettkampf

/home/ubuntu/flux-lab/code/loesung:
pruefung  tag03  tag05  tag07  tag09  tag11  tag13
tag02     tag04  tag06  tag08  tag10  tag12  tag14
  • loesung/tagNN enthält den Stand deines Fleet-Repos am Ende jedes Tags. Du schreibst alles selbst und vergleichst am Ende mit diff.
  • wettkampf/ brauchst du erst an Tag 15.

Ein Image musst du nicht bauen. notes-api liegt fertig in der GitHub Container Registry: ghcr.io/thomaszachmann/notes-api, in den Versionen 0.5 bis 0.7.

Fortschritt speichern? Kostenlos registrieren

Drill 6: notes-api von Hand

Bevor Flux ins Spiel kommt, bringst du notes-api so in den Cluster, wie es ohne GitOps üblich ist: Manifeste schreiben, kubectl apply. Die vier Dateien liegen später im Fleet-Repo, heute in ~/flux-lab/notes.

mkdir -p ~/flux-lab/notes
cd ~/flux-lab/notes
cat > namespace.yaml <<'EOF'
apiVersion: v1
kind: Namespace
metadata:
  name: notes
EOF
cat > secret.yaml <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: notes-api
  namespace: notes
stringData:
  apiKey: lab-api-key-123
EOF

Der API-Key steht hier noch im Klartext. Mit einem Secret in einem Git-Repo darf das so nicht bleiben, Tag 8 räumt es auf.

cat > deployment.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notes
  namespace: notes
spec:
  replicas: 1
  selector:
    matchLabels:
      app: notes
  template:
    metadata:
      labels:
        app: notes
    spec:
      containers:
        - name: api
          image: ghcr.io/thomaszachmann/notes-api:0.5.1
          ports:
            - containerPort: 8080
          env:
            - name: NOTES_API_KEY
              valueFrom:
                secretKeyRef:
                  name: notes-api
                  key: apiKey
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
EOF
cat > service.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: notes
  namespace: notes
spec:
  type: NodePort
  selector:
    app: notes
  ports:
    - port: 80
      targetPort: 8080
      nodePort: 30080
EOF

Eine kustomization.yaml zählt die Dateien auf. kubectl versteht sie mit -k, und Flux arbeitet ab morgen genauso:

cat > kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - namespace.yaml
  - secret.yaml
  - deployment.yaml
  - service.yaml
EOF
cd ~/flux-lab
kubectl apply -k notes
kubectl -n notes rollout status deploy/notes

Erwartet:

namespace/notes created
secret/notes-api created
service/notes created
deployment.apps/notes created
Waiting for deployment "notes" rollout to finish: 0 of 1 updated replicas are available...
deployment "notes" successfully rolled out
curl -s localhost:30080/version

Erwartet:

0.5.1

Meldet curl nichts (Exit-Code 7), richtet k3s den NodePort noch ein. Ein paar Sekunden warten und noch einmal.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Die Abweichung

Ein Kollege hat es eilig und zieht notes-api direkt im Cluster auf eine neue Version:

kubectl -n notes set image deploy/notes api=ghcr.io/thomaszachmann/notes-api:0.7.1
kubectl -n notes rollout status deploy/notes
curl -s localhost:30080/version

Erwartet (gekürzt):

deployment.apps/notes image updated
...
deployment "notes" successfully rolled out
0.7.1

Deine Dateien sagen weiter 0.5.1. Der Cluster und die Dateien sind auseinandergelaufen, und niemand merkt es. Sichtbar wird es nur, wenn jemand nachsieht:

kubectl diff -k notes

Erwartet (gekürzt):

-        image: ghcr.io/thomaszachmann/notes-api:0.7.1
+        image: ghcr.io/thomaszachmann/notes-api:0.5.1

Diese Abweichung heißt Drift. Ohne GitOps hängt es an Disziplin, ob sie jemand bemerkt und zurückdreht. Ab Tag 2 erledigt Flux das alle paar Minuten von selbst.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl get nodes

Erwartet: ein Node flux mit STATUS Ready.

flux check --pre

Erwartet: ✔ prerequisites checks passed.

echo "$GITHUB_USER ${#GITHUB_TOKEN}"

Erwartet: dein GitHub-Name und eine Zahl größer null, die Länge des Tokens. Der Token selbst bleibt so unsichtbar.

Challenge

Dreh die Abweichung von Hand zurück und prüfe, dass kubectl diff danach schweigt.

Hinweis: kubectl diff endet mit Exit-Code 0, wenn es nichts zu zeigen gibt, und mit 1, wenn es Unterschiede findet.

Lösung

kubectl apply -k notes
kubectl -n notes rollout status deploy/notes
kubectl diff -k notes; echo "Exit-Code $?"

Erwartet (gekürzt):

deployment.apps/notes configured
...
Exit-Code 0

Den Namespace brauchst du nicht mehr. Morgen legt Flux ihn neu an:

kubectl delete -k notes

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Push oder Pull? Eine CI-Pipeline, die kubectl apply ausführt, braucht Schreibrechte auf den Cluster und läuft nur, wenn jemand pusht. Flux zieht dagegen von innen: Der Cluster braucht nur Lesezugriff aufs Repo, und kein Rechner außerhalb hält Cluster-Zugangsdaten.
  • Token oder GitHub App? Ein persönlicher Token hängt an einer Person. Verlässt sie die Firma, steht Flux still. Im Betrieb nimmst du einen Token eines technischen Kontos oder eine GitHub App, die flux bootstrap github ebenfalls unterstützt.
  • Flux oder Argo CD? Beide setzen GitOps um. Flux kommt ohne eigene Oberfläche aus und wird ganz über Kubernetes-Objekte gesteuert. Argo CD bringt eine Web-UI und ein eigenes Rechtemodell mit.