10 KiB
10 KiB
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:
-
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
-
Gruppen-spezifische Variablen - Z.B. für Proxmox-Cluster
-
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
tincadminmit Sudo-Rechten - Betriebssystem: Debian Bookworm oder Trixie auf Zielhosts
Dokumentationsnavigation
Die Dokumentation ist nach funktionalen Kategorien gegliedert:
- OS-Management - Betriebssystem-Updates, Major-Upgrades, Mirror-Verwaltung
- Monitoring - CheckMK-Agent-Installation und -Verwaltung
- Container-Management - Docker-Installation und -Wartung
- Mail-Server-Verwaltung - Mailcow-Automatisierung (13 Playbooks)
- Security & Hardening - SSH-Schlüssel-Verwaltung
- Virtualisierung - Proxmox-Snapshot-Automatisierung
- Basis-System - Grundlegende Systemkonfiguration, ClamAV, Chrony
- Cleanup-Aufgaben - Wartungs- und Bereinigungsroutinen
Quick Start
Grundlegendes Kommando-Muster:
# 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
- Snapshots: Aktivieren Sie Snapshots bei riskanten Operationen (Major-Upgrades, Mailcow-Updates)
- Dry-Run: Nutzen Sie
--checkfür Trockenläufe (wo unterstützt) - Limitierung: Verwenden Sie
--limit hostnamefür Tests auf einzelnen Hosts - Vault-Sicherheit: Bewahren Sie das Vault-Passwort sicher auf
- 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 →