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:

Titel & Kurzbeschreibung – was macht die Rolle, Verweis auf Repo-README
Voraussetzungen – OS, Collections, Zugriff
Einbindung – Beispiel-Playbook oder Aufruf
Funktionsweise – Reihenfolge der Tasks, was passiert
Variablen – Tabelle mit Name, Typ, Default, Beschreibung
- Trennen zwischen Variablen mit Defaults (defaults/main.yml) und Steuer-Variablen ohne Defaults
Templates – Template-Datei → Ziel-Pfad
Handler – Handler-Name → Auslöser
Tags – verfügbare Tags und Beispiel
Abhängigkeiten – andere Rollen oder Collections
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.

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

Änderungen im Docker-Container testen: ./execute.sh
Lint prüfen, falls verfügbar: ansible-lint (nicht im Repo vorausgesetzt, aber empfohlen).
Playbook Dry-Run: --check verwenden, wo sinnvoll.
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.

8.2 KiB Raw Permalink Blame History Unescape Escape