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) odererror(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/echoErwartet (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 $FErwartet:
---
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 alertsErwartet (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-sourceEin 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 secretin 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.tokenAusprobiert: 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 mit400, und im Log des notification-controllers stehtpayload 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 receiversErwartet (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$PErwartet:
200
kubectl -n flux-system logs deploy/notification-controller --since=1m \
| grep receiver-server | tail -2Erwartet (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$PErwartet:
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 alertsErwartet: notes und github-status, beide
READY True.
flux get receiversErwartet: github-fleet, READY
True.
diff ~/flux-lab/fleet/clusters/lab/receiver.yaml \
~/flux-lab/code/loesung/tag11/clusters/lab/receiver.yamlErwartet: 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-sourceFortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Alarm-Müdigkeit: Ein Kanal pro Team, nur
error, und für Drift ein eigener Alert mitinclusionListoderexclusionList, 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-exampleentsteht die Metrikgotk_resource_infomit demready-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-webhooksaus der Flux-Installation lässt Anfragen ohnehin nur zu diesem Port durch.