CIVITAS/CORE V1s: Buildvariante und AddOn-Baseline

Diese Spezifikation ergänzt das Vorhaben Statische Masterportal-Konfiguration. Sie definiert das Zielbild einer klar getrennten Buildvariante CIVITAS/CORE V1s und legt die Kriterien für eine restaurierbare AddOn-Test-Baseline auf Basis eines Proxmox-Backups fest.

1. Zweck

Drei Ziele stehen im Vordergrund:

• Schutz der funktionierenden V1-Referenz: Die bestehende CIVITAS/CORE-V1-Variante mit S3-/RustFS-basierter Masterportal-Konfiguration funktioniert und bleibt zunächst unverändert erhalten. Sie darf nicht durch unfertige Änderungen an der statischen Konfigurationsvariante instabil werden.
• Kontrollierte Entwicklung der V1s-Variante: Die neue Variante mit statischer und versionierter Masterportal-Konfiguration wird als klar getrennte Buildvariante entwickelt und abgenommen. Der konkrete Auslieferungsmechanismus wird gesondert entschieden.
• Vorbereitung einer schnell restaurierbaren AddOn-Test-Baseline: Ein definierter Proxmox-Backup-Breakpoint soll spätere p2d2-AddOn-Experimente ermöglichen, ohne bei jedem Test den vollständigen CIVITAS/CORE-Build erneut durchlaufen zu müssen.

2. Varianten und Abgrenzung

Variante	Bedeutung
V1	Bestehende, funktionierende Referenzvariante mit bisheriger S3-/RustFS-basierter Masterportal-Konfiguration.
V1s	CIVITAS/CORE V1 mit statischer und versionierter Masterportal-Konfiguration. Der konkrete Auslieferungsmechanismus wird gesondert entschieden.
V2	Eigenständiges, späteres Vorhaben. V2 ist nicht von V1s abgeleitet und verwendet voraussichtlich eine andere Architektur (Helm-Charts statt Ansible/cc_cli).

V1s ist keine CIVITAS/CORE-Hauptversion und keine V2-Vorwegnahme. Der Buchstabe s steht ausschließlich für die statische Masterportal-Konfiguration.

Die nachfolgende Verzeichnisstruktur ist implementiert (Stand 2026-08-26):

civitas_einrichtung/
├── install_civitas_core_V1.sh
├── modules_V1/
├── templates_V1/
├── overlay_V1/
│
├── install_civitas_core_V1s.sh
├── modules_V1s/
├── templates_V1s/
└── overlay_V1s/

Die technischen Details zur V1s-Buildvariante sind in der Detail-Spezifikation Serveraufbau V1s dokumentiert (index.md, inventory-delta.md, portal-backend-image-build.md).

Bekannte Einschränkung: Monitoring/Prometheus

Stand: Monitoring (Prometheus/Loki/Grafana) aktiviert; inv_access.apis.import: true reaktiviert die Apisix-Routen (2026-08-31).

Es sind zwei getrennte Sachverhalte zu unterscheiden:

1. cc_cli validate (Business-Regel): Die Regel „Ensure that Prometheus and Loki are enabled if APIs are enabled and imported“ (cc_cli/config/semantic_rules.yaml) verlangt:

   inv_access.apis.import == false
     ODER (inv_op_stack.monitoring.prometheus.enable == true
           UND  inv_op_stack.monitoring.loki.enable == true)

   Die V1s-Buildvariante benötigt die Apisix-Routen für die Geodata-Kernkomponenten (u. a. portalBackend), daher ist inv_access.apis.import: true gesetzt. Die Regel wird damit über den zweiten ODER-Zweig erfüllt: inv_op_stack.monitoring.prometheus.enable und inv_op_stack.monitoring.loki.enable sind beide true.

2. Prometheus-Operator-CRDs: Bei aktivem Monitoring rendert das APISIX-Helm-Chart metrics.serviceMonitor.enabled: true. Die dafür nötigen monitoring.coreos.com/v1-CRDs (ServiceMonitor, PodMonitor, PrometheusRule, …) installiert V1s vorab in modules_V1s/05_addons.sh (install_prometheus_operator_crds(), Version v0.89.0). Der kube-prometheus-stack lief im Live-Lauf nicht zuverlässig vor der APISIX-Installation an. Ohne den Vorab-Install fehlte die ServiceMonitor-CRD zum Zeitpunkt des APISIX-Helm-Installs. Der Vorbereitungsschritt ist daher erforderlich und erfolgt idempotent vor install_nginx_ingress.

Hinweis zu grafana.enable: Der Task "Monitoring: [Check] Grafana reachable" in tasks/operation/monitoring.yml ist nicht mit when: gegated und läuft daher immer, sobald inv_op_stack.monitoring.enable: true ist. Deshalb muss grafana.enable: true gesetzt sein, solange Monitoring insgesamt aktiv ist — andernfalls entsteht am ungated Health-Check derselbe 404-Effekt wie beim früheren portalBackend-Fall.

3. Entwicklungs- und Übernahmeregel

