sorb/axion1337.chat-gitops

Fork 0

Table of Contents

🔄 GitOps ConfigMap Auto-Sync via Checksums

📋 Das Problem: Flux erkennt ConfigMap-Änderungen nicht

Die Situation
Das Kernproblem

🔑 Die Lösung: Checksums als Trigger

Automatisierung via Git Pre-Commit Hook

🚀 Installation
📝 Workflow: ConfigMaps ändern

1️⃣ Änderung machen
2️⃣ Committen (Hook läuft automatisch)
3️⃣ Überprüfung (optional)
4️⃣ Pushen & Deployen

🔧 Technische Details

Welche Dateien sind "überwacht"?
Hook-Implementation

⚠️ Häufige Fragen

F: Was passiert, wenn der Hook fehlschlägt?
F: Kann ich den Hook deaktivieren?
F: Der Hook touched kustomization.yaml, obwohl ich sie nicht editiert habe?
F: Was wenn ich mehrere ConfigMaps gleichzeitig ändere?

🧪 Verifikation: Hook funktioniert?
📚 Zusammenhang mit Flux CD
🚨 Notfall: Manuelle Checksum-Aktualisierung

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

🔄 GitOps ConfigMap Auto-Sync via Checksums

Dieses Dokument erklärt ein Kernproblem mit Flux CD und externe Konfigurationen – und wie wir es gelöst haben.

📋 Das Problem: Flux erkennt ConfigMap-Änderungen nicht

Die Situation

Unsere HelmRelease (element-server-suite.yaml) nutzt valuesFrom, um Konfigurationen aus externen ConfigMaps zu laden:

spec:
  valuesFrom:
    - kind: ConfigMap
      name: ess-element-custom     # ← Diese ConfigMap
      valuesKey: values.yaml
    - kind: ConfigMap
      name: ess-synapse-custom     # ← Diese ConfigMap
      valuesKey: values.yaml

