added readmes (#1)

Co-authored-by: DerLinkman <derlinkman@gmail.com> Reviewed-on: #1
2026-07-18 19:36:54 +00:00
parent 8d64bf5982
commit cab59c1658
7 changed files with 782 additions and 0 deletions
@@ -0,0 +1,138 @@
+# 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`:
+
+```bash
+./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
+
+```bash
+# 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](roles/bootstrap/README.md)         |
+| `docker`            | Installation der Docker Engine über das offizielle Repository              | [roles/docker/README.md](roles/docker/README.md)               |
+| `hawser`            | Aktualisierung des Hawser Docker-Compose-Stacks                            | [roles/hawser/README.md](roles/hawser/README.md)               |
+| `healthcheck`       | Quality-Gate: prüft laufende Container nach Updates                        | [roles/healthcheck/README.md](roles/healthcheck/README.md)     |
+| `manage-ssh-keys`    | Verwaltung erwünschter/unerwünschter SSH-Keys (Hardening)                  | [roles/manage-ssh-keys/README.md](roles/manage-ssh-keys/README.md) |
+| `monitoring`        | Zabbix Agent 2: Installation, TLS-PSK, Docker-Plugin, API-Registrierung     | [roles/monitoring/README.md](roles/monitoring/README.md)       |
+| `os-updates`        | Debian-Paketaktualisierung mit Spiegel-Wechsel, Reboot & Logging           | [roles/os-updates/README.md](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:
+
+```bash
+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).