added AGENTS.md

2026-07-18 21:36:16 +02:00
parent fb779abd06
commit 8d64bf5982
1 changed files with 166 additions and 0 deletions
@@ -0,0 +1,166 @@
+# 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/<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/dmc12.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.