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/00-Übersicht.md
+++ b/docs/00-Übersicht.md
@@ -0,0 +1,216 @@
+# Operating Automation - Ansible-Projekt Dokumentation
+
+## Übersicht
+
+Dieses Ansible-Projekt dient der Automatisierung von Systemadministrations-Aufgaben für eine Debian-basierte Infrastruktur. Es umfasst 26 Playbooks und 10 Rollen zur Verwaltung von Betriebssystem-Updates, Container-Verwaltung, Mail-Server-Betrieb (Mailcow), Monitoring (CheckMK), Virtualisierung (Proxmox) und Sicherheits-Härtung.
+
+## Projektzweck
+
+Das Projekt automatisiert folgende Hauptbereiche:
+- **Betriebssystem-Verwaltung**: Updates, Major-Upgrades, Mirror-Konfiguration
+- **Container-Infrastruktur**: Docker-Installation und -Wartung
+- **Mail-Server-Betrieb**: Umfassende Mailcow-Verwaltung mit 13 spezialisierten Playbooks
+- **Monitoring**: CheckMK-Agent-Installation und -Verwaltung
+- **Virtualisierung**: Proxmox-Snapshot-Verwaltung
+- **Sicherheit**: SSH-Schlüssel-Verwaltung und System-Härtung
+- **Wartung**: Cleanup-Routinen für Snapshots, Container und Agenten-Plugins
+
+## Projektstruktur
+
+```
+operating-automation/
+├── ansible.cfg                 # Ansible-Hauptkonfiguration
+├── vault.yml                   # Verschlüsselte Zugangsdaten (Ansible Vault)
+├── inventories/                # Host-Inventories
+│   ├── extern.yml             # Externe Mail-Server
+│   ├── icp-fra-pve1.yml       # Proxmox-Cluster (6 Hosts, IPv6 TincVPN)
+│   ├── icp-frav-packer01.yml  # Packer-Build-Host
+│   └── group_vars/            # Gruppenvariablen
+│       ├── all.yml            # Globale Variablen für alle Hosts
+│       └── all.example.yml    # Template für Umgebungsanpassungen
+├── playbooks/                  # Ansible-Playbooks
+│   ├── *.yml                  # Root-Level Playbooks (OS, Monitoring, etc.)
+│   ├── cleanups/              # Wartungs- und Bereinigungsaufgaben
+│   ├── docker/                # Docker-Verwaltung
+│   ├── hardening/             # Sicherheits-Härtung
+│   └── managed-mailcow/       # Mailcow-spezifische Automatisierung
+├── roles/                      # Ansible-Rollen
+│   ├── checkmk-monitoring/    # CheckMK-Integration
+│   ├── deploy-clamd/          # ClamAV-Antivirus-Bereitstellung
+│   ├── docker/                # Docker-Verwaltung
+│   ├── manage-ssh-keys/       # SSH-Schlüssel-Administration
+│   ├── managed-mailcow/       # Mailcow-Operationen
+│   ├── os-updates/            # Betriebssystem-Updates
+│   ├── proxmox-automation/    # Proxmox-Snapshot-Verwaltung
+│   ├── ssh/                   # SSH-Konfiguration (in Entwicklung)
+│   ├── system/                # Basis-Systemkonfiguration
+│   └── updates/               # Generische Update-Mechanismen
+└── collections/                # Externe Collections (via ansible-galaxy)
+```
+
+## Ansible-Konfiguration
+
+Die Datei `ansible.cfg` definiert folgende wichtige Einstellungen:
+
+| Einstellung | Wert | Bedeutung |
+|-------------|------|-----------|
+| `host_key_checking` | `False` | Deaktiviert SSH-Host-Key-Überprüfung |
+| `roles_path` | `./roles:/etc/ansible/roles` | Priorisiert lokale Rollen |
+| `interpreter_python` | `/usr/bin/python3` | Erzwingt Python 3 auf allen Zielhosts |
+
+## Inventory-Struktur
+
+Das Projekt nutzt drei separate Inventory-Dateien für unterschiedliche Deployment-Kontexte:
+
+### icp-fra-pve1.yml
+- **Zweck**: Proxmox-Cluster-Verwaltung
+- **Hosts**: 6 Systeme
+- **Adressierung**: IPv6 TincVPN-Adressen
+- **Ziel-OS**: Debian Bookworm/Trixie
+
+### extern.yml
+- **Zweck**: Externe Mail-Server
+- **Adressierung**: IPv4 mit custom SSH-Ports
+- **Besonderheit**: Root-SSH-Zugang
+
+### icp-frav-packer01.yml
+- **Zweck**: Einzelner Packer-Build-Host
+- **Zugriff**: Root via SSH
+
+## Gruppenvariablen (group_vars)
+
+Die Konfiguration erfolgt über eine dreistufige Hierarchie:
+
+1. **all.yml** - Globale Defaults für alle Hosts:
+   - OS-Update-Konfiguration (Mirror, Upgrade-Modi, Ziel-Versionen)
+   - CheckMK-Agent-Version (2.3.0p34 CEE) und Server-URLs
+   - Docker-Mirror und Proxy-Konfiguration
+   - CrowdSec LAPI-Einstellungen
+   - BackupCow Git-Repository
+
+2. **Gruppen-spezifische Variablen** - Z.B. für Proxmox-Cluster
+
+3. **Host-spezifische Variablen** - Inline in Inventory-Dateien
+
+## Externe Abhängigkeiten
+
+Das Projekt benötigt folgende Ansible-Collections (Installation via `ansible-galaxy`):
+
+| Collection | Version | Verwendung |
+|------------|---------|------------|
+| `community.docker` | 3.11.0 | Docker-Operationen (cleanup, image mgmt) |
+| `community.proxmox` | 1.4.0 | Proxmox API (Snapshots, VM-Management) |
+| `checkmk.general` | - | CheckMK-Agent-Deployment & Registrierung |
+
+## Vault-Verwendung
+
+Die Datei `vault.yml` enthält verschlüsselte Zugangsdaten für:
+- Proxmox API-Tokens
+- CheckMK Automation-User und Passwörter
+- Weitere sensible Konfigurationsdaten
+
+**Verwendung**: Playbooks mit Vault-Zugriff müssen mit `--ask-vault-pass` ausgeführt werden.
+
+## Voraussetzungen
+
+- **Ansible**: Version 2.14 oder höher
+- **Python**: Version 3.x auf allen Zielhosts
+- **SSH-Zugriff**: Schlüsselbasierte Authentifizierung als `tincadmin` mit Sudo-Rechten
+- **Betriebssystem**: Debian Bookworm oder Trixie auf Zielhosts
+
+## Dokumentationsnavigation
+
+Die Dokumentation ist nach funktionalen Kategorien gegliedert:
+
+1. **[OS-Management](01-OS-Management.md)** - Betriebssystem-Updates, Major-Upgrades, Mirror-Verwaltung
+2. **[Monitoring](02-Monitoring.md)** - CheckMK-Agent-Installation und -Verwaltung
+3. **[Container-Management](03-Container-Management.md)** - Docker-Installation und -Wartung
+4. **[Mail-Server-Verwaltung](04-Mail-Server-Verwaltung.md)** - Mailcow-Automatisierung (13 Playbooks)
+5. **[Security & Hardening](05-Security-Hardening.md)** - SSH-Schlüssel-Verwaltung
+6. **[Virtualisierung](06-Virtualisierung.md)** - Proxmox-Snapshot-Automatisierung
+7. **[Basis-System](07-Basis-System.md)** - Grundlegende Systemkonfiguration, ClamAV, Chrony
+8. **[Cleanup-Aufgaben](08-Cleanup-Aufgaben.md)** - Wartungs- und Bereinigungsroutinen
+
+## Quick Start
+
+Grundlegendes Kommando-Muster:
+
+```bash
+# Einfaches Playbook ohne Vault
+ansible-playbook playbooks/setup-chronyd.yml -i inventories/icp-fra-pve1.yml -K
+
+# Playbook mit Vault-Zugriff
+ansible-playbook playbooks/os-update.yml -i inventories/icp-fra-pve1.yml -K --ask-vault-pass
+
+# Mit spezifischen Variablen
+ansible-playbook playbooks/os-major-upgrade.yml \
+  -i inventories/icp-fra-pve1.yml \
+  -e "os_update_version_codename=trixie" \
+  -e "do_snapshots=true" \
+  -K --ask-vault-pass
+```
+
+**Parameter-Erklärung**:
+- `-i`: Inventory-Datei
+- `-K`: Fragt nach Sudo-Passwort
+- `--ask-vault-pass`: Fragt nach Vault-Passwort
+- `-e`: Externe Variable (überschreibt Defaults)
+
+## Best Practices
+
+1. **Snapshots**: Aktivieren Sie Snapshots bei riskanten Operationen (Major-Upgrades, Mailcow-Updates)
+2. **Dry-Run**: Nutzen Sie `--check` für Trockenläufe (wo unterstützt)
+3. **Limitierung**: Verwenden Sie `--limit hostname` für Tests auf einzelnen Hosts
+4. **Vault-Sicherheit**: Bewahren Sie das Vault-Passwort sicher auf
+5. **Inventories**: Pflegen Sie getrennte Inventories für Produktion und Test-Umgebungen
+
+## Projekt-Architektur
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Ansible Control Node                      │
+│                                                               │
+│  ┌─────────────┐   ┌──────────────┐   ┌─────────────┐      │
+│  │  Playbooks  │──▶│    Roles     │──▶│ Inventories │      │
+│  └─────────────┘   └──────────────┘   └─────────────┘      │
+│         │                  │                   │             │
+│         │                  │                   │             │
+│         └──────────────────┴───────────────────┘             │
+│                            │                                 │
+└────────────────────────────┼─────────────────────────────────┘
+                             │
+                             ▼
+         ┌───────────────────────────────────────┐
+         │        Target Infrastructure          │
+         │                                       │
+         │  ┌──────────┐  ┌──────────────┐      │
+         │  │ Proxmox  │  │   Mailcow    │      │
+         │  │ Cluster  │  │   Servers    │      │
+         │  └──────────┘  └──────────────┘      │
+         │                                       │
+         │  ┌──────────┐  ┌──────────────┐      │
+         │  │ CheckMK  │  │    Docker    │      │
+         │  │  Agent   │  │  Container   │      │
+         │  └──────────┘  └──────────────┘      │
+         └───────────────────────────────────────┘
+```
+
+## Häufig verwendete Playbooks
+
+| Playbook | Häufigkeit | Zweck |
+|----------|------------|-------|
+| `os-update.yml` | Wöchentlich | Regelmäßige Sicherheitsupdates |
+| `managed-mailcow/update-mailcow.yaml` | Monatlich | Mailcow-Updates |
+| `docker/cleanup-images.yml` | Wöchentlich | Speicherplatz freigeben |
+| `setup-checkmk-monitoring.yml` | Bei neuen Hosts | Monitoring einrichten |
+| `os-major-upgrade.yml` | Bei Releases | Debian-Versionssprung |
+
+## Kontakt und Support
+
+Diese Dokumentation wurde erstellt am: **14. April 2026**
+
+Bei Änderungen an Playbooks oder Rollen sollte diese Dokumentation entsprechend aktualisiert werden.
+
+---
+
+**Navigation**: [Nächstes: OS-Management →](01-OS-Management.md)