From 38eb74797412ceab2634806bcec0c881cce085c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lukas=20Weberru=C3=9F?= Date: Mon, 16 Nov 2026 10:30:21 +0000 Subject: [PATCH] docs: propose repository separation for a slim standalone Accelerator --- README.de.md | 1 + README.md | 1 + docs/architecture.de.md | 2 + docs/architecture.md | 2 + docs/repository-separation-concept.de.md | 299 ++++++++++++++++++ docs/repository-separation-concept.md | 277 ++++++++++++++++ .../docs/architecture.de.md | 2 + .../docs/architecture.md | 2 + 8 files changed, 586 insertions(+) create mode 100644 docs/repository-separation-concept.de.md create mode 100644 docs/repository-separation-concept.md diff --git a/README.de.md b/README.de.md index bf7da46..bf23262 100644 --- a/README.de.md +++ b/README.de.md @@ -28,6 +28,7 @@ können manuell ausgefüllt werden und verwenden ein separates Backend mit eigen - [Erste Schritte](docs/getting-started.de.md) - [Architektur/Module](docs/architecture.de.md) +- [Konzept zur Repository-Trennung](docs/repository-separation-concept.de.md) – schlanker eigenständiger Accelerator und separat versionierter Configurator - [Private-Runner-Konzept](docs/private-runner-concept.de.md) – STACKIT Git, VM-Runner in der SNA, Betrieb mit und ohne Configurator (Architekturvorschlag) - [Corporate-VM: Firewall, NAT und SSH](docs/corporate-vm-connectivity.de.md) - [Landing Zone Configurator](landing-zone-configurator/README.de.md) diff --git a/README.md b/README.md index 2a28dfa..68564c8 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ filled manually and use a separate backend/state. - [Getting Started](docs/getting-started.md) - [Architecture/Modules](docs/architecture.md) +- [Repository separation concept](docs/repository-separation-concept.md) - slim standalone Accelerator and separately versioned Configurator - [Private runner concept](docs/private-runner-concept.md) - STACKIT Git, SNA VM runners, standalone and Configurator operation (architecture proposal) - [Corporate VM connectivity: firewall, NAT and SSH](docs/corporate-vm-connectivity.md) - [Landing Zone Configurator](landing-zone-configurator/README.md) diff --git a/docs/architecture.de.md b/docs/architecture.de.md index efb668f..df62e24 100644 --- a/docs/architecture.de.md +++ b/docs/architecture.de.md @@ -3,6 +3,8 @@ [English](architecture.md) | [Deutsch](architecture.de.md) +Das [Repository-Trennungskonzept](repository-separation-concept.de.md) beschreibt die vorgeschlagene Verschlankung des eigenständig nutzbaren Accelerators und die Auslagerung des Configurators. Es ist noch kein vollzogener Repository-Umzug. + Das [Private-Runner-Konzept](private-runner-concept.de.md) beschreibt die vorgeschlagene Erweiterung für private Service-APIs über STACKIT Git und VM-Runner in der SNA. Es ist noch keine implementierte Ausführungsoption. Dieses Repository ist ein produktionsbereites OpenTofu-/Terraform-Framework für die Bereitstellung einer STACKIT Landing Zone. Es provisioniert die vollständige Cloud-Grundlage: Governance-Hierarchie, Identitäts- und Zugriffsverwaltung, gemeinsame Netzwerke, optionale Firewall, DNS, Geheimnisverwaltung, Observability sowie wiederholbare Projektvorlagen pro Workload. diff --git a/docs/architecture.md b/docs/architecture.md index ee43de4..878beb6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,6 +2,8 @@ [English](architecture.md) | [Deutsch](architecture.de.md) +The [repository separation concept](repository-separation-concept.md) proposes a slimmer independently usable Accelerator and extraction of the Configurator. The repository move has not been implemented. + The [private runner concept](private-runner-concept.md) describes a proposed extension for private service APIs using STACKIT Git and VM runners in the SNA. It is not an implemented execution option. This repository is a production-ready OpenTofu/Terraform framework for deploying a STACKIT Landing Zone. It provisions the complete cloud foundation, covering governance hierarchy, identity and access management, shared networking, optional firewall, DNS, secrets management, observability, and repeatable per-workload project templates. diff --git a/docs/repository-separation-concept.de.md b/docs/repository-separation-concept.de.md new file mode 100644 index 0000000..e7411d6 --- /dev/null +++ b/docs/repository-separation-concept.de.md @@ -0,0 +1,299 @@ +# Konzept zur Repository-Trennung von Accelerator und Configurator + +[English](repository-separation-concept.md) | [Deutsch](repository-separation-concept.de.md) + +Status: Architekturvorschlag vom 16.11.2026. Vereinbartes Hauptmotiv ist ein +kleinerer, übersichtlicherer Accelerator für Nutzer ohne Configurator. Dieses +Konzept verschiebt keine Dateien, legt keine Repositories an, ändert keine +Workflows und deployt nichts. Repository-Namen und Umsetzungsreihenfolge sind +Vorschläge. + +## 1. Nutzerziel und Erfolgskriterien + +Der native Accelerator ist ein vollständig eigenständig nutzbares IaC-Produkt. +Gewöhnlicher Checkout, Dokumentation, Validierung und Releases sollen nur das +enthalten, was diese Nutzung benötigt. Terraform-/OpenTofu-Nutzer müssen sich +nicht mit Webanwendung, Datenbankmigrationen, Assistant, Browser-Tests, +CF-Hosting, Installer oder SaaS-Deployment-Setup des Configurators befassen oder +diese installieren. + +Die Trennung vereinfacht daher primär das Produkt und erzeugt nicht nur zwei +GitHub-Adressen. Native Eingaben, Modulpfade, State-Adressen, Platform-/Application- +CLI-Nutzung und unterstützte native Hilfswerkzeuge bleiben erhalten. Weder +Configurator-Konto, -API, -Datenbank, -Laufzeit, -Release-Berechtigung noch +Anwendungsabhängigkeit werden Voraussetzung für native Nutzung. Optionale +Anwendungshinweise bleiben kurze Links auf deren eigene Dokumentation. + +Die Abnahme misst nativen versionierten Dateibaum, Quell-/Release-Archivinhalt, +Checkout-/Download-Größe, benötigte Werkzeuge und CI-Umfang gegen einen erfassten +Ausgangswert. Dateien bei HEAD zu entfernen beweist keinen kleineren vollständigen +Git-Clone; historische Objekte sind separat zu behandeln (Abschnitt 8). + +## 2. Vorgeschlagene Verantwortungsgrenze + +| Bleibt in `stackit-landing-zone` | Wechselt in vorgeschlagenes `stackit-landing-zone-configurator` | +| --- | --- | +| Native `src/`-Roots/-Module, Referenz-tfvars, native Provider-Vorgaben und benötigte Helfer | API/UI/Worker, Contracts-/Domain-Code, Assistant und Anwendungsassets | +| Native Modul-/Konfigurationstests und native Release-/Deployment-Verifikation | App-/Unit-/Datenbank-/Browser-/Recovery-Integrationstests und HCL-Adapter | +| Native Architektur, Einstieg, CLI-/Betriebs- und Moduldokumentation | Configurator-Produkt-, Betreiber- und Kundeninstallationsdokumentation | +| Native Validierung, SKU-/Flavor-Prüfung und Accelerator-Release-Workflows | Configurator-Validierung, Modellqualifikation, Betreiber-Provisionierung und Dev-/Prod-Release-Workflows | +| Minimale native Quellpaketierung, Herkunfts- und Kompatibilitätsmetadaten | Runner-Paketierung/-Mirrors, Anwendungs-Quellkompatibilität, SaaS-Infrastruktur, Go-Installer und Kunden-Software-Releases | +| Künftiges optionales Private-Runner-VM-IaC und eigenständige Git-Beispiele, soweit als native Funktion umgesetzt | Optionaler Configurator-Adapter für diesen privaten Ausführungsweg | + +HCL-Adapter und anwendungsgeneriertes JSON bleiben Anwendungstools, die den nativen +Quellvertrag konsumieren. Der Accelerator importiert weder `@lzc/domain` noch +verlangt er eine App-Installation zur nativen Release-Erzeugung. Auch über ein +vermeintlich gemeinsames Paket kommt keine große App-Werkzeugkette hinzu. +Ein kleines generisches natives Manifest kann ohne Anwendungsimplementierung +veröffentlicht werden. + +Keine gepflegte Kopie nativer Module in einem Configurator-Fork. Ein verifizierter +Quellsnapshot im Release-Paket ist ein Build-Eingang, keine zweite bearbeitbare +Wahrheitsquelle. Die Anwendungspakete des Configurators bleiben zusammen; ein +drittes Shared-Code-Repository ist für die erste Trennung nicht erforderlich. + +## 3. Versionierte Abhängigkeit statt Nachbarverzeichnis + +Abhängigkeitsrichtung: Configurator → Accelerator. Ein unveränderliches natives +Paket enthält unterstützte Roots/Module, Referenzeingaben und ein Manifest mit +Quellrepository, ursprünglicher Revision, Paketprüfsumme und nativer +Vertragsversion. Benötigte native Assets oder authentifizierte Referenzen gehören +hinein; App-Code, Kunden-State, Zugangsdaten, `.terraform`-Verzeichnisse und +Configurator-Infrastruktur nicht. Interne Modulpfade bleiben zum nativen Checkout +konsistent. Lesbare Versionstags werden zu unveränderlichen Revisionen/Prüfsummen +aufgelöst und dokumentiert, nicht allein als Integritätsbeleg verwendet. + +Der Configurator deklariert exakt unterstützte Pakete und Engine-/Provider-/ +Laufzeitkompatibilität. Sein Build entpackt verifizierte Quellen an einen eigenen +Ort, generiert/prüft Eingabe- und Vorlagenkataloge über den Adapter und paketiert +das qualifizierte Material zur Ausführung. Tests erhalten einen ausdrücklichen +nativen Quellpfad statt `../../../src` oder der Git-Objektdatenbank des aktuellen +Repositorys. Übergangsweise ist ein separater Checkout einer gepinnten +Accelerator-SHA möglich. Unveränderliche Release-Pakete sind der vorgeschlagene +reguläre Release-Weg. + +```mermaid +flowchart LR + Native["Accelerator-Repository: native Quellen und Tests"] -->|"Verifiziertes versioniertes Paket"| Contract["Native Quellen / Vertrag / Herkunft"] + Contract -->|"Gepinnte unterstützte Versionen"| App["Configurator-Repository: App, Adapter, Runner, Installer"] + App --> Tests["Komponentenübergreifende Qualifikation"] + Tests -->|"Freigegebenes unveränderliches Paket"| Release["Configurator-SaaS / Kunden-Software-Release"] +``` + +Bestehende Ausführungsnachweise können mehrere historische native Roots und +Provider-Locks referenzieren. Diese Identitäten und Pakete erhalten. App- und +native Quellrevision werden nach Trennung getrennte Felder. Ein Configurator- +Commit darf nicht als Accelerator-Commit interpretiert werden. Nicht verfügbare +gepinnt-historische Quellen sperren die betroffene Operation, statt auf aktuelles +natives `main` zurückzufallen. + +## 4. Pipeline-Aufteilung und Integrationsprüfungen + +Heute bestehen elf YAML-Workflows. Vorgeschlagene Zuständigkeit: + +| Natives Repository: vier | Configurator-Repository: sieben | +| --- | --- | +| Validate | Validate Configurator | +| Validate STACKIT Flavors | Assistant live regression | +| Verify Deployment | Configurator Bootstrap | +| Publish Release | Configurator Platform | +| | Configurator Runtime | +| | Configurator Release | +| | Configurator Production Release | + +Dies ist eine Planungsübersicht, kein vollzogener Workflow-Umzug. Pfade, +Arbeitsverzeichnisse, Caches, native Quellbeschaffung und Veröffentlichungsprüfungen +anpassen. Jedes Repository bekommt einen eigenen korrekten Workflow-Katalog mit +Phasengrafik/Aktualitätsprüfung. Eine optionale Gesamtansicht benennt klar das +zuständige Repository. Native PRs starten nicht standardmäßig die gesamte +Anwendungs-Pipeline. + +Native CI verantwortet native Korrektheit. Configurator-CI verantwortet +Anwendungsverhalten und Kompatibilität mit deklarierten nativen Versionen: +Import-/Export-Roundtrips, Erhalt von Eingaben/Defaults, Kompilierung, +Quellprüfungen, gespeicherte Pläne, Upgrade/Recovery und betroffene Assistant- +Fakten. Eine kleine begrenzte Versionsmatrix wird explizit festgelegt; keine +unbegrenzte Zusage für alle historischen Versionen. + +Bei komponentenübergreifenden Änderungen beide PRs verknüpfen und die native +Kandidaten-SHA vor Zulassung mit dem Configurator prüfen. Tests mit Kandidatenquellen +sind isoliert und erhalten keine Deployment-/Kundenzugänge. Ein gemergtes/ +veröffentlichtes natives Release kann einen Abhängigkeits-Update-PR im Configurator +auslösen, der betroffene Kataloge regeneriert, passende Qualifikation durchläuft +und normal geprüft wird. Keine stille App-Abhängigkeitsänderung, kein automatisches +SaaS-Deployment oder Kunden-Landing-Zone-Upgrade. + +Eine eng begrenzte GitHub App kann bei Bedarf Update-PRs erzeugen oder Prüfungen +starten. Das gewöhnliche Workflow-`GITHUB_TOKEN` gilt nur im eigenen Repository. +Öffentliche native Pakete benötigen zum Lesen kein privilegiertes +repositoryübergreifendes Schreib-Token. Wiederverwendbare Workflows über +Repository-Grenzen sind möglich, müssen aber gepinnt und ausdrücklich zugelassen +sein. Sie schaffen weder gemeinsame Commit-Atomarität noch heben sie +Repository-Berechtigungsgrenzen auf. + +## 5. Releases und Updates + +Accelerator und Configurator veröffentlichen Releases im jeweiligen Repository +mit unabhängigen Versionsreihen. Das Configurator-/Installer-Kompatibilitätsmanifest +nennt unterstützte native Pakete, generiertes Schema, Engine, Provider-Locks, +Worker-Paket und App-Quellstand. Gleiche Versionsnummern beweisen keine +Kompatibilität. + +Ein reiner App-Fix kann seine native Abhängigkeit behalten. Neue native Funktionen +werden im Configurator erst nach Adapter-/Domain-/UI-/Runner-/Assistant-Anpassung +und Qualifikation zugelassen. Unterstützte Bestandskonfigurationen und +Bestellungen behalten exakte Ausführungstupel. Das Kundeninstallationsmodell im +[Softwarekonzept](../landing-zone-configurator/docs/customer-installation-concept.de.md) +trennt weiterhin Installationsupdates, Live-Katalogaktualisierung und explizite +Accelerator-/Vorlagen-/Workload-Upgrades mit frischem Plan/Apply. + +Native Nutzer beziehen Infrastruktur-Releases weiterhin direkt und installieren +für Fehlerkorrekturen keine App. Softwarekunden erhalten ein vollständiges +kompatibles Anwendungs-/Installer-Paket. Die laufende Instanz muss keine zwei +Repositories klonen oder Anbieter-CI erreichen. Getrennte Quellverantwortung +rechtfertigt keine unversionierten Laufzeitdownloads. + +Ein Repository-Wechsel allein verlangt weder Cloud-Ressourcenersatz noch Rotation +von Kunden-State-Schlüsseln oder Workload-State-Migration. Änderungen an +Quellformat, Schema oder Artefaktidentität benötigen eine ausdrückliche +Kompatibilitäts-/Migrationsentscheidung. Eine neue Major-Nummer allein löst das +nicht; auch nicht jeder alte Plan bleibt automatisch ausführbar. + +## 6. Heutige Kopplungen mit gezieltem Änderungsbedarf + +Die Sichtung zeigt folgende konkrete Migrationspunkte: + +- Adapterbefehle und Tests lesen native Variablen/Vorlagen über relative `src/`- + Pfade. Anwendungsskripte/-Fixtures und native Integrationsprüfungen teilen + denselben Checkout-Aufbau. +- Runner-Paketierung lädt gepinnte Accelerator-Commits und verwendet `git archive` + aus der aktuellen Repository-Objektdatenbank, einschließlich historischer + Application-Roots. +- Buildpack-Quell- und Produktions-Release-Prüfungen benennen + `stackitcloud/stackit-landing-zone` ausdrücklich und prüfen Workflow-/Ref-/Run- + Identität. +- Build-Artefakte, Attestierungen, geschützte Buildpack-Tags und Release-Metadaten + sind an Repository-/Quellidentität gebunden. Eine andere Checkout-URL genügt nicht. +- Configurator-CI startet heute bei nativen `src/**`-Änderungen. Dieser implizite + Integrationstrigger entfällt nach Auslagerung und braucht begrenzten Ersatz. +- Repository-Dokumentation, Assistant-Quellen, Links und Beitragsanleitung benötigen + zuständigkeitsgerechte Verweise. Native Anleitung darf nicht weiter App-Prüfungen + für gewöhnliche native Beiträge voraussetzen. + +Vertrauensverträge ausdrücklich aktualisieren. Neue App-Pakete müssen das neue +vertrauenswürdige Repository/Workflow und die nativen Paketidentitäten nachweisen. +Unterstützte alte Pakete behalten ursprüngliche Nachweise und Prüfung. Keine +beliebigen Repositories, Wildcard-Origins oder unsignierten Ersatzpakete zum +Vereinfachen des Übergangs zulassen. + +## 7. Migrationsreihenfolge und Betriebsübergang + +1. **Inventar/Ausgangswerte:** versionierte Inhalte, Abhängigkeiten, Workflows, + generierte Assets, offene PRs, Quell-Pins, Release-Tags, Secrets/Environments + und nötige historische Pakete klassifizieren. Umfang für native Nutzer messen. +2. **Im bisherigen Repository entkoppeln:** native Paket-/Quelleingänge und + getrennte App-/native Revisionen einführen; vorhandenes natives und + Anwendungsverhalten beweisen. Keine Kunden-Ressourcenadressen ändern. +3. **App auslagern:** neues Repository mit gewählter Historienstrategie, + Anwendungspaketen, App-Dokumentation und sieben Workflows erzeugen. + Urheberschaft/Lizenzhinweise und Quellen-/Herkunftszuordnung erhalten. + Repository-Schutz, CODEOWNERS, Reviews und Artefaktregeln einrichten. +4. **Betreibervertrauen neu aufbauen:** erforderliche Environments/Reviewer, + Variablen, begrenzte Zugänge, Runner-Zugriff, Tag-Regeln und Artefakt-/Signaturregeln + anlegen. Secrets aus geschützter Verwahrung erneut setzen oder bewusst rotieren; + GitHub-Secret-Werte sind kein gewöhnlicher Repository-Export. Keine Zugänge in + Issues, Quellen, Migrationslogs oder Kunden-Releases kopieren. +5. **Qualifizieren:** vollständiges Paket aus neuem Repository bauen, + Manifest-/Quell-Ablehnung und historische native Kompatibilität prüfen, + nötige lokale/CI-/Modellqualifikation durchführen. Danach ausdrücklich + autorisierten Dev-Übergang und Laufzeitprüfungen durchführen. Getesteten + Wiederherstellungsweg zum zuvor unterstützten Release vorbereiten. +6. **Genau einen Schreiber umschalten:** alte Configurator-Änderungswege deaktivieren, + bevor neue dieselbe Stage verwalten. Backend-Schlüssel, CF-App-/Routennamen, + Datenbanken und Infrastruktur-IDs erhalten. GitHub-Concurrency-Gruppen + koordinieren nicht repositoryübergreifend; genau einen aktiven Deployer plus + geprüftes State-/Deployment-Locking verwenden. Produktion wird separat geprüft + aktiviert. +7. **Natives HEAD verschlanken:** App-Baum/-Workflows und reine App-Abhängigkeiten/ + -Dokumentation aus dem nativen Arbeitsbaum entfernen. Benötigte native Helfer + und kurzen optionalen App-Link erhalten. Beide Workflow-Grafiken aktualisieren + und App-freie native Releases prüfen. Dokumentation und ausgewählte Issues/PRs + überleiten, ohne historische Herkunftsnachweise zu beschädigen. Vorübergehende + Doppelpflege beenden. + +Offene Änderungen vor Auslagerung koordinieren. Kurzes Übergangsfenster mit +Änderungsstopp oder abgestimmter Merge-Plan verhindert zwei gepflegte App-Kopien. +Der Repository-Umzug autorisiert keine gleichzeitige Umsetzung von +Kundenanmeldung, Installer oder privaten Runnern. Diese unabhängigen Vorhaben auf +stabile Versionsverträge aufsetzen. + +## 8. Git-Historie, Archive und tatsächliche Größe + +App-Verzeichnis aus neuen Commits entfernen verkleinert Arbeitsbaum und neu +zusammengestellte native Pakete. Blobs aus alten Commits/Tags verschwinden dadurch +nicht aus einem vollständigen Clone. Getrennt messen: aktueller nativer Quellbaum, +neue Release-/Archivgröße, flacher Checkout und vollständiger historischer Clone. + +Zunächst bestehende native Repository-Historie und unveränderliche Quellreferenzen +erhalten. Saubere native Release-Pakete und unterstützte Shallow-Checkout-Anleitung +für Nutzer ohne Historienbedarf anbieten. GitHubs automatisch erzeugte Archive +historischer Monorepo-Tags bleiben historische Archive und werden nicht als +bereinigte native Pakete umetikettiert. Dokumentierter neuer nativer Download +muss tatsächlich das native Paket wählen, kein altes Gesamt-Repository-Archiv. + +App-Historienextraktion/-Filterung kann andere Commit-IDs erzeugen. Ursprüngliche +und neue Herkunft sowie alte Release-Metadaten zuordnen statt vorhandene +Ausführungsnachweise umzuschreiben. Nicht voraussetzen, dass die neue App-Historie +alle für Runner-Paketierung benötigten historischen nativen Commits enthält. + +Wird später eine kleinere vollständige Remote-Historie gefordert, sind +Historienumschreibung/Repository-Ersatz und Legacy-Archivierung eine eigene +störende Migration mit ausdrücklicher Freigabe und vollständigem Referenz-/ +Aufbewahrungsplan. Das gehört nicht zur ersten Trennung und darf keine Pins von +gehostetem SaaS, Kunden oder alten nativen Modulen zerstören. Native Einfachheit +und schlanke reguläre Distribution sollen ohne erzwungene Historienumschreibung +entstehen. + +## 9. Aufwand, Risiken und Abnahme + +Vorläufige Einschätzung aus den gesichteten Kopplungen, kein abgeschlossenes +Migrationsaudit: etwa **10–20 technische Personentage** für produktionssichere +Trennung einschließlich Abhängigkeitspaketierung, CI-/Vertrauensänderungen, +Dokumentation, Kompatibilitätsprüfungen und Betriebsübergang. Rein mechanische +Dateiauslagerung kann 2–4 Tage dauern, ist aber keine Produktionsabnahme. +Review-Wartezeit, gehostete Build-/Deploy-Dauer, Organisationsberechtigungen und +unerwartete Kompatibilitätslücken können die Kalenderdauer verlängern. Neue +Installer-/Anmelde-/Private-Runner-Funktionen sind nicht enthalten. + +Die Abnahme muss zeigen: + +- Native Nutzer laden/klonen das schlanke aktuelle Produkt und führen dokumentierte + Init-/Validate-/Tests sowie Platform-/Application-CLI ohne Configurator-Setup aus. +- Neue native Pakete, Werkzeugvoraussetzungen und native CI enthalten keine reinen + App-Pakete/-Tests, Hosting- oder Release-Berechtigungen. Größenvergleich explizit + dokumentieren und HEAD von Historie trennen. +- Configurator reproduzierbar aus verifizierten nativen Paketen bauen; deklarierte + ältere Quellen-/Plan-/Recovery-Tupel bleiben unterstützt oder bekommen geprüfte + Migrationen. +- Komponentenübergreifende Änderungen erhalten Integrationsprüfungen und können + weder automatisch deployen noch ungeprüfte native Funktionen einführen. +- Gefälschte bzw. falsche Repository-Artefakte, Refs, Workflow-Identitäten und + geänderte Prüfsummen werden abgewiesen; Secrets/Änderungsrechte bleiben begrenzt. +- Dev-Übergang, Einzelschreiber, Produktionsfreigabe und Wiederherstellung werden + separat nachgewiesen. Native Ressourcenidentitäten und Kunden-State bleiben. +- Beide Repositories haben korrekte zweisprachige Dokumentation, Workflow-Zuständigkeit + und Versions-/Update-Anleitungen; das native README bleibt auf native Nutzer + ausgerichtet. + +Offen: endgültiger App-Repository-Name/Sichtbarkeit, Historienstrategie, +nativer Paketvertrag/Supportzeitraum, repositoryübergreifende +Automatisierungsidentität, Ablage optionalen eigenständigen Runner-IaC und +Cutover-Release. Das Hauptziel für Nutzer ist vereinbart; Umsetzung braucht eine +separate Beauftragung. + +## 10. Referenzen + +- [Native Architektur](architecture.de.md), [eigenständiger Einstieg](getting-started.de.md) und [zweiphasiger CLI-Ablauf](../src/application/README.de.md#independent-two-phase-cli-workflow). +- [Heutige Workflows](workflows.de.md), [Configurator-Entwicklung](../landing-zone-configurator/docs/development.de.md), [Runner-Paketierung](../landing-zone-configurator/deploy/runner/package.sh), [Buildpack-Vertrauen](../landing-zone-configurator/infra/ci/buildpack-source.mjs) und [Produktions-Quellprüfung](../landing-zone-configurator/infra/ci/production-release.mjs): Nachweise heutiger Kopplung, kein bereits migriertes Verhalten. +- [Kundeninstallationskonzept](../landing-zone-configurator/docs/customer-installation-concept.de.md) und [Private-Runner-Konzept](private-runner-concept.de.md): ergänzende Konzepte mit unabhängiger Umsetzung. +- [GitHub-Token-Umfang](https://docs.github.com/en/actions/concepts/security/github_token), [wiederverwendbare Workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations) und [Concurrency](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency): berücksichtigte Repository-Grenzen. diff --git a/docs/repository-separation-concept.md b/docs/repository-separation-concept.md new file mode 100644 index 0000000..153e36b --- /dev/null +++ b/docs/repository-separation-concept.md @@ -0,0 +1,277 @@ +# Accelerator and Configurator repository separation concept + +[English](repository-separation-concept.md) | [Deutsch](repository-separation-concept.de.md) + +Status: architecture proposal, 2026-11-16. The agreed primary motivation is a +smaller, clearer Accelerator for users who do not use the Configurator. This +concept does not move files, create repositories, change workflows or deploy +anything. Repository names and implementation sequence below are proposals. + +## 1. Consumer objective and success criteria + +The native Accelerator is a complete independently usable IaC product. Its normal +checkout, documentation, validation and releases should contain only what that +use needs. A user who chooses Terraform/OpenTofu should not have to navigate or +install the Configurator's web application, database migrations, Assistant, +browser tests, CF hosting, installer or SaaS deployment setup. + +The separation is therefore primarily a product simplification, not merely two +GitHub URLs. Preserve native inputs, module paths, state addresses, Platform/ +Application CLI operation and supported native helper tools. No Configurator +account, API, database, runtime, release permission or application dependency +becomes a prerequisite for native use. Optional references to the application +are short links to its own documentation. + +Acceptance measures the native tracked tree, source/release archive contents, +checkout/download footprint, required toolchain and CI scope. Compare these with +a recorded pre-split baseline. Do not claim a smaller full Git clone solely from +removing files at HEAD; historical objects need separate treatment (section 8). + +## 2. Proposed ownership boundary + +| Stays in `stackit-landing-zone` | Moves to a proposed `stackit-landing-zone-configurator` | +| --- | --- | +| Native `src/` roots/modules, reference tfvars, native provider constraints and required helpers | API/UI/worker, contracts/domain code, Assistant and application assets | +| Native module/configuration tests and native release/deployment verification | App/unit/database/browser/recovery integration suites and HCL adapter | +| Native architecture, getting-started, CLI/operations and module documentation | Configurator product, operator and customer-installation documentation | +| Native validation, SKU/flavor verification and Accelerator release workflows | Configurator validation, model qualification, operator provisioning and Dev/Prod release workflows | +| Minimal native source packaging, provenance and compatibility metadata | Runner packaging/mirrors, application source compatibility, SaaS infrastructure, Go installer and customer software releases | +| Future optional private-runner VM IaC and standalone Git examples, if delivered as native features | Optional Configurator adapter for that private execution path | + +The HCL adapter and app-generated JSON remain application tooling consuming the +native source contract. The Accelerator must not import `@lzc/domain`, require +app installation to produce a native release, or acquire a large app toolchain +through a supposedly shared package. A small generic native manifest can be +published without depending on application implementation. + +Do not duplicate native modules in a maintained Configurator fork. A verified +vendored source snapshot inside a release package is a build input, not another +editable source of truth. Keep the Configurator's application packages together; +a third shared-code repository is not required for the initial split. + +## 3. Versioned dependency instead of a neighboring directory + +The dependency direction is Configurator → Accelerator. Publish an immutable +native bundle containing the supported roots/modules, reference inputs and a +manifest with source repository, original revision, package digest and native +contract version. Include required native assets or authenticated references; +exclude app code, customer state, credentials, `.terraform` directories and +Configurator infrastructure. Keep internal module paths consistent with the +native checkout. Human version tags are resolved and recorded with immutable +revisions/digests, never treated as sufficient integrity evidence alone. + +The Configurator declares exact supported bundles plus engine/provider/runtime +compatibility. Its build extracts the selected verified source to a dedicated +location, generates/checks input and template catalogues through its adapter, +and packages the qualified material for execution. Tests take an explicit native +source directory rather than `../../../src` or the current repository's Git +object database. During transition, a separate checkout at a pinned Accelerator +SHA is an option; consuming immutable release bundles is the proposed normal +release path. + +```mermaid +flowchart LR + Native["Accelerator repository: native source and tests"] -->|"Verified versioned bundle"| Contract["Native source / contract / provenance"] + Contract -->|"Pinned supported versions"| App["Configurator repository: app, adapter, Runner, installer"] + App --> Tests["Cross-component qualification"] + Tests -->|"Approved immutable package"| Release["Configurator SaaS / customer software release"] +``` + +Existing execution records may refer to several historical native roots and +provider locks. Preserve those source identities and packages; the app source +revision and native source revision are distinct fields after the split. A +Configurator commit must not be interpreted as an Accelerator commit. Failure to +obtain a pinned historical source blocks the affected operation, not a fallback +to current native `main`. + +## 4. Pipeline split and integration checks + +There are currently eleven YAML workflows. The proposed ownership is: + +| Native repository: four | Configurator repository: seven | +| --- | --- | +| Validate | Validate Configurator | +| Validate STACKIT Flavors | Assistant live regression | +| Verify Deployment | Configurator Bootstrap | +| Publish Release | Configurator Platform | +| | Configurator Runtime | +| | Configurator Release | +| | Configurator Production Release | + +This is a planning inventory, not an implemented workflow move. Adapt paths, +working directories, caches, native source acquisition and publication guards. +Each repository gets its own accurate workflow catalogue/phase map and freshness +check; an optional combined presentation must clearly identify the owning repo. +Native PRs should not run the entire application pipeline by default. + +Native CI owns native correctness. Configurator CI owns application behavior and +compatibility with its declared native versions: import/export roundtrips, +input/default preservation, compilation, source guards, saved plans, upgrade/ +recovery and Assistant facts when affected. A small bounded supported-version +matrix is explicit; "all historical versions forever" is not a support promise. + +For cross-component changes, link the two PRs and test the candidate native SHA +against the Configurator before admitting it. Candidate-source tests are isolated +and receive no deployment/customer credentials. A merged/published native release +can open a Configurator dependency-update PR, which regenerates affected +catalogues, runs applicable qualification and gets normal review. It must not +silently change the app dependency, deploy SaaS or upgrade customer Landing Zones. + +A narrowly scoped GitHub App can create update PRs or dispatch checks when needed. +The workflow's ordinary `GITHUB_TOKEN` is repository-scoped. Public native bundle +reads need no privileged cross-repository write token. Cross-repository reusable +workflows are possible but must be pinned and explicitly permitted; they do not +restore same-commit atomicity or remove repository authorization boundaries. + +## 5. Release and update behavior + +Publish Accelerator and Configurator releases from their respective repositories +on independent version tracks. The Configurator/installer compatibility manifest +names supported native bundles, generated schema, engine, provider locks, worker +package and app source. Matching version numbers are not compatibility proof. + +An app-only fix can retain its native dependency. A new native capability is +available in the Configurator only after adapter/domain/UI/Runner/Assistant work +and qualification admit it. Old supported configurations and orders retain exact +execution tuples. The customer installation model in the [software concept](../landing-zone-configurator/docs/customer-installation-concept.md) +continues to distinguish installation updates, live catalogue refresh and +explicit Accelerator/template/workload upgrades with fresh Plan/Apply. + +Existing native users continue to consume native releases directly. They do not +install the app to receive infrastructure fixes. Software customers receive a +complete compatible application/installer package; their running instance does +not need to clone two repositories or access vendor CI. Independent source +ownership does not justify unversioned runtime downloads. + +Changing repository alone need not replace cloud resources, rotate customer state +keys or migrate workload state. Any source format, schema or artifact-identity +change requires an explicit compatibility/migration decision, not an automatic +major-version label or an assumption that every old plan remains executable. + +## 6. Current couplings that need deliberate work + +The inspected repository contains the following concrete migration points: + +- Adapter commands and tests read native variables/templates through relative + `src/` paths. Application scripts/fixtures and native integration checks share + the same checkout layout. +- Runner packaging fetches pinned Accelerator commits and uses `git archive` from + the current repository object database, including historical application roots. +- Buildpack-source and production-release guards name + `stackitcloud/stackit-landing-zone` explicitly and verify workflow/ref/run identity. +- Build artifacts, attestations, protected buildpack tags and release metadata + are tied to repository/source identity; changing a checkout URL is insufficient. +- Configurator CI currently triggers for native `src/**` changes. That implicit + integration trigger disappears after extraction and needs a bounded replacement. +- Repo documentation, assistant sources, links and contributor instructions need + ownership-aware references; native guidance must not keep listing app checks as + requirements for an ordinary native contribution. + +Update trust contracts explicitly. New app packages must prove the new trusted +repository/workflow and native bundle identities. Supported old packages keep +their original proofs and verification path; do not accept arbitrary repos, +wildcard origins or unsigned replacements to ease the cutover. + +## 7. Migration sequence and operating cutover + +1. **Inventory/baseline:** classify tracked content, dependencies, workflows, + generated assets, open PRs, source pins, release tags, secrets/environments and + required historical packages. Measure the standalone consumer footprint. +2. **Decouple in place:** introduce explicit native bundle/source inputs and + separate app/native revisions while still in the monorepo; prove existing + native and application behavior. No customer resource-address changes. +3. **Extract the app:** create the new repository with chosen history strategy, + application packages, app documentation and its seven workflows. Preserve + authorship/license notices and source/provenance mappings. Establish repository + protection, CODEOWNERS, reviews and artifact publication policies. +4. **Rebuild operator trust:** recreate required Environments/reviewers, variables, + scoped credentials, runner access, tag rules and artifact/signing policies. + Re-provision secrets from protected custody or rotate deliberately; GitHub + secret values are not an ordinary repository export. Do not copy credentials + into issues, source, migration logs or a customer release. +5. **Qualify:** build a complete new-repo package, prove manifest/source rejection + and historical native compatibility, run required local/CI/model qualification, + then perform an explicitly authorized Dev cutover and runtime checks. Prepare + tested recovery to the previously supported release. +6. **Switch one writer:** disable old Configurator mutation paths before allowing + new ones to manage the same stage. Preserve backend keys, CF app/route names, + databases and infrastructure IDs. Repository-local GitHub concurrency groups + do not coordinate across repos; use a single active deployer plus verified + state/deployment locking. Production is a separate reviewed activation. +7. **Slim the native HEAD:** remove the app tree/workflows and app-only dependency/ + documentation from the native working tree, retain native-required helpers and + a short optional app link. Update both workflow maps and verify native releases + exclude application payload. Redirect documentation and selected issues/PRs + without breaking historical provenance. End the temporary dual-maintenance lane. + +Coordinate open changes before extraction; a short cutover freeze or coordinated +merge plan avoids maintaining two application copies. The repository move is not +permission to implement customer authentication, installer or private runners at +the same time. Stage these independent projects against stable version contracts. + +## 8. Git history, archives and actual size + +Removing the app directory from new commits makes the working tree and newly +selected native bundles smaller. It does not remove blobs reachable through old +commits/tags from a complete clone. Record these as separate measurements: +current native source size, new release/archive size, shallow checkout and full +historical clone size. + +Initially preserve the existing native repository history and immutable source +references. Offer clean native release bundles and supported shallow checkout +instructions for users who do not need history. GitHub's automatically generated +archives for historical monorepo tags remain historical archives; do not relabel +them as cleaned native-only packages. Ensure the documented new native download +actually selects the native bundle instead of a legacy whole-repository archive. + +An app history extraction/filter can create different commit IDs; preserve +original-to-new provenance and old release metadata instead of rewriting existing +execution records. Do not assume the migrated app's Git history contains every +historical native commit needed by Runner packaging. + +If reducing the original remote's full historical storage later becomes a +requirement, treat history rewriting/repository replacement and legacy archival +as a separate disruptive migration requiring explicit approval and a complete +reference/retention plan. It is not part of the initial split and must not destroy +pins needed by deployed SaaS, customers or old native modules. Native simplicity +and lean normal distribution should be delivered without forcing this rewrite. + +## 9. Effort, risks and acceptance + +Preliminary estimate based on the inspected couplings, not a completed migration +audit: roughly **10–20 engineering person-days** for a production-safe split, +including dependency packaging, CI/trust changes, documentation, compatibility +checks and operating cutover. Mechanical file extraction alone might take 2–4 +days but is not production acceptance. Review queues, hosted build/deploy time, +organization permissions and unexpected compatibility gaps may extend elapsed +time. New installer/authentication/private-runner features are excluded. + +Acceptance must prove: + +- A native user downloads/clones the slim current product and performs documented + init/validate/tests and Platform/Application CLI use without Configurator setup. +- New native bundles, native tool requirements and native CI exclude app-only + packages, tests, hosting and release permissions; the footprint comparison is + explicit and separates HEAD from history. +- Configurator builds reproducibly from verified native bundles; declared older + source/plan/recovery tuples remain supported or have reviewed migrations. +- Cross-component changes get integration checks and cannot auto-deploy or + introduce unreviewed native capabilities. +- Forged/wrong-repository artifacts, refs, workflow identities and altered digests + are rejected; secrets and mutation rights remain scoped. +- Dev cutover, single-writer behavior, production approval and recovery are + independently evidenced; native resource identities and customer state stay put. +- Both repositories have truthful bilingual docs, workflow ownership and supported + version/update instructions; the remaining native README is native-first. + +Decisions still needed: final app repository name/visibility, history preservation +strategy, native bundle contract/support window, cross-repo automation identity, +where optional standalone runner IaC lives and which release performs cutover. +The primary consumer goal is agreed; implementation authorization is separate. + +## 10. References + +- [Native architecture](architecture.md), [standalone getting started](getting-started.md) and [two-phase CLI workflow](../src/application/README.md#independent-two-phase-cli-workflow). +- [Current workflow inventory](workflows.md), [Configurator development](../landing-zone-configurator/docs/development.md), [Runner packaging](../landing-zone-configurator/deploy/runner/package.sh), [buildpack trust](../landing-zone-configurator/infra/ci/buildpack-source.mjs) and [production source validation](../landing-zone-configurator/infra/ci/production-release.mjs): current coupling evidence, not already migrated behavior. +- [Customer-installed software concept](../landing-zone-configurator/docs/customer-installation-concept.md) and [private runner concept](private-runner-concept.md): complementary concepts with independent implementation work. +- [GitHub token scope](https://docs.github.com/en/actions/concepts/security/github_token), [reusable workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/reusing-workflow-configurations) and [concurrency](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency): repository boundaries considered in this proposal. diff --git a/landing-zone-configurator/docs/architecture.de.md b/landing-zone-configurator/docs/architecture.de.md index 2171c95..8cdd312 100644 --- a/landing-zone-configurator/docs/architecture.de.md +++ b/landing-zone-configurator/docs/architecture.de.md @@ -4,6 +4,8 @@ [English](architecture.md) | [Deutsch](architecture.de.md) +Das vorgeschlagene [Repository-Trennungskonzept](../../docs/repository-separation-concept.de.md) priorisiert einen schlanken nativen Accelerator. Der Configurator würde native Releases als geprüfte versionierte Abhängigkeit konsumieren; der Umzug ist nicht umgesetzt. + Die vorgeschlagene [Kundeninstallation als Software](customer-installation-concept.de.md) beschreibt Bootstrap, lokale Passkeys/optionales Firmen-SSO und delegierte Cloud-Ausführung getrennt von der heutigen gehosteten Betriebsart. Sie ist noch nicht implementiert. Der vorgeschlagene [private Ausführungsweg über STACKIT Git und VM-Runner](../../docs/private-runner-concept.de.md) ist separat dokumentiert. Der Configurator würde als optionaler Auftraggeber dieselben Kundenpipelines nutzen; dies ersetzt die hier beschriebene CF-Ausführung noch nicht. diff --git a/landing-zone-configurator/docs/architecture.md b/landing-zone-configurator/docs/architecture.md index d1bc5f4..0250f41 100644 --- a/landing-zone-configurator/docs/architecture.md +++ b/landing-zone-configurator/docs/architecture.md @@ -3,6 +3,8 @@ [English](architecture.md) | [Deutsch](architecture.de.md) +The proposed [repository separation](../../docs/repository-separation-concept.md) prioritizes a slim native Accelerator. The Configurator would consume native releases as verified versioned dependencies; the move is not implemented. + The proposed [customer-installed software profile](customer-installation-concept.md) describes bootstrap, local passkeys/optional corporate SSO and delegated cloud execution separately from the current hosted mode. It is not implemented. The proposed [private execution path using STACKIT Git and VM runners](../../docs/private-runner-concept.md) is documented separately. The Configurator would optionally submit to the same customer pipelines; this does not yet replace the CF execution described here.