PKR-Lab

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

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.