Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 11: Notifications

Ziel: Flux melden lassen, was es tut und was schiefgeht, den Zustand jedes Commits auf GitHub anzeigen und Flux per Webhook sofort abgleichen lassen, statt aufs Intervall zu warten. · Dauer: ca. 75 min · Voraussetzung: Tag 10

Briefing

Der notification-controller arbeitet in zwei Richtungen:

Richtung Objekte Wofür
raus Provider + Alert Ereignisse an Slack, Teams, Webhooks, GitHub … schicken
rein Receiver Webhooks von GitHub, Registries … empfangen und Flux anstoßen
  • Ein Provider ist ein Ziel: Typ (slack, msteams, generic, github …), Adresse, Zugangsdaten.
  • Ein Alert wählt Ereignisse aus (welche Objekte, ab welcher Schwere) und schickt sie an einen Provider. Die Schwere ist info (alles) oder error (nur Fehler).
  • Ein Receiver öffnet eine geheime URL. Kommt dort ein gültiger Webhook an, stößt er einen Abgleich an, etwa der GitRepository nach einem Push.

Im Lab gibt es kein Slack. Stattdessen läuft ein kleiner Echo-Server, der jede Anfrage in sein Log schreibt. Was dort ankommt, käme genauso in Slack an.

 kustomize-controller ─ Ereignis ─► notification-controller ─ Alert ─► Provider echo
 helm-controller                                                   └─► Provider github
                                                                         (Commit-Status)
 curl (statt GitHub) ── POST /hook/… ──► Receiver ── stößt an ──► GitRepository flux-system

Drill 1: Ein Empfänger

cd ~/flux-lab/fleet
mkdir -p infrastructure/echo
cd infrastructure/echo
printf 'apiVersion: v1\nkind: Namespace\nmetadata:\n  name: echo\n' > namespace.yaml
cat > deployment.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo
  namespace: echo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  template:
    metadata:
      labels:
        app: echo
    spec:
      containers:
        - name: echo
          image: mendhak/http-https-echo:39
          ports:
            - containerPort: 8080
EOF
cat > service.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: echo
  namespace: echo
spec:
  selector:
    app: echo
  ports:
    - port: 80
      targetPort: 8080
EOF
cat > kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - namespace.yaml
  - deployment.yaml
  - service.yaml
EOF
cd ~/flux-lab/fleet
flux create kustomization echo --source=GitRepository/flux-system \
  --path=./infrastructure/echo --prune=true --interval=10m --wait=true \
  --export > clusters/lab/echo.yaml
git add -A
git commit -m "Webhook-Empfänger echo"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization echo
kubectl -n echo logs deploy/echo

Erwartet (gekürzt):

...
Listening on ports 8080 for http, and 8443 for https.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Provider und Alert

F=clusters/lab/alerts.yaml
flux create alert-provider echo --type=generic \
  --address=http://echo.echo.svc.cluster.local/ --export > $F
flux create alert notes --provider-ref=echo --event-severity=info \
  --event-source="Kustomization/notes" --event-source="HelmRelease/*.notes-helm" \
  --export >> $F
cat $F

Erwartet:

---
apiVersion: notification.toolkit.fluxcd.io/v1
kind: Provider
metadata:
  name: echo
  namespace: flux-system
spec:
  address: http://echo.echo.svc.cluster.local/
  type: generic
---
apiVersion: notification.toolkit.fluxcd.io/v1
kind: Alert
metadata:
  name: notes
  namespace: flux-system
spec:
  eventSeverity: info
  eventSources:
  - kind: Kustomization
    name: notes
  - kind: HelmRelease
    name: '*'
    namespace: notes-helm
  providerRef:
    name: echo

