ansible-playbooks/roles/os-updates/README.md

# 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".