DerLinkman
30f3e9a4c6
- replace inventory/dmc12.yml with cloudlorean.yml (+ group_vars) and update all README/AGENTS call examples and the inventory table - move admin_password hash into encrypted vault.yml; remove plaintext copies from roles/bootstrap/defaults and group_vars/external.yml - bootstrap.yml loads vault.yml via vars_files (same pattern as monitoring) - monitoring: PSK config/registration updates, docker role defaults, os-updates logging/reboot refinements, ansible.cfg/execute.sh tweaks - add .project-wiki knowledge base and .github agent instructions
151 lines
8.1 KiB
Markdown
151 lines
8.1 KiB
Markdown
# 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 |
|
||
|------------------|--------------------|------------------------|-------------------------------------------------|
|
||
| Cloudlorean | `cloudlorean.yml` | `cloudlorean.yml`, `debian.yml` | Debian-Hosts & Proxmox-Knoten (u. a. `dmc12`) |
|
||
| 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 Cloudlorean-Inventory
|
||
ansible-playbook -i inventory/cloudlorean.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/cloudlorean.yml playbooks/os-updates-deb.yml
|
||
|
||
# Hawser aktualisieren
|
||
ansible-playbook -i inventory/cloudlorean.yml playbooks/upgrade-hawser.yml
|
||
|
||
# SSH-Keys härtene
|
||
ansible-playbook -i inventory/cloudlorean.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 (`monitoring_zabbix_api_password`, `admin_password`, Proxmox-Zugang)
|
||
liegen verschlüsselt in `vault.yml`. `playbooks/monitoring.yml` und `bootstrap.yml`
|
||
binden die Datei selbst per `vars_files` ein. 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/cloudlorean.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. Für schnellere Ausführungen werden standardmäßig 20 parallele
|
||
Worker (`forks`), SSH-Pipelining und persistente SSH-Verbindungen
|
||
(`ControlPersist=60s`) verwendet. `gathering=smart` vermeidet die erneute
|
||
Faktenabfrage innerhalb eines Laufs, ohne einen persistenten Fakten-Cache mit
|
||
potenziell veralteten Hostdaten einzuführen. `internal_poll_interval` reduziert
|
||
die Wartezeit des Controllers zwischen Worker-Abfragen.
|
||
|
||
SSH-Verbindungen verwenden weiterhin `StrictHostKeyChecking=no` sowie `/dev/null`
|
||
als KnownHosts-Datei, was die Ersteinrichtung neuer Hosts erleichtert – in
|
||
produktiven Umgebungen entsprechend restriktiver konfigurieren. Bei sehr vielen
|
||
gleichzeitig verwalteten Hosts kann `forks` über `ANSIBLE_FORKS` oder einen
|
||
zusätzlichen Konfigurationswert an die Controller- und Netzwerkressourcen
|
||
angepasst werden. Fact-Caching und alternative Strategien wie `free` sind nicht
|
||
global aktiviert, da sie bei diesen Playbooks veraltete Fakten oder eine andere
|
||
Ausführungsreihenfolge verursachen können.
|
||
|
||
## 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).
|