From 8d64bf59828b14a102d8f8dd3d317fa79bb703f2 Mon Sep 17 00:00:00 2001 From: DerLinkman Date: Sat, 18 Jul 2026 21:36:16 +0200 Subject: [PATCH] added AGENTS.md --- AGENTS.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..79079b6 --- /dev/null +++ b/AGENTS.md @@ -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//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. \ No newline at end of file