add docs

2026-06-11 18:04:41 +02:00
parent 590d37e4cf
commit da81549161
9 changed files with 5004 additions and 0 deletions
--- a/docs/01-OS-Management.md
+++ b/docs/01-OS-Management.md
@@ -0,0 +1,346 @@
+# OS-Management
+
+## Übersicht
+
+Diese Kategorie umfasst alle Playbooks und Rollen zur Verwaltung des Debian-Betriebssystems, einschließlich regulärer Updates, Major-Version-Upgrades und Paketquellen-Konfiguration.
+
+**Anwendungsfälle**:
+- Regelmäßige Sicherheits- und Paket-Updates
+- Debian-Versionssprünge (z.B. Bookworm → Trixie)
+- Umstellung auf alternative Mirror-Server
+- Automatisierte Wartungsfenster
+
+---
+
+## Playbooks
+
+### os-update.yml
+
+Führt reguläre Betriebssystem-Updates (Minor-Updates) für Debian-Systeme durch.
+
+**Datei**: `playbooks/os-update.yml`
+
+**Zweck**: Regelmäßige Installation von Sicherheits- und Paket-Updates auf allen Debian-Systemen mit optionaler Snapshot-Erstellung vor dem Update.
+
+**Ziel-Hosts**: `all` (gefiltert auf Debian-Systeme)
+
+**Benutzer**: `tincadmin` (mit sudo-Rechten)
+
+**Verwendete Rollen**:
+- [`proxmox-automation`](06-Virtualisierung.md#rolle-proxmox-automation) (optional, für Snapshots)
+- `os-updates` (siehe unten)
+
+**Wichtige Variablen**:
+
+| Variable | Default | Beschreibung |
+|----------|---------|-------------|
+| `os_also_update_mirror` | `false` | Aktualisiert auch die Mirror-Konfiguration |
+| `os_update_version_codename` | `"trixie"` | Ziel-Codename für Paketquellen |
+| `do_snapshots` | `true` | Erstellt Proxmox-Snapshots vor Updates |
+| `snapshot_name` | `"AUTO_before_os_update_{{ ansible_date_time.date }}"` | Name des Snapshots |
+
+**Verwendungsbeispiel**:
+
+```bash
+# Einfaches Update ohne Snapshots
+ansible-playbook playbooks/os-update.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -e "do_snapshots=false" \
+  -K --ask-vault-pass
+
+# Update mit Mirror-Aktualisierung
+ansible-playbook playbooks/os-update.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -e "os_also_update_mirror=true" \
+  -K --ask-vault-pass
+
+# Update auf einzelnem Host
+ansible-playbook playbooks/os-update.yml \
+  -i inventories/icp-fra-pve1.yml \
+  --limit hostname.example.com \
+  -K --ask-vault-pass
+```
+
+**Abhängigkeiten**:
+- Vault-Datei (`vault.yml`) für Proxmox API-Zugriff
+- Proxmox-Umgebung (wenn `do_snapshots=true`)
+- Verfügbare Updates auf den Zielsystemen
+
+**Besonderheiten**:
+- Prüft mit `apt list --upgradable`, ob Updates verfügbar sind
+- Erstellt Snapshots nur wenn tatsächlich Updates vorhanden sind
+- Überspringt Snapshot-Erstellung automatisch, wenn `do_snapshots=false`
+- Bedingte Proxmox-Integration je nach Konfiguration
+
+**Workflow**:
+1. Lädt Vault-Datei (falls Snapshots aktiviert)
+2. Prüft auf verfügbare Updates
+3. Erstellt Snapshot (optional, nur bei verfügbaren Updates)
+4. Aktualisiert APT-Cache
+5. Führt Paket-Upgrade durch
+6. Neustart bei Kernel-Updates (optional)
+
+---
+
+### os-major-upgrade.yml
+
+Führt ein Debian-Major-Version-Upgrade durch (z.B. Bookworm → Trixie).
+
+**Datei**: `playbooks/os-major-upgrade.yml`
+
+**Zweck**: Upgrade des Debian-Betriebssystems auf die nächste Hauptversion mit automatischer Snapshot-Erstellung und Neustart-Verwaltung.
+
+**Ziel-Hosts**: `all` (gefiltert auf Debian-Systeme)
+
+**Benutzer**: `tincadmin` (mit sudo-Rechten)
+
+**Verwendete Rollen**:
+- [`proxmox-automation`](06-Virtualisierung.md#rolle-proxmox-automation) (für Snapshots)
+- `os-updates` (für Version-Upgrade-Logik)
+
+**Wichtige Variablen**:
+
+| Variable | Default | Beschreibung |
+|----------|---------|-------------|
+| `os_update_major_version` | `true` | Aktiviert Major-Version-Upgrade |
+| `os_update_version_codename` | `"trixie"` | Ziel-Debian-Version |
+| `do_snapshots` | `true` | Erstellt Snapshots vor Upgrade |
+| `snapshot_name` | `"AUTO_before_major_{{ ansible_date_time.date }}"` | Snapshot-Name |
+
+**Verwendungsbeispiel**:
+
+```bash
+# Major-Upgrade auf Trixie mit Snapshots
+ansible-playbook playbooks/os-major-upgrade.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -e "os_update_version_codename=trixie" \
+  -K --ask-vault-pass
+
+# Ohne Snapshots (nicht empfohlen!)
+ansible-playbook playbooks/os-major-upgrade.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -e "do_snapshots=false" \
+  -K --ask-vault-pass
+
+# Test auf einzelnem Host
+ansible-playbook playbooks/os-major-upgrade.yml \
+  -i inventories/icp-fra-pve1.yml \
+  --limit test-host.example.com \
+  -K --ask-vault-pass
+```
+
+**Abhängigkeiten**:
+- Vault-Datei für Proxmox API-Tokens
+- Proxmox-Integration (stark empfohlen für Snapshots)
+- Ausreichend Festplattenspeicher für Upgrade
+- Stabile Netzwerkverbindung
+
+**Besonderheiten**:
+- **Liest `/etc/os-release`** um aktuelle Debian-Version zu ermitteln
+- **Vergleicht** aktuelle und Ziel-Version vor Upgrade
+- **Erstellt Snapshots** vor dem Upgrade (Rollback-Möglichkeit)
+- **Wartet auf Verbindung** nach Neustart (Timeout: 300 Sekunden)
+- **Überspringt** Upgrade automatisch, wenn bereits auf Ziel-Version
+
+**Workflow**:
+1. Lädt Vault-Datei
+2. Liest aktuelle OS-Version aus `/etc/os-release`
+3. Abruft Proxmox VM-ID
+4. Erstellt Pre-Upgrade Snapshot
+5. Aktualisiert Paketquellen auf neue Version
+6. Aktualisiert APT-Cache
+7. Führt `apt dist-upgrade` durch
+8. Startet System neu
+9. Wartet auf Verfügbarkeit des Systems
+
+**⚠️ Warnung**: Major-Upgrades sind kritische Operationen. Immer Snapshots aktivieren und auf Test-Systemen validieren!
+
+---
+
+### os-change-mirror.yml
+
+Ändert die Debian-Paketquellen (APT-Mirror) auf allen Systemen.
+
+**Datei**: `playbooks/os-change-mirror.yml`
+
+**Zweck**: Umstellung der APT-Paketquellen auf alternative Mirror-Server (z.B. auf interne tinc.gmbh Mirrors).
+
+**Ziel-Hosts**: `all` (gefiltert auf Debian-Systeme)
+
+**Benutzer**: `tincadmin` (mit sudo-Rechten)
+
+**Verwendete Rollen**:
+- `os-updates` (Task: `update_mirrors`)
+
+**Wichtige Variablen**:
+- Verwendet Variablen aus `group_vars/all.yml` (`os_update_mirrors`)
+
+**Verwendungsbeispiel**:
+
+```bash
+# Mirror-Änderung auf allen Hosts
+ansible-playbook playbooks/os-change-mirror.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -K
+
+# Auf spezifischer Host-Gruppe
+ansible-playbook playbooks/os-change-mirror.yml \
+  -i inventories/extern.yml \
+  -K
+
+# Mit custom Mirror (überschreibt Defaults)
+ansible-playbook playbooks/os-change-mirror.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -e "os_update_mirrors=['http://deb.debian.org/debian']" \
+  -K
+```
+
+**Abhängigkeiten**:
+- Debian-Betriebssystem (`ansible_os_family == "Debian"`)
+- Keine Vault-Datei erforderlich
+
+**Besonderheiten**:
+- **Überprüfung des Betriebssystems** mit Fehler-Abbruch bei Nicht-Debian
+- **Backup** der alten `/etc/apt/sources.list` wird automatisch erstellt
+- **Aktualisiert** APT-Cache nach Mirror-Änderung
+- **Einfaches Playbook** ohne komplexe Logik
+
+**Workflow**:
+1. Prüft OS-Familie (nur Debian erlaubt)
+2. Erstellt Backup der aktuellen sources.list
+3. Schreibt neue Mirror-Konfiguration
+4. Aktualisiert APT-Cache (`apt update`)
+
+---
+
+## Rollen
+
+### Rolle: os-updates
+
+**Zweck**: Zentrale Rolle für alle OS-Update-Operationen auf Debian-Systemen.
+
+**Pfad**: `roles/os-updates/`
+
+**Hauptaufgaben**:
+
+#### 1. main.yml
+Steuert den Update-Workflow und koordiniert Mirror-Updates und Paket-Upgrades.
+
+#### 2. update_mirrors.yaml
+Aktualisiert die APT-Mirror-Konfiguration in `/etc/apt/sources.list`.
+
+- Verwendet Jinja2-Template `sources.list.j2`
+- Setzt Mirror-URLs aus `os_update_mirrors` Variable
+- Erstellt Backup der Original-Konfiguration
+
+#### 3. upgrade_packages.yaml
+Führt das eigentliche Paket-Upgrade durch.
+
+- Aktualisiert APT-Cache
+- Führt `apt upgrade` oder `apt dist-upgrade` durch
+- Prüft auf Kernel-Updates
+- Triggert Neustart bei Kernel-Update (über Handler)
+
+#### 4. update_major_version.yaml
+Wechselt Debian auf eine neue Hauptversion.
+
+- Ändert Codename in `/etc/apt/sources.list`
+- Führt `apt update` und `apt dist-upgrade` durch
+- Verwaltet Neustart-Logik
+
+**Standardvariablen** (`defaults/main.yml`):
+
+| Variable | Default | Beschreibung |
+|----------|---------|-------------|
+| `os_update_auto_upgrade` | `true` | Automatisches Upgrade aktivieren |
+| `os_also_update_mirror` | `true` | Mirror auch aktualisieren |
+| `os_update_mirrors` | tinc.gmbh Mirrors | Liste der APT-Mirror-URLs |
+| `os_update_major_version` | `false` | Major-Version-Upgrade aktivieren |
+| `os_update_version_codename` | `"bookworm"` | Ziel-Debian-Codename |
+
+**Handler**:
+- `apt cleanup` - Führt `apt autoremove` und `apt clean` aus
+- `Reboot system` - Startet System neu und wartet auf Verfügbarkeit
+
+**Templates**:
+- `sources.list.j2` - Erzeugt `/etc/apt/sources.list` mit konfigurierten Mirrors
+
+**Verwendung in Playbooks**:
+
+```yaml
+- name: OS Updates durchführen
+  hosts: all
+  become: true
+  roles:
+    - role: os-updates
+```
+
+**Verwendung einzelner Tasks**:
+
+```yaml
+- name: Nur Mirrors aktualisieren
+  include_role:
+    name: os-updates
+    tasks_from: update_mirrors
+```
+
+---
+
+## Best Practices
+
+### 1. Snapshot-Verwaltung
+Aktivieren Sie **immer** Snapshots bei Major-Upgrades:
+```bash
+-e "do_snapshots=true"
+```
+
+### 2. Test-First-Ansatz
+Testen Sie Updates zuerst auf einem einzelnen Host:
+```bash
+--limit test-host.example.com
+```
+
+### 3. Wartungsfenster
+Planen Sie OS-Updates in Wartungsfenstern, besonders wenn Neustarts erforderlich sind.
+
+### 4. Mirror-Auswahl
+Verwenden Sie geografisch nahe oder interne Mirrors für schnellere Updates:
+```yaml
+os_update_mirrors:
+  - "http://tinc.gmbh/debian"
+  - "http://tinc.gmbh/debian-security"
+```
+
+### 5. Monitoring nach Updates
+Überprüfen Sie nach Major-Upgrades:
+- System-Services: `systemctl --failed`
+- Kernel-Version: `uname -r`
+- Verfügbare Updates: `apt list --upgradable`
+- Logs: `/var/log/apt/history.log`
+
+---
+
+## Fehlerbehebung
+
+### Problem: Snapshot schlägt fehl
+**Lösung**: Überprüfen Sie Proxmox API-Zugangsdaten in `vault.yml` und Speicherplatz auf dem Storage.
+
+### Problem: APT-Lock während Update
+**Lösung**: Stellen Sie sicher, dass keine anderen APT-Prozesse laufen:
+```bash
+sudo lsof /var/lib/dpkg/lock-frontend
+sudo killall apt apt-get
+```
+
+### Problem: Neustart nach Kernel-Update hängt
+**Lösung**: Überprüfen Sie Console-Zugriff über Proxmox und prüfen Sie auf Boot-Probleme.
+
+### Problem: Mirror nicht erreichbar
+**Lösung**: Testen Sie Mirror-Erreichbarkeit manuell:
+```bash
+curl -I http://tinc.gmbh/debian/
+```
+
+---
+
+**Navigation**: [← Zurück zur Übersicht](00-Übersicht.md) | [Nächstes: Monitoring →](02-Monitoring.md)