added readmes (#1)

Co-authored-by: DerLinkman <derlinkman@gmail.com> Reviewed-on: #1
2026-07-18 19:36:54 +00:00
parent 8d64bf5982
commit cab59c1658
7 changed files with 782 additions and 0 deletions
@@ -0,0 +1,97 @@
+# Rolle `healthcheck`
+
+Post-Update Quality-Gate. Die Rolle prüft nach einem OS-Update, ob alle
+Docker-Container wieder laufen, und protokolliert das Ergebnis im selben
+Update-Log, das auch von der `os-updates`-Rolle verwendet wird.
+
+> Siehe auch das Playbook `playbooks/os-updates-deb.yml` sowie die
+> [Repo-README](../../README.md).
+
+## Voraussetzungen
+
+- Debian-Ziel-Host
+- Optional installiertes Docker (wird automatisch erkannt)
+- Idealerweise vorheriger Lauf der `os-updates`-Rolle (für gemeinsames Log)
+
+## Einbindung
+
+Die Rolle ist fest in `playbooks/os-updates-deb.yml` nach der `os-updates`-
+Rolle eingebunden und wird in der Regel nicht separat aufgerufen:
+
+```yaml
+- hosts: all
+  become: true
+  user: admin
+  roles:
+    - role: os-updates
+    - role: healthcheck
+```
+
+```bash
+ansible-playbook -i inventory/dmc12.yml playbooks/os-updates-deb.yml
+```
+
+## Funktionsweise
+
+`tasks/main.yml` führt nacheinander folgende Schritte aus:
+
+1. **Docker-Binary erkennen** – `which docker` (fehlertolerant)
+2. **Docker-Präsenz festhalten** – Fakt `healthcheck_docker_installed`
+3. **Alle Container auflisten** – `docker ps -a --format {{.Names}}`
+4. **Laufende Container auflisten** – `docker ps --filter status=running`
+5. **Container-Health bewerten** – Differenz aus allen und laufenden
+   Containern ergibt `healthcheck_non_running_containers`
+6. **Gesamtergebnis bestimmen** – `healthcheck_all_running`,
+   `healthcheck_passed`
+7. **Default-Ergebnis ohne Docker** – falls Docker nicht installiert ist,
+   gilt der Healthcheck als bestanden (`passed: true`, 0 Container)
+8. **Log-Verzeichnis sicherstellen** – delegiert an localhost
+9. **Quality-Gate in Update-Log schreiben** – `blockinfile` mit Marker
+   `# {mark} ANSIBLE-HEALTHCHECK`, Abschnitt `quality_gate:`
+10. **Fehlschlagen bei ungesunden Containern** – nur wenn
+    `healthcheck_fail_on_unhealthy` gesetzt ist
+
+## Variablen
+
+| Variable                     | Typ   | Default                                                          | Beschreibung                                  |
+|------------------------------|-------|------------------------------------------------------------------|-----------------------------------------------|
+| `healthcheck_logging_enabled`| bool  | `{{ os_update_logging_enabled \| default(true) }}`               | Logging aktivieren                            |
+| `healthcheck_log_dir`        | string| `{{ os_update_log_dir \| default('/ansible/logs') }}`            | Basis-Verzeichnis für Logs                    |
+| `healthcheck_log_inventory`  | string| `{{ inventory_file \| basename \| splitext \| first }}`          | Inventory-Name (abgeleitet)                   |
+| `healthcheck_log_file`       | string| `<log_dir>/<inventory>/<hostname>/update.log`                   | Pfad zur Update-Log-Datei                    |
+| `healthcheck_fail_on_unhealthy`| bool| `false`                                                          | Playbook fehlschlagen lassen, wenn Container nicht laufen |
+
+Die Variablen leiten sich standardmäßig aus den Werten der `os-updates`-Rolle
+ab, sodass beide Rollen in dasselbe Log schreiben.
+
+## Templates
+
+Keine Templates.
+
+## Handler
+
+Keine Handler.
+
+## Tags
+
+Die Rolle vergibt keine eigenen Tags.
+
+## Abhängigkeiten
+
+- Keine weiteren Rollen.
+- Collections: `ansible.builtin` (Bordmittel).
+- Empfohlener Partner: `os-updates`-Rolle (für gemeinsames Log-Format).
+
+## Hinweise
+
+- Wird Docker nicht gefunden, gilt der Healthcheck als bestanden – nützlich
+  für Hosts, die keine Container betreiben.
+- Das Log wird **delegiert auf localhost** geschrieben (auf dem Ansible-
+  Controller), nicht auf dem Zielhost. Das Verzeichnis `logs/` ist
+  git-ignored.
+- Die `quality_gate`-Sektion im Log ist an denselben Eintrag gekoppelt wie
+  der `os-updates`-Preflight, sodass ein Update-Lauf inkl. Healthcheck
+  nachvollziehbar dokumentiert ist.
+- `healthcheck_fail_on_unhealthy: false` (Default) bricht das Playbook nicht
+  ab – bewusst gewählt, damit nach Updates nicht versehentlich ganze
+  Host-Gruppen blockiert werden. Für kritische Hosts individuell setzen.