• V1s startet als bewusst abgeleitete, kontrollierte Buildvariante auf Grundlage der V1-Referenz.
• Abweichungen zwischen V1 und V1s müssen dokumentiert und begründet sein.
• Sicherheits- und Stabilitätskorrekturen aus V1 dürfen später gezielt nach V1s übernommen werden.
• Es gibt keine implizite, automatische Synchronisierung zwischen V1 und V1s.
• V1 bleibt bis zur erfolgreichen Abnahme von V1s unverändert als Referenz erhalten.

4. V1s-AddOn-Baseline

Nach erfolgreicher V1s-Abnahme soll ein definierter Proxmox-Backup-Breakpoint entstehen:

V1s-Build und Plattformabnahme erfolgreich
        ↓
V1s-AddOn-Baseline sichern
        ↓
p2d2-AddOn iterativ installieren und testen
        ↓
bei Fehlern: Restore der V1s-AddOn-Baseline
        ↓
nur AddOn und dessen Konfiguration erneut ausrollen

Zweck des Breakpoints ist, für p2d2-AddOn-Experimente nicht jedes Mal den vollständigen CIVITAS/CORE-Build erneut durchlaufen zu müssen.

Ein Backup darf erst dann als V1s-AddOn-Baseline gelten, wenn alle folgenden Kriterien erfüllt sind:

• der V1s-Build war ohne nicht dokumentierte manuelle Nacharbeiten erfolgreich,
• Cluster, zentrale Dienste, Routing, TLS und Identitätsmanagement sind abgenommen,
• das Masterportal lädt die statische beziehungsweise versionierte Konfiguration,
• im portal-backend tritt kein Fehler wegen fehlender Konfigurationsdateien auf,
• die lokale RustFS-LXC beziehungsweise deren Credentials sind für die V1s-Portal-Auslieferung nicht erforderlich,
• der zugrunde liegende Git-Stand und die relevanten Artefakt-Versionen sind dokumentiert,
• ein Restore dieser Baseline wurde mindestens einmal isoliert erfolgreich getestet.

Stand 2026-08-31: Die ersten fünf Kriterien sind durch den erfolgreichen V1s-Testlauf erfüllt. Das Kriterium zur Dokumentation von Git-Stand und Artefakt-Versionen wird in der laufenden Doku-Aktualisierung nachgezogen. Das Restore-Kriterium bleibt formal offen.

Am 2026-08-31 kam es beim Server-Shutdown zu einem Fehlstart des V1s-Clusters. Der zuvor manuell angelegte PBS-Snapshot vm/2010/2026-08-31T20:50:27Z wurde eingespielt. Danach liefen alle Komponenten ohne manuellen Eingriff wieder vollständig und öffentlich erreichbar. Das ist ein faktischer Restore-Nachweis, kein geplanter isolierter Test im Sinne von Kriterium 7. Kriterium 7 bleibt deshalb formal offen, der faktische Nachweis ist aber dokumentiert.

Belege aus dem faktischen Restore:

• Kriterium 3 und 4: config.json und services-internet.json wurden nach dem Restore ohne Eingriff mit gültigem Inhalt ausgeliefert.
• Kriterium 5: S3_ENABLED=false bestand zum Zeitpunkt des Restore und danach. Die übrigen S3_*-Variablen stehen auf unused beziehungsweise Default.
• Clusterzustand: 28 Pods in 11 Namespaces Running, keine CrashLoopBackOff, keine Pending. Alle 11 Helm-Releases blieben auf REVISION 1 und wurden nach dem Restore nicht neu ausgerollt.

Ein Backup ist erst nach einem verifizierten Restore als AddOn-Baseline zulässig. Das Backup ersetzt keinen AddOn-Rückbau: Ein Rückbau p2d2-eigener Ressourcen folgt eigenen, AddOn-spezifischen Regeln.

5. Beziehung zum AddOn

• Die V1s-AddOn-Baseline ist die vorgesehene Testbasis für die Entwicklung des p2d2-AddOns.
• Nach einem Restore sollen nur AddOn-Artefakte und AddOn-Konfigurationen erneut ausgerollt werden; ein vollständiger CIVITAS/CORE-Build ist danach nicht erforderlich.
• Es besteht kein Anspruch, dass alle Details bereits entschieden oder implementiert sind.

Die konkrete Auslieferung der p2d2-Masterportal-Instanzkonfiguration bleibt eine offene Architekturentscheidung (siehe Zielbild und Abgrenzung).

6. Offene Punkte

Die V1s-Skriptstruktur und der Artefakt-/Image-Build-Prozess sind implementiert und nicht mehr offen. Die folgenden Punkte sind noch zu klären:

• genaue Abnahmetests,
• Backup-Namens- und Aufbewahrungskonzept,
• konkrete Preflight- und Restore-Automatisierung,
• Konfigurations-Lifecycle einer späteren p2d2-Masterportal-Instanz: Abgrenzung zwischen Build-Time-Artefakten, Deployment-Time-Konfiguration, schnell aktualisierbarer Instanzkonfiguration und sensiblen Werten.

Verwandte Seiten

• Übersicht – Gesamtvorhaben der statischen Masterportal-Konfiguration
• Zielbild und Abgrenzung – Ausgangslage, Zielarchitektur und offene Entscheidungen
• S3-zu-statisch-Migration – Migrationsvorhaben, Prinzipien und konzeptionelle Abnahme
• p2d2 als CIVITAS/CORE-V1-AddOn – Zielbild, Voraussetzungen und Lifecycle des AddOns