Diese ConfigMaps entstehen aus Dateien im Git-Repo (apps/production/custom-configs/*.yaml) und werden von Kustomize in den Cluster deployed.

Das Kernproblem

Flux CD reagiert NICHT automatisch, wenn sich eine ConfigMap ändert.

Warum? Flux überwacht nur das Git-Repository auf Änderungen. Wenn du element-values.yaml änderst:

✅ Flux sieht die Änderung im Git-Repo
✅ Kustomize erzeugt eine neue ConfigMap mit den neuen Werten
❌ Aber Helm (der Helm-Controller in Flux) erkennt nicht, dass sich die externe ConfigMap geändert hat
❌ Helm deployt das Chart nicht neu → Die alten Themes/Configs bleiben aktiv

Das ist kein Bug, sondern by-design: Helm achtet nur auf:

Chart-Version (z.B. 26.4.0)
Änderungen in den direkten values: Blöcken
Nicht auf externe Quellen wie ConfigMaps

🔑 Die Lösung: Checksums als Trigger

Wir nutzen Annotations mit Checksums als Workaround:

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  annotations:
    element-config-checksum: "401f8a87d0ef5d91d2e5032d4aede42c"  # ← Hash der element-values.yaml
    synapse-config-checksum: "e98fe81141f52e7ea833596ca39853b9"  # ← Hash der synapse-values.yaml

Wenn sich der Annotation-Wert ändert, sieht Flux, dass die HelmRelease selbst sich geändert hat – und deployt neu.

Automatisierung via Git Pre-Commit Hook

Das Problem: Wer aktualisiert die Checksums, wenn man element-values.yaml editiert?

Lösung: Ein Git pre-commit Hook tut das automatisch:

$ vi apps/production/custom-configs/element-values.yaml
# (Farbe ändern, Theme hinzufügen, …)

$ git add apps/production/custom-configs/element-values.yaml
$ git commit -m "feat: new theme"
# ← Der Hook läuft jetzt:
#   1. Berechnet MD5-Hash der neuen element-values.yaml
#   2. Aktualisiert die Annotation in kustomization.yaml
#   3. Added kustomization.yaml zum Commit automatisch

Der User muss nichts Zusätzliches tun – alles läuft automatisch.

🚀 Installation

Nach dem Repository klonen, führe dieses Skript aus:

cd prod/gitops
./scripts/install-hooks.sh

Das Skript:

✅ Erstellt einen Symlink .git/hooks/pre-commit → scripts/hooks/pre-commit
✅ Macht die Hook-Datei ausführbar
✅ Gibt dir eine Bestätigungsmeldung

Einmalig pro lokales Repository. Neue Klone müssen den Hook auch installieren.

📝 Workflow: ConfigMaps ändern

So sieht die Praxis aus:

1️⃣ Änderung machen

vi apps/production/custom-configs/element-values.yaml
# Edit: Themes, Farben, Logging-Level, etc.

2️⃣ Committen (Hook läuft automatisch)

git add apps/production/custom-configs/element-values.yaml
git commit -m "feat: add Dark Purple theme variant"

# Pre-Commit Hook läuft automatisch:
# → Berechnet neuen Hash
# → Updated kustomization.yaml
# → Added kustomization.yaml zum Commit

3️⃣ Überprüfung (optional)

# Schaue, was committet wird:
git show --stat

# Output sollte zeigen:
#   element-values.yaml (modified)
#   kustomization.yaml (modified) ← vom Hook hinzugefügt

4️⃣ Pushen & Deployen

git push
# ← Flux sieht die Änderung an kustomization.yaml
# ← HelmRelease wird neu-synced mit den neuen Checksums
# ← Die neue Config ist in ~5 Minuten aktiv

🔧 Technische Details

Welche Dateien sind "überwacht"?

Der Hook beobachtet:

Datei	Annotation	Ziel
`apps/production/custom-configs/element-values.yaml`	`element-config-checksum`	Element Web Themes, Branding
`apps/production/custom-configs/synapse-values.yaml`	`synapse-config-checksum`	Synapse Logging, Federation

Hook-Implementation

Der Hook (scripts/hooks/pre-commit) macht folgendes:

Prüft, ob eine der überwachten Dateien geändert wurde (git diff --cached)
Berechnet den MD5-Hash der Datei (kompatibel mit macOS/Linux)
Ersetzt den Hash-Wert in apps/production/kustomization.yaml via sed
Added kustomization.yaml automatisch zum Commit mit git add

# Beispiel: element-values.yaml ändert sich von
value: "401f8a87d0ef5d91d2e5032d4aede42c" # element-config
# zu
value: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" # element-config

⚠️ Häufige Fragen

F: Was passiert, wenn der Hook fehlschlägt?

A: Der Commit wird abgebrochen. Du siehst eine Fehlermeldung. Typische Gründe:

md5 oder md5sum nicht installiert (sehr unwahrscheinlich)
sed Syntax-Fehler (sehr selten)

Lass dich nicht entmutigen – rufe denen auf, die das Setup machen 🚀

F: Kann ich den Hook deaktivieren?

A: Ja, aber bitte nicht! Wenn du temporär ohne Hook arbeiten möchtest:

git commit --no-verify

Das umgeht den Hook einmalig. Danach musst du die Checksums manuell aktualisieren.

F: Der Hook touched `kustomization.yaml`, obwohl ich sie nicht editiert habe?

A: Das ist Absicht. Der Hook updated nur die Checksums, nicht den Rest der Datei. Das ist sauber und Git-freundlich.

F: Was wenn ich mehrere ConfigMaps gleichzeitig ändere?

A: Der Hook aktualisiert alle deren Checksums in einem Pass. Keine Probleme.

🧪 Verifikation: Hook funktioniert?

Teste es selbst:

# 1. Hook installieren
./scripts/install-hooks.sh

# 2. Eine Teständerung machen
echo "# Test" >> apps/production/custom-configs/element-values.yaml

# 3. Committen
git add apps/production/custom-configs/element-values.yaml
git commit -m "test: verify hook"

# 4. Überprüfung: Wurde kustomization.yaml auto-updated?
git diff HEAD~1 apps/production/kustomization.yaml | grep -i checksum

# Output sollte zeigen, dass ein Checksum sich geändert hat

Wenn ja → Hook funktioniert! ✅
Wenn nein → Rufe uns an 📞

📚 Zusammenhang mit Flux CD

┌─────────────────────────────────────────────────────────────┐
│ Git Repository (axion1337.chat-gitops)                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  apps/production/custom-configs/                            │
│  ├── element-values.yaml (du änderst das)                   │
│  ├── synapse-values.yaml                                    │
│  └── mas-secret.yaml                                        │
│                                                              │
│  apps/production/                                           │
│  └── kustomization.yaml (Hook updated die Checksums hier)   │
│                                                              │
│  apps/production/                                           │
│  └── element-server-suite.yaml (HelmRelease mit Annotations)│
│                                                              │
└─────────────────────────────────────────────────────────────┘
                            ↓ git push
┌─────────────────────────────────────────────────────────────┐
│ FluxCD im Kubernetes-Cluster                                │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│ 1. GitRepository Source                                     │
│    └─ Fetcht dein Repo alle 10 Minuten                      │
│                                                              │
│ 2. Kustomization production-apps                            │
│    └─ Applyt die Kustomize-Overlays                         │
│    └─ Erzeugt ConfigMaps mit neuen Werten                   │
│                                                              │
│ 3. HelmRelease matrix-stack                                 │
│    └─ Sieht neue Annotations (Checksums)                    │
│    └─ Deployt Helm-Chart mit neuen Werten                   │
│                                                              │
│ 4. Element Web Pods                                         │
│    └─ Restarten automatisch                                 │
│    └─ Laden neue Config aus der ConfigMap                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

🚨 Notfall: Manuelle Checksum-Aktualisierung

Falls der Hook ausfällt (z.B. weil Git Hooks in CI deaktiviert sind), kannst du Checksums manuell aktualisieren:

# 1. Neuen Hash berechnen
md5sum apps/production/custom-configs/element-values.yaml
# Output: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6  apps/production/custom-configs/element-values.yaml

# 2. Annotation in kustomization.yaml updaten
vi apps/production/kustomization.yaml
# Ändere: value: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" # element-config

# 3. Committen
git add apps/production/kustomization.yaml
git commit -m "fix: manual checksum update"
git push

Version: 1.0
Letztes Update: 2026-05-14
Kompatibilität: FluxCD 2.x, Kustomize 5.x+