ansible-playbooks/README.md

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