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,128 @@
+# Rolle `os-updates`
+
+Aktualisiert alle installierten Pakete auf Debian-Hosts, optional mit
+Spiegel-Wechsel (Mirror-Switch) und Codename-Anpassung. Die Rolle führt bei
+Bedarf einen Reboot durch (nur bei neuem Kernel, nicht in LXC-Containern)
+und schreibt ein detailliertes Update-Log auf den Ansible-Controller.
+
+> Siehe auch das Playbook `playbooks/os-updates-deb.yml` (in dem direkt im
+> Anschluss die `healthcheck`-Rolle läuft) sowie die
+> [Repo-README](../../README.md).
+
+## Voraussetzungen
+
+- Debian-Ziel-Host
+- Benutzer mit `become`-Rechten
+- Schreibrecht auf dem Controller für das Log (delegiert nach localhost)
+
+## Einbindung
+
+```yaml
+- hosts: all
+  become: true
+  user: admin
+  roles:
+    - role: os-updates
+```
+
+```bash
+ansible-playbook -i inventory/dmc12.yml playbooks/os-updates-deb.yml
+```
+
+## Funktionsweise
+
+`tasks/main.yml` steuert den Ablauf:
+
+1. **`update_mirrors.yml`** (nur wenn `os_also_update_mirror`):
+   - Führt ggf. ein vorangestelltes `apt upgrade dist` durch, falls der
+     Codename des Hosts nicht dem Ziel-Codename entspricht.
+   - Sichert `/etc/apt/sources.list` (Debian <= 12).
+   - Entfernt `/etc/apt/sources.list` ab Debian 13 (Umstieg auf deb822).
+   - Schreibt das Template `sources.list-deb822.j2` nach
+     `/etc/apt/sources.list.d/debian.sources` (Debian >= 13) bzw.
+     `sources.list.j2` nach `/etc/apt/sources.list` (Debian < 13).
+   - Erkennt `.list`- und `.sources`-Fragmente in
+     `/etc/apt/sources.list.d` und ersetzt Codenames (z. B. `bookworm` →
+     `trixie`) per `replace`, sofern sie in `os_update_debian_codenames`
+     gelistet sind.
+   - Aktualisiert den apt-Cache, wenn sich Quellen geändert haben.
+2. **`upgrade_packages.yml`**:
+   - `logging_preflight.yml` – ermittelt Anzahl und Liste der upgradbaren
+     Pakete, zeichnet Start-Zeitpunkt auf.
+   - `apt upgrade: full` – vollständiges Upgrade aller Pakete. Benachrichtigt
+     Handler `apt cleanup` und `apt autoremove`.
+   - `reboot.yml` – entscheidet über Reboot-Vergleich von laufendem und
+     installiertem Kernel, rebootet asynchron, wartet auf Wiederkehr,
+     erfasst Downtime. Wird in LXC-Containern übersprungen.
+   - `logging_postflight.yml` – berechnet Dauer, schreibt Log-Eintrag mit
+     allen Fakten in `os_update_log_file` (delegiert an localhost).
+
+### Reboot-Entscheidung
+
+- Läuft ein älterer Kernel als installiert, gilt `reboot_required: true`.
+- Der Reboot erfolgt mit `async: 1`, `poll: 0`, gefolgt von
+  `wait_for_connection` (Delay 10s, Timeout 600s).
+- In LXC-Containern (`virtualization_type == "lxc"`) wird der gesamte
+  Reboot-Block übersprungen.
+
+## Variablen
+
+| Variable                    | Typ    | Default                                                  | Beschreibung                                                |
+|-----------------------------|--------|----------------------------------------------------------|-------------------------------------------------------------|
+| `os_update_auto_upgrade`    | bool   | `true`                                                   | (Steuer-Vorbereitung) Auto-Upgrade erlauben                 |
+| `os_also_update_mirror`    | bool   | `false`                                                  | Spiegel-Wechsel und Codename-Rewrite durchführen           |
+| `os_update_logging_enabled`| bool   | `true`                                                   | Update-Logging aktivieren                                  |
+| `os_update_log_dir`         | string | `/ansible/logs`                                          | Basis-Verzeichnis für Logs                                 |
+| `os_update_log_inventory`   | string | `{{ inventory_file \| basename \| splitext \| first }}`  | Inventory-Name (abgeleitet)                                |
+| `os_update_log_file`        | string | `<log_dir>/<inventory>/<hostname>/update.log`            | Pfad zur Update-Log-Datei (Controller-seitig)              |
+| `os_update_mirrors`         | list   | siehe `defaults/`                                        | Zwei Spiegel: `[0]` Haupt-Spiegel, `[1]` Security-Spiegel   |
+| `os_update_version_codename`| string | `{{ ansible_facts['distribution_release'] }}`           | Ziel-Codename für Template-Ausfüllung                      |
+| `os_update_debian_codenames`| list   | `[trixie, bookworm, bullseye]`                           | Erlaubte Codenames, die in `.list`/`.sources` umgeschrieben werden |
+
+> **Achtung:** `os_update_version_codename` wird in
+> `inventory/group_vars/debian.yml` auf `trixie` überschrieben. Nicht blind
+> ändern – der Wert steuert die Template-Ausfüllung der `sources.list`.
+
+## Templates
+
+| Template                  | Ziel                                            | Debian-Version |
+|---------------------------|-------------------------------------------------|----------------|
+| `sources.list.j2`         | `/etc/apt/sources.list`                         | < 13           |
+| `sources.list-deb822.j2`  | `/etc/apt/sources.list.d/debian.sources`        | >= 13          |
+
+Beide Templates erzeugen `main`, `-updates`, `-backports` und `-security`
+Einträge mit `main contrib non-free non-free-firmware`.
+
+## Handler
+
+| Handler          | Auslöser                          | Beschreibung                      |
+|------------------|-----------------------------------|-----------------------------------|
+| `apt cleanup`    | `apt upgrade: full`              | `apt clean` + `apt autoclean`    |
+| `apt autoremove` | `apt upgrade: full`              | `apt autoremove`                  |
+
+## Tags
+
+Die Rolle vergibt keine eigenen Tags.
+
+## Abhängigkeiten
+
+- Keine weiteren Rollen.
+- Collections: `ansible.builtin` (Bordmittel).
+- Empfohlener Partner: `healthcheck`-Rolle (für Quality-Gate nach Update).
+
+## Hinweise
+
+- **Logging**: Das Log wird **delegiert an localhost** geschrieben unter
+  `logs/<inventory>/<hostname>/update.log`. Das Verzeichnis `logs/` ist
+  git-ignored. Die Struktur ist so gewählt, dass die `healthcheck`-Rolle
+  ihre `quality_gate`-Sektion an denselben Log-Eintrag anhängen kann.
+- **Spiegel-Wechsel** (`os_also_update_mirror: true`) ist potenziell
+  destruktiv: bestehende `sources.list` wird gesichert bzw. entfernt.
+  Vorsicht beim Wechsel auf andere Debian-Releases.
+- **Codename-Rewrite** greift nur bei Codenames aus
+  `os_update_debian_codenames` – schützt davor, Drittrepositories
+  versehentlich umzuschreiben.
+- **LXC**: In Containern wird der Reboot-Block komplett übersprungen
+  (`virtualization_type != "lxc"`).
+- **Idempotenz**: `apt upgrade: full` meldet `changed`, wenn Pakete
+  aktualisiert wurden; ohne anstehende Updates ist der Lauf "ok".