60000 - Hintergründe zum Code — Übersicht
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/60000-uebersicht.md
Hintergründe zum Code — Übersicht
Der Code in diesem Repo (Ansible, Helm-Charts, Skripte, Workflows, iOS-App) enthält keine Kommentare. Alles, was früher als Kommentar neben dem Code stand — warum etwas so gebaut ist,
welcher Vorfall eine Regel ausgelöst hat, welche Fallstricke es gibt und was man beim Ändern beachten muss —, steht stattdessen in dieser Kategorie.
Die Fach-Kategorien (a–f, 1–3) beschreiben, was läuft und wie man es bedient. Diese Kategorie beschreibt, warum es so ist. Die Zeitachse eines Vorfalls steht in
5-incidents/ oder d0000, hier steht die Regel, die daraus folgt.
Die Docs
| Doc | Inhalt |
|---|---|
| 60010 Ansible: Hosts, VMs und Playbooks | ENTW- und PROD-VM, Rolle libvirt_host (Bridge, dnsmasq-Snippet, Basis-Image), DNS der VMs, Worker-Playbooks und ihre Reihenfolge, Tailscale-Auth-Keys, WireGuard-Notzugang |
| 60020 Ansible: Rollen | Kiosk-Geräte (alamos, Banana Pi, Xibo), Energie-Rollen, Watchdogs, vmagent und Exporter, journal_upload, Semaphore-Rollen, wireguard_backup, alert_caller (Telefon-Alarm), vaultwarden_restore |
| 60030 ArgoCD, Bootstrap und SealedSecrets | Generierte Bootstrap-Dateien, ignoreDifferences, Rolle argocd, PROD im Hub, Daten-Migrationen, Promotion-Konfiguration, Fallstricke beim Versiegeln |
| 60040 Helm-Charts im TECH-Cluster | Gemeinsame Muster (HPA, Speicher, Root-Container), Zertifikate und TLS, Traefik-Metriken, cloudflared, alle TECH-Apps von alamos bis zammad |
| 60050 Helm-Charts im PROD-Cluster | Regeln für PROD-Kopien, Nextcloud, Immich, Wiki.js und wiki-docs-sync, Xibo, Paperless-ngx |
| 60060 Monitoring und Alerting | Alertmanager-Routing, alle VMRules, Telefon-Alarm (Routen und Paging-Regeln), Scrapes und Labels, VictoriaMetrics, Grafana-Ordner, Logging |
| 60070 lldap | Chart-Entscheidungen und Secrets |
| 60080 carplay-api und iOS-App | Verträge, Absicherung, Datenquellen, Transport und Tailscale in der App, Modelle und Bedienung |
| 60090 pacman (Schulungsobjekt) | Server, Bestenliste, Zugriffslog, Trainingsmodus, Frontend-Skripte |
| 600a0 CI-Workflows, Skripte und Lint | Alle Workflows (inkl. CodeQL und Security-Issues), Promotions- und Sync-Skripte, Ruleset, Dependabot und Renovate, .ansible-lint, .yamllint |
| 600b0 Nachprüfung nach der Repo-Aufspaltung | Befunde und Fixes nach dem Split, Renovate (wiki-sync, Zeitplan, Repos ohne Config), Rulesets und Release-Commit, Testmatrix, Live-Tests, offene Entscheidungen |
| 600c0 capulus-operator | Entscheidungen, Backup-Controller (Spec-Hash, restic-Gruppierung, Skript-Argumente), Alerts, Chart und CI, Reihenfolge der Umstellung |
| 600d0 MDM | Cloudflare und Geräte-Authentifizierung, SCEP-Image, Datenbank, NanoMDM-/NanoDEP-Fallstricke, n8n-Workflows |
Fehlersuche statt Begründung
Wer eine Störung sucht, startet bei der zentralen Fehlersuche. Meldungen und Fehlerbilder der Skripte und Workflows stehen in f00c0, die der Ansible-Rollen auf den Rollen-Seiten. Diese Kategorie hält dagegen fest, warum eine Regel existiert.
So ist ein Eintrag aufgebaut
- Eine Aussage hat eine Fundstelle (Pfad, Datei oder Rolle in Backticks) und eine Begründung. Wo es einen Vorfall gab, steht sein Datum dabei.
- Wer den Code an einer solchen Stelle ändern will, prüft zuerst den Eintrag: Die meisten Regeln existieren, weil ein naheliegender Ansatz schon einmal gescheitert ist.
- Ein Eintrag beschreibt den Grund, nicht den Inhalt des Codes. Was der Code tut, steht im Code und in den Fach-Docs.
Neue Begründungen eintragen
Kommentare nicht wieder in den Code schreiben. Eine neue Begründung, einen neuen Fallstrick oder eine neue Entscheidung trägt man im selben PR wie die Codeänderung in das Doc der passenden Fläche ein
(Tabelle unten), unter der Komponente, zu der sie gehört. Passt ein Thema in kein bestehendes Doc, entsteht ein neues Doc mit der nächsten freien ID (6xxxx, in 0x10-Schritten,
siehe TEMPLATE).
Von der Datei zum Eintrag
| Pfad | Doc |
|---|---|
capulus-ansible/host_vars/, capulus-ansible/group_vars/, capulus-ansible/inventory/, ansible/*.yml, capulus-ansible/roles/libvirt_host, capulus-ansible/roles/dnsmasq, capulus-ansible/roles/disable_eee |
60010 |
capulus-ansible/roles/* (übrige Rollen) |
60020 |
capulus-ansible/roles/argocd, argocd/bootstrap/, argocd/bootstrap-prod/, argocd/promotion.yaml, SealedSecrets |
60030 |
argocd/apps/tech/* (ohne monitoring, lldap, carplay-api, pacman, capulus-operator, mdm) |
60040 |
argocd/apps/prod/*, argocd/apps/entw/* |
60050 |
argocd/apps/tech/monitoring, argocd/apps/tech/logging |
60060 |
argocd/apps/tech/lldap |
60070 |
argocd/apps/tech/carplay-api, ios/ |
60080 |
argocd/apps/tech/pacman |
60090 |
argocd/apps/tech/capulus-operator, capulus-operator (Repo) |
600c0 |
argocd/apps/tech/mdm, argocd/apps/tech/n8n/workflows/mdm-*.json |
600d0 |
.github/workflows/, .github/actions/, .github/dependabot.yml, renovate.json, scripts/, Makefile, .ansible-lint, .yamllint, ops/, CLAUDE.md, .gitignore |
600a0 |
Sync ins Wiki
Die Docs werden von wiki-docs-sync nach Wiki.js gespiegelt, die ganze Ordnerstruktur von pkr-lab-docs bleibt als Seitenbaum erhalten. Aufbau und Betrieb: wiki-sync, Hintergründe in
60050.