Ansible Playbooks

Zentrale Ansible-Sammlung für die Bereitstellung, Härtung, Aktualisierung und Überwachung von Debian-Hosts. Das Repository enthält eigenständige Rollen, zugehörige Playbooks, mehrere Inventories sowie eine Docker-basierte Ausführungsumgebung, sodass Playbooks direkt aus einem Container heraus gestartet werden können.

Inhaltsübersicht

.
├── ansible.cfg            # Globale Ansible-Konfiguration
├── bootstrap.yml          # Top-Level-Playbook für die Ersteinrichtung
├── execute.sh             # Startet die Docker-Ausführungsumgebung
├── setenv.sh              # Umgebungsvariablen für Proxmox (nicht im Repo)
├── vault.yml              # Ansible-Vault-verschlüsselte Secrets
├── docker/                # Dockerfile & Requirements für die Laufzeit-Umgebung
├── inventory/             # Inventories mit group_vars
├── logs/                  # Update-Logs (git-ignored)
├── playbooks/             # Playbooks, die die Rollen einbinden
└── roles/                 # Wiederverwendbare Ansible-Rollen

Voraussetzungen

• Ansible >= 2.20 (im Docker-Image bereits enthalten)
• Ziel-Hosts: Debian (alle Playbooks prüfen os_family == "Debian")
• Ansible-Collections: ansible.posix, community.general, community.docker, community.zabbix (siehe docker/requirements.yml)
• Zugang: SSH-Zugang als Benutzer admin mit hinterlegtem Public Key

Docker-Ausführungsumgebung

Damit Playbooks nicht lokal installiert werden müssen, liefert das Repository ein fertiges Docker-Image. execute.sh erstellt ein IPv6-fähiges Bridge-Netzwerk, startet einen interaktiven Container und mountet das Repository nach /ansible:

./execute.sh

Im Container stehen Aliase wie ap (ansible-playbook), ag (ansible-galaxy) und av (ansible-vault) zur Verfügung. Das Image wird über docker/Dockerfile gebaut, die benötigten Collections werden beim Build automatisch installiert.

Inventories

Alle Inventories liegen unter inventory/. Pro Inventory existiert eine gleichnamige Datei sowie ein Eintrag in group_vars/:

Inventory	Datei	group_vars	Beschreibung
DMC12 (Umgebung)	dmc12.yml	debian.yml	Debian-Hosts & Proxmox-Knoten
Home	home.yml	home.yml	Heimisches Netzwerk (10.13.37.0/24)
External	external.yml	external.yml	Externe Hosts (IPv6)

Die group_vars definieren standortspezifische Werte wie Zabbix-Server, Spiegelserver und autorisierte SSH-Keys.

Playbooks

Playbook	Rolle(n)	Zweck
bootstrap.yml	bootstrap	Vollständige Ersteinrichtung eines Debian-Hosts
playbooks/docker.yml	docker	Docker Engine installieren
playbooks/monitoring.yml	monitoring	Zabbix Agent 2 installieren & registrieren
playbooks/os-updates-deb.yml	os-updates, healthcheck	Pakete aktualisieren + Healthcheck
playbooks/upgrade-hawser.yml	hawser	Hawser-Stack aktualisieren
playbooks/hardening/manage-ssh-keys.yml	manage-ssh-keys	SSH-Schlüssel hartieren

Aufrufbeispiele

# Ersteinrichtung aller Hosts im DMC12-Inventory
ansible-playbook -i inventory/dmc12.yml bootstrap.yml

# Nur Docker auf einem einzelnen Host installieren
ansible-playbook -i inventory/home.yml playbooks/docker.yml -l rp

# OS-Updates inkl. Healthcheck
ansible-playbook -i inventory/dmc12.yml playbooks/os-updates-deb.yml

# Hawser aktualisieren
ansible-playbook -i inventory/dmc12.yml playbooks/upgrade-hawser.yml

# SSH-Keys härtene
ansible-playbook -i inventory/dmc12.yml playbooks/hardening/manage-ssh-keys.yml

Rollen

Rolle	Kurzbeschreibung	Dokumentation
bootstrap	Ersteinrichtung: Pakete, Admin-User, SSH, MOTD, sysctl, Docker, Monitoring	roles/bootstrap/README.md
docker	Installation der Docker Engine über das offizielle Repository	roles/docker/README.md
hawser	Aktualisierung des Hawser Docker-Compose-Stacks	roles/hawser/README.md
healthcheck	Quality-Gate: prüft laufende Container nach Updates	roles/healthcheck/README.md
manage-ssh-keys	Verwaltung erwünschter/unerwünschter SSH-Keys (Hardening)	roles/manage-ssh-keys/README.md
monitoring	Zabbix Agent 2: Installation, TLS-PSK, Docker-Plugin, API-Registrierung	roles/monitoring/README.md
os-updates	Debian-Paketaktualisierung mit Spiegel-Wechsel, Reboot & Logging	roles/os-updates/README.md

Secrets & Vault

Sensible Werte (z. B. monitoring_zabbix_api_password, admin_password) liegen verschlüsselt in vault.yml. Zum Entschlüsseln wird eine Vault-Passwort benötigt, die in .vault_pass hinterlegt ist (git-ignored). Beim Aufruf muss Ansible die Vault-Passwort-Datei kennen:

ansible-playbook -i inventory/dmc12.yml --vault-password-file .vault_pass bootstrap.yml

Hinweis: Die Datei setenv.sh enthält Zugangsdaten für Proxmox und ist bewusst nicht für eine Veröffentlichung vorgesehen. .vault_pass und setenv.sh stehen in .gitignore.

Logging

Die Rollen os-updates und healthcheck schreiben pro Host ein Update-Log unter logs/<inventory>/<hostname>/update.log. Das Verzeichnis logs/ ist git-ignored und dient als lokales Audit-Trail.

Konfiguration

ansible.cfg deaktiviert Host-Key-Checking und legt ./roles als Rollen-Pfad fest. SSH-Verbindungen verwenden StrictHostKeyChecking=no sowie /dev/null als KnownHosts-Datei, was die Ersteinrichtung neuer Hosts erleichtert – in produktiven Umgebungen entsprechend restriktiver konfigurieren.

Beitragen

1. Änderungen lokal testen – idealerweise über ./execute.sh im Container.
2. Variablen in defaults/main.yml der jeweiligen Rolle pflegen und in der Rollen-README dokumentieren.
3. Keine Secrets unverschlüsselt committen (Vault nutzen).