356 lines
9.4 KiB
Markdown
356 lines
9.4 KiB
Markdown
# Workflow - GitOps / No-Drift Regeln
|
|
|
|
Dieses Dokument definiert den verbindlichen Arbeitsablauf fuer Aenderungen an der Homelab-Infrastruktur.
|
|
|
|
---
|
|
|
|
## Ziel
|
|
|
|
Es darf **keine dauerhafte Abweichung** zwischen:
|
|
|
|
- Gitea Online
|
|
- lokalem Clone
|
|
- Komodo-Stacks
|
|
- laufenden Docker-Containern
|
|
- Host-Konfiguration
|
|
|
|
geben.
|
|
|
|
**Grundsatz:**
|
|
|
|
> Gitea Online ist die operative Quelle der Wahrheit.
|
|
|
|
---
|
|
|
|
## Betriebsmodell
|
|
|
|
Die Rollen sind bewusst getrennt:
|
|
|
|
- **Gitea Online** ist `origin` und damit der verbindliche Sollzustand.
|
|
- Der **lokale Clone** ist die Arbeitskopie fuer Aenderungen.
|
|
- **Komodo** deployed aus Gitea und ist kein Bearbeitungsort.
|
|
- Der **Host** ist Laufzeit, nicht Quelle der Wahrheit.
|
|
|
|
### Operative Hierarchie
|
|
|
|
1. `origin/master` in Gitea
|
|
2. lokaler Clone auf dem Windows-PC
|
|
3. Komodo-Deployments / Webhooks
|
|
4. laufende Container und Host-Dateien
|
|
|
|
Wenn diese Ebenen voneinander abweichen, gewinnt immer zuerst Git und nicht der manuelle Live-Zustand.
|
|
|
|
---
|
|
|
|
## Standard-Workflow
|
|
|
|
Aenderungen werden immer in dieser Reihenfolge durchgefuehrt:
|
|
|
|
1. Lokal synchronisieren
|
|
2. Lokal aendern
|
|
3. Commit erzeugen
|
|
4. Push nach Gitea
|
|
5. Komodo reagiert automatisch per Webhook
|
|
6. Ergebnis testen
|
|
7. Doku pruefen und nachziehen
|
|
|
|
---
|
|
|
|
## Standardwerkzeug fuer den Alltag
|
|
|
|
Der bevorzugte lokale Workflow ist:
|
|
|
|
- **GitHub Desktop** fuer `Fetch`, `Pull`, `Commit`, `Push`
|
|
- Editor nach Wahl fuer Datei-Aenderungen
|
|
- Gitea Web fuer Historie, Review und kleine Notfaelle
|
|
- Komodo nur fuer Deploy-Status, Logs und Stack-Sicht
|
|
|
|
### Tagesablauf mit GitHub Desktop
|
|
|
|
Vor lokaler Arbeit:
|
|
|
|
1. GitHub Desktop oeffnen
|
|
2. `Fetch origin`
|
|
3. wenn noetig `Pull origin`
|
|
|
|
Nach lokaler Arbeit:
|
|
|
|
1. Aenderungen pruefen
|
|
2. Commit mit sauberer Nachricht
|
|
3. `Push origin`
|
|
4. Komodo-Webhook im Hinterkopf behalten
|
|
|
|
---
|
|
|
|
## Wenn online in Gitea gearbeitet wurde
|
|
|
|
Web-Aenderungen in Gitea sind erlaubt, aber nicht der Normalfall.
|
|
|
|
Wenn online etwas geaendert wurde, gilt **vor der naechsten lokalen Arbeit**:
|
|
|
|
1. GitHub Desktop oeffnen
|
|
2. `Fetch origin`
|
|
3. `Pull origin`
|
|
4. erst dann lokal weiterarbeiten
|
|
|
|
Sonst entsteht Drift zwischen Gitea Online und lokalem Clone.
|
|
|
|
---
|
|
|
|
## Komodo-Regeln
|
|
|
|
Komodo ist in diesem Setup:
|
|
|
|
- primaeres Deployment-Werkzeug
|
|
- GitOps-Consumer fuer die Stacks
|
|
- Monitoring- und Status-Werkzeug
|
|
|
|
### Deshalb gilt
|
|
|
|
- Stack-Konfiguration nur im Repository anpassen
|
|
- nicht im Komodo-Web-Editor arbeiten
|
|
- Pushes koennen automatisch einen Komodo-Deploy ausloesen
|
|
- wenn Komodo und Git voneinander abweichen, gewinnt Git
|
|
|
|
### Ausnahme: Komodo-Zugangsmodell
|
|
|
|
Komodo bleibt **bewusst** ohne zentrale Traefik-ForwardAuth-Middleware.
|
|
|
|
Grund:
|
|
|
|
- Komodo hat eigene Authentifizierung
|
|
- Komodo nutzt REST- und WebSocket-Endpunkte
|
|
- Webhooks laufen ueber `/listener/...`
|
|
- Periphery nutzt den speziellen WebSocket-Pfad `/ws/periphery`
|
|
|
|
Deshalb wird Komodo aktuell nur ueber Traefik veroeffentlicht, aber **nicht** pauschal mit `authelia@file` vorgeschaltet.
|
|
|
|
**Regel:** Aenderungen an Komodo-Auth, Komodo-Routing oder vorgeschalteter Middleware nur nach expliziter Wirkungspruefung auf:
|
|
|
|
- UI-Login
|
|
- Gitea-Webhooks
|
|
- Periphery-Verbindung
|
|
- API-/Automationszugriffe
|
|
|
|
---
|
|
|
|
## Verbotene Arbeitsweise
|
|
|
|
Folgende Dinge sind grundsaetzlich zu vermeiden:
|
|
|
|
- Aenderungen direkt im Komodo-Web-Editor
|
|
- Aenderungen direkt per `docker run`
|
|
- Aenderungen an laufenden Containern ohne Repo-Anpassung
|
|
- spontane Host-Hotfixes ohne Nachdokumentation
|
|
- Secrets im Git-Repository
|
|
- mehrere kritische Dienste gleichzeitig migrieren
|
|
|
|
---
|
|
|
|
## Erlaubte Arbeitsweise
|
|
|
|
Erlaubt und gewuenscht sind:
|
|
|
|
- Aenderungen an Compose-Dateien im Git-Repo
|
|
- Commit + Push vor jedem produktiven Deploy
|
|
- GitHub Desktop als Standardweg fuer den lokalen Sync
|
|
- Gitea Web fuer Review, Historie und kleine Hotfixes
|
|
- Host-Hotfixes nur im Ausnahmefall mit sofortiger Nachpflege im Repo
|
|
|
|
---
|
|
|
|
## No-Drift-Prinzip
|
|
|
|
### Definition
|
|
|
|
**Configuration Drift** liegt vor, wenn der reale Zustand vom Git-Zustand abweicht.
|
|
|
|
Beispiele:
|
|
|
|
- laufender Container wurde manuell veraendert
|
|
- lokaler Clone ist nicht mehr auf dem Stand von `origin/master`
|
|
- Komodo-Stack entspricht nicht mehr dem Repo
|
|
- Host-Dateien wurden angepasst, aber nicht dokumentiert
|
|
- Traefik dynamic config wurde lokal geaendert, aber Git weiss nichts davon
|
|
|
|
### Regel
|
|
|
|
Wenn Drift erkannt wird, gilt:
|
|
|
|
1. Drift **nicht ignorieren**
|
|
2. Drift **sofort benennen**
|
|
3. entscheiden:
|
|
- Repo an Realitaet anpassen
|
|
- oder Realitaet an Repo zurueckfuehren
|
|
4. erst danach weiterarbeiten
|
|
|
|
### Pflichtcheck bei Drift-Verdacht
|
|
|
|
Vor jedem Reparaturversuch muessen die Ebenen getrennt geprueft werden:
|
|
|
|
1. lokaler Clone
|
|
2. Gitea `origin/master`
|
|
3. Komodo Stack Workspace
|
|
4. Docker Runtime
|
|
5. Host-Netzwerklistener
|
|
|
|
Das detaillierte Runbook steht in `docs/GITOPS_DRIFT_RUNBOOK.md`.
|
|
|
|
**Regel:** `HostConfig.PortBindings` allein beweist keinen aktiven Host-Port. Entscheidend sind `NetworkSettings.Ports`, `docker ps`, `ss -ltnp` und ein echter `curl` gegen den Host-Port.
|
|
|
|
**Stop-Regel:** Wenn zwei Reparaturversuche nicht zum erwarteten Ergebnis fuehren, keine weiteren Schreibbefehle ausfuehren. Erst die Pflichtmatrix aus dem Runbook ausfuellen.
|
|
|
|
---
|
|
|
|
## Ausnahmefall: Hotfix auf dem Host
|
|
|
|
Manchmal ist ein Live-Hotfix noetig. Das ist erlaubt, aber nur unter diesen Bedingungen:
|
|
|
|
1. Hotfix nur wenn der Dienst sonst nicht funktioniert
|
|
2. Aenderung sofort dokumentieren
|
|
3. Aenderung danach ins Git-Modell ueberfuehren
|
|
4. kein stiller Dauerzustand
|
|
|
|
### Pflicht bei Hotfixes
|
|
|
|
- Was wurde geaendert?
|
|
- Wo wurde es geaendert?
|
|
- Warum war es noetig?
|
|
- Muss diese Aenderung ins Repo uebernommen werden?
|
|
- Ist ein Rollback dokumentiert?
|
|
|
|
---
|
|
|
|
## Ausnahme: Traefik Dynamic Config
|
|
|
|
> **Diese Dateien werden von Komodo nicht automatisch deployed.**
|
|
|
|
Komodo deployed ausschliesslich `docker-compose.yml`-Dateien. Die Traefik-Konfigurationsdateien unter `traefik/dynamic/` im Git-Repo werden **nicht** automatisch auf den Host uebertragen.
|
|
|
|
Diese Ausnahme bleibt bewusst bestehen. Der File-Provider wird weiterhin nur fuer zentrale Middlewares, TLS und Dashboard-Konfiguration genutzt, waehrend Service-Routing ueber Docker-Labels laeuft.
|
|
|
|
### Betroffene Dateien
|
|
|
|
| Git-Pfad | Host-Pfad (NAS) |
|
|
|---|---|
|
|
| `traefik/dynamic/middlewares.yml` | `/mnt/user/appdata/traefik/dynamic/middlewares.yml` |
|
|
| `traefik/dynamic/tls.yml` | `/mnt/user/appdata/traefik/dynamic/tls.yml` |
|
|
| `traefik/dynamic/dashboards.yml` | `/mnt/user/appdata/traefik/dynamic/dashboards.yml` |
|
|
|
|
### Pflicht-Workflow bei Aenderungen an Traefik Dynamic Config
|
|
|
|
1. Datei im Git-Repo (`traefik/dynamic/`) aendern
|
|
2. Commit + Push
|
|
3. Datei manuell auf den Host kopieren
|
|
4. Traefik laedt dynamic config automatisch neu
|
|
5. Aenderung testen
|
|
|
|
> **Merksatz:** Git-Commit allein reicht hier nicht. Ohne den manuellen Kopier-Schritt wirkt die Aenderung nicht.
|
|
|
|
---
|
|
|
|
## Secrets-Regeln
|
|
|
|
- Secrets liegen niemals im Repository
|
|
- Secrets liegen unter `/mnt/user/appdata/secrets/`
|
|
- Secrets werden ueber Datei-Mounts mit `_FILE` Variablen oder Komodo Stack Environment Variables eingebunden
|
|
- Rechte: `chmod 600`
|
|
- Secret-Namen und Pfade werden in `docs/SECRETS_MAP.md` dokumentiert
|
|
|
|
---
|
|
|
|
## Image-Versionierung
|
|
|
|
- Mutable Tags wie `latest`, `stable`, `release` oder reine Major-Tags werden nach Moeglichkeit auf den **aktuell laufenden Digest** gepinnt.
|
|
- Digest-Pinning friert den bekannten Laufzeitstand ein; es ist **kein** automatisches Upgrade.
|
|
- Echte Versions-Upgrades sind ein eigener, bewusster Aenderungsblock mit anschliessendem Test.
|
|
- Wenn der laufende Digest unbekannt ist, wird er zuerst am produktiven Container ausgelesen und erst danach im Repo festgeschrieben.
|
|
|
|
---
|
|
|
|
## DNS-Regeln fuer Container
|
|
|
|
Nicht alle Container koennen externe DNS-Namen aufloesen. Standardmaessig nutzt Docker `127.0.0.11` als internen DNS-Resolver. In bestimmten Netzwerk-Setups schlaegt externe Namensaufloesung damit fehl (`server misbehaving`).
|
|
|
|
### Regel
|
|
|
|
Container die **externe Domains aufloesen muessen** erhalten explizit:
|
|
|
|
```yaml
|
|
dns:
|
|
- 1.1.1.1
|
|
- 8.8.8.8
|
|
```
|
|
|
|
### Aktuell betroffen
|
|
|
|
| Service | Grund |
|
|
|---|---|
|
|
| `traefik` | ACME Let's Encrypt (`acme-v02.api.letsencrypt.org`) |
|
|
| `ddns-updater` | IP-Erkennung (ipify.org) + Cloudflare API |
|
|
|
|
---
|
|
|
|
## Dokumentationspflicht
|
|
|
|
Nach jeder erfolgreichen Migration oder relevanten Aenderung muessen diese Dateien geprueft werden:
|
|
|
|
- `docs/MIGRATION_LOG.md`
|
|
- `docs/SECRETS_MAP.md`
|
|
- `docs/ROLLBACK.md`
|
|
- `HOMELAB_ARCHITECTURE_MASTER_V2.md` falls Architektur betroffen ist
|
|
- `docs/GITOPS_DRIFT_RUNBOOK.md` falls GitOps-/Komodo-/Runtime-Drift betroffen ist
|
|
|
|
---
|
|
|
|
## Sprint-Regel
|
|
|
|
Jede Migration wird als Sprint behandelt. Ein Sprint umfasst immer:
|
|
|
|
1. Ist-Zustand pruefen
|
|
2. Zielzustand definieren
|
|
3. Compose-Datei im Repo anpassen
|
|
4. lokal synchronisieren und aendern
|
|
5. Commit + Push
|
|
6. Deploy ueber Komodo
|
|
7. Test
|
|
8. Doku aktualisieren
|
|
9. Sprint abschliessen
|
|
|
|
> Nie mehrere kritische Dienste gleichzeitig aendern.
|
|
|
|
---
|
|
|
|
## Rollback-Regel
|
|
|
|
Jede Aenderung muss rueckrollbar sein. Vor jedem Deploy muss klar sein:
|
|
|
|
- wie der letzte funktionierende Zustand aussieht
|
|
- welcher Commit der letzte stabile Stand ist
|
|
- ob Datenpfade unveraendert bleiben
|
|
- wie der Dienst im Fehlerfall zurueckgenommen wird
|
|
|
|
Wenn Rollback nicht klar ist, wird nicht deployed.
|
|
|
|
---
|
|
|
|
## Arbeitsregel fuer KI-Assistenten
|
|
|
|
Wenn mit einer KI gearbeitet wird, gilt immer:
|
|
|
|
> Lies zuerst:
|
|
> 1. `HOMELAB_ARCHITECTURE_MASTER_V2.md`
|
|
> 2. `docs/WORKFLOW.md`
|
|
> 3. die betroffene Compose-Datei
|
|
> 4. ggf. `docs/MIGRATION_LOG.md`
|
|
|
|
Erst danach duerfen Aenderungen vorgeschlagen werden.
|
|
|
|
---
|
|
|
|
## Merksatz
|
|
|
|
> Erst syncen, dann aendern.
|
|
> Erst Git, dann Deploy.
|
|
> Kein Drift, kein Chaos.
|