HelmRelease/*.notes-helm heißt: alle HelmReleases im Namespace notes-helm.

git add -A
git commit -m "Alerts an echo"
git push
flux reconcile kustomization flux-system --with-source
flux get alert-providers
flux get alerts

Erwartet (gekürzt):

NAME    READY   MESSAGE
echo    True    Provider is Ready
NAME    SUSPENDED   READY   MESSAGE
notes   False       True    Alert is Ready

Jetzt passiert etwas. Der Kollege mit dem kubectl scale ist zurück:

kubectl -n notes scale deploy notes --replicas=4
flux reconcile kustomization notes
kubectl -n echo logs deploy/echo | grep -E '^        "(message|severity|reason)"'

Erwartet:

        "severity": "info",
        "message": "Deployment/notes/notes configured",
        "reason": "Progressing",
        "severity": "info",
        "message": "Reconciliation finished in 6.648211995s, next run in 5m0s",
        "reason": "ReconciliationSucceeded",

Der Echo-Server schreibt die ganze Anfrage ins Log. Der grep sucht drei Felder aus dem JSON, das Flux geschickt hat. Die erste Meldung ist die Drift-Korrektur. Genau das möchte man in einem Team-Kanal sehen.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Nur Fehler

Mit info kommt jeder Abgleich an, bei zehn Kustomizations alle paar Minuten. Für einen Kanal, den Menschen lesen, ist error die richtige Schwelle. Zum Testen baust du gleich einen Fehler mit ein:

sed -i 's/  eventSeverity: info/  eventSeverity: error/' clusters/lab/alerts.yaml
sed -i 's/NOTES_REPLICAS: "2"/NOTES_REPLICAS: zwei/' clusters/lab/notes.yaml
git commit -am "Alerts nur bei Fehlern, notes kaputt"
git push
flux reconcile kustomization flux-system --with-source

Ein paar Sekunden später:

kubectl -n echo logs deploy/echo --since=60s | grep -E '^        "(message|severity|reason)"'

Erwartet (gekürzt):

        "severity": "error",
        "message": "Deployment/notes/notes dry-run failed: failed to create typed patch object (notes/notes; apps/v1, Kind=Deployment): .spec.replicas: expected numeric (int or float), got string\n",
        "reason": "ReconciliationFailed",

Reparieren kommt im nächsten Drill, zusammen mit einer neuen Art von Meldung.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Commit-Status auf GitHub

Der Provider github schreibt keinen Text irgendwohin, sondern setzt am Commit auf GitHub einen Status: einen grünen Haken oder ein rotes Kreuz, wie bei einer CI. Dafür braucht er einen Token mit Commit statuses: Read and write. Das Recht hast du in Tag 0 schon gesetzt.

kubectl -n flux-system create secret generic github-status \
  --from-literal=token=$GITHUB_TOKEN
flux create alert-provider github --type=github \
  --address=https://github.com/$GITHUB_USER/flux-fleet \
  --secret-ref=github-status --export >> clusters/lab/alerts.yaml
flux create alert github-status --provider-ref=github --event-severity=info \
  --event-source="Kustomization/*" --export >> clusters/lab/alerts.yaml
sed -i 's/NOTES_REPLICAS: zwei/NOTES_REPLICAS: "2"/' clusters/lab/notes.yaml
git commit -am "notes repariert, Commit-Status auf GitHub"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization notes
  • Der Token kommt per kubectl create secret in den Cluster, nicht über Git. Mit SOPS aus Tag 8 könnte er auch verschlüsselt im Repo liegen.
  • Der Status braucht die info-Ereignisse, denn „erfolgreich“ ist keine Fehlermeldung.

Öffne auf GitHub die Commit-Liste von flux-fleet. Am obersten Commit steht ein grüner Haken. Ein Klick darauf zeigt, welche Kustomizations ihn angewendet haben. Dasselbe liefert die API:

curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/$GITHUB_USER/flux-fleet/commits/$(git rev-parse HEAD)/statuses \
  | grep -E '"(state|context)"'

Erwartet (gekürzt, der Hash im Kontext weicht ab):

    "state": "success",
    "context": "kustomization/notes/39d0a9b7",
    "state": "success",
    "context": "kustomization/flux-system/39d0a9b7",

Für ein Team heißt das: Wer einen Pull Request mergt, sieht am Commit, ob der Cluster ihn übernommen hat. Bei mehreren Clustern zeigt der Kontext auch, welcher es war.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Ein Receiver

Bis Flux einen Push bemerkt, vergeht bis zu einer Minute (interval: 1m). Ein Webhook von GitHub verkürzt das auf Sekunden. GitHub signiert jeden Webhook mit einem gemeinsamen Geheimnis, und der Receiver prüft die Signatur.

Das Geheimnis, ohne Zeilenumbruch am Ende:

cd ~/flux-lab
head -c 24 /dev/urandom | base64 | tr -d '\n' > webhook.token
kubectl -n flux-system create secret generic webhook-token \
  --from-file=token=webhook.token

Ausprobiert: Ohne tr -d '\n' endet die Datei mit einem Zeilenumbruch, und der landet im Secret. Die Signatur, die du gleich mit $(cat webhook.token) berechnest, hat ihn nicht. Der Receiver antwortet dann auf jeden Webhook mit 400, und im Log des notification-controllers steht payload signature check failed.

Der Receiver selbst und ein NodePort, damit du ihn von der VM aus erreichst:

cd fleet
F=clusters/lab/receiver.yaml
cat > $F <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: webhook-receiver-nodeport
  namespace: flux-system
spec:
  type: NodePort
  selector:
    app: notification-controller
  ports:
    - port: 80
      targetPort: http-webhook
      nodePort: 30900
EOF
flux create receiver github-fleet --type=github --event=ping --event=push \
  --secret-ref=webhook-token --resource=GitRepository/flux-system --export >> $F
git add -A
git commit -m "Receiver für GitHub-Webhooks"
git push
flux reconcile kustomization flux-system --with-source
flux get receivers

Erwartet (gekürzt, der Pfad weicht ab):

NAME            SUSPENDED   READY   MESSAGE
github-fleet    False       True    Receiver initialized for path: /hook/0b49313d55e70e12666dc1ef0f2f794caa74ad1e169dcdde61c7bed689e78b6f

Der Pfad ist ein Hash aus Name, Namespace und Token. Wer ihn nicht kennt, kann keine Abgleiche auslösen.

GitHub erreicht deine VM nicht. Du spielst GitHub selbst: eine Push-Nachricht, signiert wie GitHub es tut, mit HMAC-SHA256 über den Inhalt:

P=$(kubectl -n flux-system get receiver github-fleet -o jsonpath='{.status.webhookPath}')
BODY='{"ref":"refs/heads/main"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$(cat ~/flux-lab/webhook.token)" \
  | cut -d' ' -f2)
curl -s -w '%{http_code}\n' -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=$SIG" -d "$BODY" localhost:30900$P

Erwartet:

200
kubectl -n flux-system logs deploy/notification-controller --since=1m \
  | grep receiver-server | tail -2

Erwartet (gekürzt):

{"level":"info",…,"msg":"handling GitHub event: push",…}
{"level":"info",…,"msg":"resource 'GitRepository/flux-system.flux-system' annotated",…}

annotated ist dasselbe, was flux reconcile tut: Der Receiver setzt die Annotation, und der source-controller holt sofort.

Mit falscher Signatur:

curl -s -w '%{http_code}\n' -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=falsch" -d "$BODY" localhost:30900$P

Erwartet:

400

Auf GitHub richtest du das unter flux-fleet → Settings → Webhooks → Add webhook ein: Payload URL https://<öffentliche Adresse>/hook/…, Content type application/json, Secret = Inhalt von webhook.token, Ereignis „Just the push event“. Im Betrieb steht davor ein Ingress mit TLS.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

flux get alerts

Erwartet: notes und github-status, beide READY True.

flux get receivers

Erwartet: github-fleet, READY True.

diff ~/flux-lab/fleet/clusters/lab/receiver.yaml \
  ~/flux-lab/code/loesung/tag11/clusters/lab/receiver.yaml

Erwartet: keine Ausgabe.

Challenge

Das Team will in seinem Kanal sehen, wann fluxcdbot eine neue Version committet, aber weiterhin keine gewöhnlichen Abgleiche. Richte einen Alert ein und löse ein Update aus.

Hinweis: Die ImageUpdateAutomation meldet einen Push als info. Ein eigener Alert mit eigener Schwelle stört den Alert notes nicht.

Lösung

flux create alert image-updates --provider-ref=echo --event-severity=info \
  --event-source="ImageUpdateAutomation/*" --export >> clusters/lab/alerts.yaml
sed -i 's/NOTES_VERSION: 0.7.1/NOTES_VERSION: 0.7.0/' clusters/lab/cluster-vars.yaml
git commit -am "Alert für Image-Updates"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile image update notes
kubectl -n echo logs deploy/echo --since=60s | grep -E '^        "(message|reason)"'

Erwartet (gekürzt):

        "message": "pushed commit '161c323' to branch 'flux/notes-updates'\n0.7.0 -> 0.7.1\n",
        "reason": "Succeeded",

Danach den Pull Request „mergen“ und den Branch löschen, wie in Tag 10:

git fetch -p
git merge --no-edit origin/flux/notes-updates
git push
git push origin --delete flux/notes-updates
flux reconcile kustomization flux-system --with-source

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Alarm-Müdigkeit: Ein Kanal pro Team, nur error, und für Drift ein eigener Alert mit inclusionList oder exclusionList, die Meldungen nach Text filtern. Wer jeden Abgleich sieht, liest bald gar keinen mehr.
  • Monitoring statt Chat: Für Bereitschaftsdienste taugen Metriken besser als Nachrichten. Mit kube-state-metrics und der Konfiguration aus dem Beispiel flux2-monitoring-example entsteht die Metrik gotk_resource_info mit dem ready-Zustand jedes Flux-Objekts (Tag 13), und Alertmanager übernimmt das Eskalieren.
  • Receiver öffentlich machen: Der Receiver ist der einzige Teil von Flux, den man von außen erreichen muss. Er gehört hinter einen Ingress mit TLS und Rate-Limit, und die NetworkPolicy allow-webhooks aus der Flux-Installation lässt Anfragen ohnehin nur zu diesem Port durch.