# 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. ## 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//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//README.md` (Abschnitt "Variablen") | | Neue Task-Datei / neuer Subtask in einer Rolle | `roles//README.md` (Abschnitte "Funktionsweise" / "Tasks") | | Neues Template oder Handler | `roles//README.md` (Abschnitt "Templates" / "Handler") | | Neuer Tag | `roles//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//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//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/.yml` überschreiben. - Templates nutzen `# {{ ansible_managed }}` als Header. - Tasks sind in Subtask-Dateien (`tasks/.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/dmc12.yml`: `gitea`, `ipam`). Beim Hinzufügen neuer Hosts prüfen. - **PSK-Store**: `monitoring` speichert pro Host eine PSK unter `.zabbix-psk/.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///update.log` (auf dem Controller, delegiert). Verzeichnis ist git-ignored.