ansible-playbooks/AGENTS.md

AGENTS.md

Richtlinien und Kontext für AI-Agenten (z. B. Mammouth Code, Claude, GPT), die an diesem Ansible-Repository arbeiten. Diese Datei fasst Repository-spezifische Konventionen zusammen, damit Änderungen konsistent und nachvollziehbar bleiben.

Project Wiki (Automatic Instructions)

• Before implementing, modifying, debugging, refactoring, testing, documenting, or planning code, read .project-wiki/INDEX.md and follow its routing to the smallest relevant set of wiki documents (automatic context preflight).
• After making source changes, update the affected .project-wiki/ records (technical docs, traceability maps, section indexes, REGISTRY.yml, STATUS.md) as part of the same task.
• Use the wiki sync mode only for manual or externally changed code; agent-made changes are updated directly (automatic post-implementation wiki update).
• After every meaningful wiki edit, reconcile affected indexes, REGISTRY.yml, STATUS.md, traceability, and append an entry to .project-wiki/logs/wiki-log-YYYY-MM.md.
• Write all wiki content and generated instruction blocks in English; reply to the user in their chat language.

Repository-Übersicht

Zentrale Ansible-Sammlung für die Bereitstellung, Härtung, Aktualisierung und Überwachung von Debian-Hosts.

.
├── 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 (git-ignored)
├── vault.yml              # Ansible-Vault-verschlüsselte Secrets
├── .vault_pass            # Vault-Passwort (git-ignored)
├── 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

Rollen

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

Jede Rolle besitzt eine eigene README.md unter roles/<name>/README.md, die Anforderungen, Variablen, Templates, Handler, Tags und Nutzung dokumentiert. Die globale README.md im Repo-Root verweist auf diese Rollen-READMEs und beschreibt Inventories, Playbooks und die Docker-Ausführungsumgebung.

WICHTIG: Dokumentationspflicht bei Änderungen

Jede neue Funktion, jeder neue Parameter und jede neue Variable MUSS dokumentiert werden. Keine undokumentierten Änderungen committen.

Wann welche README aktualisiert werden muss

Art der Änderung	Zu aktualisierende Datei(en)
Neue Variable in defaults/main.yml einer Rolle	roles/<rolle>/README.md (Abschnitt "Variablen")
Neue Task-Datei / neuer Subtask in einer Rolle	roles/<rolle>/README.md (Abschnitte "Funktionsweise" / "Tasks")
Neues Template oder Handler	roles/<rolle>/README.md (Abschnitt "Templates" / "Handler")
Neuer Tag	roles/<rolle>/README.md (Abschnitt "Tags")
Neues Playbook oder wesentliche Änderung an bestehendem	Globale README.md (Tabelle "Playbooks")
Neue Rolle	Globale README.md (Tabellen "Inhalt" & "Rollen") + roles/<neu>/README.md erstellen
Neues Inventory oder group_vars	Globale README.md (Abschnitt "Inventories")
Änderung an ansible.cfg, execute.sh oder docker/	Globale README.md
Änderung an Secrets / Vault-Handhabung	Globale README.md (Abschnitt "Secrets & Vault")

Konventionen für Rollen-READMEs

Jede roles/<name>/README.md soll mindestens folgende Abschnitte enthalten:

1. Titel & Kurzbeschreibung – was macht die Rolle, Verweis auf Repo-README
2. Voraussetzungen – OS, Collections, Zugriff
3. Einbindung – Beispiel-Playbook oder Aufruf
4. Funktionsweise – Reihenfolge der Tasks, was passiert
5. Variablen – Tabelle mit Name, Typ, Default, Beschreibung
   • Trennen zwischen Variablen mit Defaults (defaults/main.yml) und Steuer-Variablen ohne Defaults
6. Templates – Template-Datei → Ziel-Pfad
7. Handler – Handler-Name → Auslöser
8. Tags – verfügbare Tags und Beispiel
9. Abhängigkeiten – andere Rollen oder Collections
10. Hinweise – Besonderheiten, Plattform-Einschränkungen

Konventionen für die globale README

• Tabellen für Playbooks, Inventories und Rollen aktuell halten
• Neue Rollen-READMEs in der Rollen-Tabelle verlinken
• Aufrufbeispiele bei neuen Playbooks ergänzen

Technische Konventionen

Sprache & Stil

• Dokumentation (README.md, Kommentare in Templates): Deutsch
• Code: Englisch (Variablennamen, Task-Names, Module)
• Keine Kommentare in Task-Dateien, außer wenn der User es ausdrücklich wünscht (siehe System-Regeln). Inline-Doku über die READMEs laufen.

Ansible-Stil

• Module grundsätzlich mit FQCN verwenden (ansible.builtin.apt, ansible.builtin.template, …), ausgenommen ältere Tasks, die kurze Namen nutzen – bei neuen Tasks FQCN verwenden.
• Variablen-Defaults immer in defaults/main.yml, nie hart in Tasks.
• Variablen pro Inventory in inventory/group_vars/<gruppe>.yml überschreiben.
• Templates nutzen # {{ ansible_managed }} als Header.
• Tasks sind in Subtask-Dateien (tasks/<name>.yml) ausgelagert, wenn eine Rolle mehr als eine logische Einheit hat. tasks/main.yml enthält nur import_tasks/include_tasks und import_role.

Secrets

• Sensible Werte (Passwörter, API-Keys) gehören in vault.yml (verschlüsselt).
• .vault_pass, setenv.sh, logs/, .zabbix-psk sind git-ignored und dürfen niemals committet werden.
• Klartext-Secrets in defaults/ oder group_vars/ vermeiden; stattdessen Vault-Referenz verwenden.

OS-Unterstützung

• Alle Playbooks prüfen ansible_facts['os_family'] == "Debian" und brechen bei Nicht-Debian ab. Neue Playbooks müssen diesen Check enthalten.
• LXC-Container: Tasks, die sysctl oder reboot betreffen, müssen virtualization_type != "lxc" prüfen und übersprungen werden.

Tags

• Verwendete Tags pro Rolle in der jeweiligen README dokumentieren.
• Gängige Tags: ssh, motd, bashrc, sysctl, monitoring.

Collections

Benötigte Collections (in docker/requirements.yml):

• ansible.posix
• community.general
• community.docker
• community.zabbix (nur in der monitoring-Rolle verwendet – ggf. ergänzen)

Docker-Ausführungsumgebung

• docker/Dockerfile baut ein debian:trixie-slim-Image mit ansible-core.
• execute.sh startet einen interaktiven Container, der das Repo nach /ansible mountet und SSH-Keys unter /root/.ssh bereithält.
• Bei Änderung der Collections muss docker/requirements.yml aktualisiert und ein Image-Rebuild durchgeführt werden.

Testing & Verifikation

1. Änderungen im Docker-Container testen: ./execute.sh
2. Lint prüfen, falls verfügbar: ansible-lint (nicht im Repo vorausgesetzt, aber empfohlen).
3. Playbook Dry-Run: --check verwenden, wo sinnvoll.
4. Nach Änderungen an einer Rolle die zugehörige README.md aktualisieren.

Häufige Fallstricke

• os_update_version_codename in inventory/group_vars/debian.yml: Default trixie. Nicht blind ändern – wird für Template-Ausfüllung der sources.list verwendet.
• ssh_service_name: Auf manchen Hosts heißt der Service ssh, nicht sshd (siehe inventory/cloudlorean.yml: gitea, ipam). Beim Hinzufügen neuer Hosts prüfen.
• PSK-Store: monitoring speichert pro Host eine PSK unter .zabbix-psk/<hostname>.psk (git-ignored). Bei Host-Umbenennung PSK migrieren oder neu generieren – sonst stimmt die Zabbix-Registrierung nicht.
• Logs: os-updates und healthcheck schreiben Logs nach logs/<inventory>/<hostname>/update.log (auf dem Controller, delegiert). Verzeichnis ist git-ignored.