# 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)