Servercow-Ansible/operating-automation
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
70a6f6acea00f79bef85bf94745d037c4f4d7586
operating-automation/docs/00-Übersicht.md
Ansible Servercow da81549161 add docs
2026-06-11 18:04:41 +02:00

217 lines
10 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink