166 lines
8.2 KiB
Markdown
166 lines
8.2 KiB
Markdown
# 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. |