--- title: "Spring Boot mit Terraform von der VM auf Kubernetes umstellen" description: "Dasselbe Spring-Boot-JAR auf STACKIT Kubernetes betreiben: mit PostgreSQL Flex, Gateway API, DNS, Managed Telemetry sowie geprobtem Daten-Cutover und Rollback." scfAsset: managed: false category: "runbook" external: false tags: ["design-and-mobilize", "use-cases", "runnable-example", "replatform", "kubernetes", "terraform", "ske", "spring-boot", "postgresql"] maintainers: - user: "lukas.weberruss" role: true website: true source_url: "https://framework.stackit.cloud/de/migration/assetcontainer/stackit/replatform-automation-spring-boot-vm-to-kubernetes-terraform/" source_file: "docs/de/migration/assetcontainer/stackit/replatform-automation-spring-boot-vm-to-kubernetes-terraform.mdx" --- ## Überblick Dieses Asset wendet das Migration Framework auf ein Replatform von Spring Boot und PostgreSQL an: Die Anwendung wechselt vom VM-Service zu STACKIT Kubernetes Engine (SKE), die Datenbank von selbstverwaltetem PostgreSQL zu STACKIT PostgreSQL Flex. Geschäftsfunktion und Anwendungs-JAR bleiben unverändert; die Betriebsmodelle für Laufzeit und Datenbank ändern sich. ## Referenzimplementierung Das Referenzrepository ist die maßgebliche Quelle für Terraform, Helm-Charts, fest versionierte Artefakte, Migrationsskripte und Validierung. Verwenden Sie einen geprüften Stand mit den hier beschriebenen Gateway-API- und `scripts/migrate_postgres.py`-Workflows. Ein älterer Stand mit direktem Datenbank-Import-Job implementiert dieses Verfahren nicht. ## Replatform-Scope in diesem Asset - **Laufzeit**: Dasselbe Spring-Music-JAR mit Spring Boot 2.4.0 läuft auf Java 11 in einem Kubernetes-Deployment statt unter systemd. - **Daten**: PostgreSQL Flex stellt getrennte Anwendungs- und Probedatenbanken bereit; JDBC- und Migrationsclients benötigen TLS. - **Netzwerkverkehr**: Envoy Gateway, Gateway API HTTPRoutes und SKE-verwaltetes ExternalDNS ersetzen den VM-Endpunkt. - **Betrieb**: Kubernetes-Zustands- und Ressourcenkontrollen ersetzen das Host-Service-Management; Managed Telemetry erfasst Cluster-, Anwendungs- und Datenbanksignale. - **Migration**: Quellnachweise, isolierte Probe, explizit freigegebener Cutover und verifizierter Datenbank-Rollback bleiben von der Infrastrukturbereitstellung getrennt. Cloud Foundry, Object Storage, die Zerlegung in Microservices und Anwendungsmodernisierung sind nicht Teil dieser Implementierung. Die alte Beispielanwendung demonstriert einen Plattformwechsel; sie ist keine Empfehlung, einen nicht mehr unterstützten Anwendungsstack produktiv einzusetzen. ## Architekturdiagramm der Referenz Prüfen Sie das Architektur-Asset vor der Wahl von Kapazität und Netzwerkkontrollen. Es trennt die implementierte Topologie von Produktionserweiterungen wie öffentlichem HTTPS, hochverfügbaren Workern und geschützten Metriken. ## End-to-End-Ablauf 1. Replatform-Eignung, Quellkompatibilität, Landing-Zone-Bereitschaft und Verantwortlichkeiten bestätigen. 2. Einen vertrauenswürdigen PostgreSQL-Dump und ein Integritätsmanifest unabhängig vom Ziel vorbereiten. 3. Terraform für SKE, PostgreSQL Flex, Gateway, DNS, Workload und Observability prüfen und anwenden. 4. Das Ziel validieren und den finalen Quelldump in der isolierten Probedatenbank testen. 5. Quellschreibzugriffe einfrieren, Ausfallzeit freigeben und den kontrollierten Cutover mit geschütztem Zielbackup ausführen. 6. Anwendungs- und Datennachweise abnehmen oder den Zielzustand vor dem Cutover wiederherstellen; den Client-Traffic nach dem freigegebenen Betreiberverfahren umschalten. 7. Nachweise während der Stabilisierung aufbewahren und repräsentative Telemetrie für spätere Optimierung nutzen. ## Arbeitsumgebung für den Walkthrough vorbereiten Verwenden Sie eine isolierte Linux-Laborumgebung mit Git, Terraform, kubectl, curl, jq, getent, Python ab Version 3.11 sowie PostgreSQL-Server- und Client-Werkzeugen. Die Rehost-Beispielskripte benötigen außerdem `runuser`, `sha256sum`, ein Betriebssystemkonto `postgres` und Root-Rechte, um eine temporäre lokale Datenbank zu erstellen und zu prüfen. Führen Sie die Beispielbefehle in dieser vorbereiteten Laborumgebung aus, nicht auf einem produktiven Datenbankhost. Die privaten Artefakte müssen für den Migrationsbediener lesbar bleiben; machen Sie sie nicht für alle Benutzer lesbar. Beziehen Sie geprüfte Commit-IDs beider Repositorys vom Referenz-Maintainer und exportieren Sie diese vorab als `REHOST_REVISION` und `REPLATFORM_REVISION`. Der Replatform-Stand muss Gateway API und den freigabegesteuerten Migrationsworkflow enthalten. Setzen Sie nicht voraus, dass der Remote-Standardbranch bereits die lokal getestete Implementierung enthält. Ist der freigegebene Stand nicht verfügbar, beschaffen Sie ihn vor dem Walkthrough. Ersetzen Sie beide Platzhalter durch die freigegebenen vollständigen Commit-IDs mit jeweils 40 Zeichen und setzen Sie diese im selben Bash-Terminal: ```bash export REHOST_REVISION="REPLACE_WITH_REVIEWED_REHOST_COMMIT_ID" export REPLATFORM_REVISION="REPLACE_WITH_REVIEWED_REPLATFORM_COMMIT_ID" ``` Führen Sie den folgenden Block vollständig aus einem leeren Arbeitsverzeichnis aus. Die `if`-Prüfung lehnt fehlende, leere oder falsch formatierte IDs einschließlich unveränderter Platzhalter ab. Jedes `&&` führt den nächsten Befehl nur nach Erfolg des vorherigen aus. Git prüft die Verfügbarkeit der Commits; die Formatprüfung allein bestätigt weder Freigabe noch Repository-Inhalt. ```bash if [[ ! ${REHOST_REVISION:-} =~ ^[0-9a-fA-F]{40}$ || ! ${REPLATFORM_REVISION:-} =~ ^[0-9a-fA-F]{40}$ ]]; then printf '%s\n' "Set both revision variables to reviewed full 40-character commit IDs." >&2 false else umask 077 && git clone https://github.com/stackitcloud/stackit-cmf-Rehost-springboot.git && git clone https://github.com/stackitcloud/stackit-cmf-replatform-springboot-k8s.git && git -C stackit-cmf-Rehost-springboot checkout --detach "$REHOST_REVISION" && git -C stackit-cmf-replatform-springboot-k8s checkout --detach "$REPLATFORM_REVISION" && test -f stackit-cmf-replatform-springboot-k8s/scripts/migrate_postgres.py && test -f stackit-cmf-replatform-springboot-k8s/scripts/validate_gateway.sh && cd stackit-cmf-replatform-springboot-k8s && printf '%s\n' "Workspace ready. Continue from this Replatform checkout." || { printf '%s\n' "Preparation failed. Resolve the error before continuing." >&2 false } fi ``` Fahren Sie erst nach der Meldung `Workspace ready` fort. Bei Fehlern bleibt das Terminal offen; weitere Vorbereitungsbefehle werden übersprungen. Vorhandene oder teilweise geklonte Verzeichnisse werden weder entfernt noch überschrieben: Prüfen Sie diese und bewahren Sie lokale Änderungen, bevor Sie es in einem neuen leeren Arbeitsverzeichnis erneut versuchen. Nach Erfolg befindet sich das Terminal für die nächsten Schritte im Replatform-Checkout. Nutzen Sie ein freigegebenes STACKIT Projekt, einen Service Account, DNS-Delegation, SKE-Kapazität und ein geschütztes Terraform-Backend. Beziehen Sie Zugangsdaten über den freigegebenen Secret-Kanal, niemals aus diesem Trail. Die folgenden Befehle setzen diese Verzeichnisstruktur und eine geprüfte Konfiguration voraus; sie belegen keinen validierten Greenfield-Produktionsaufbau. ## Quellnachweise vorbereiten Qualifizieren Sie einen konsistenten Quelldump und sein Manifest, bevor Daten in den Migrationsworkflow eingehen. Die Rehost-Referenz liefert `scripts/create_source_dump.sh` und `scripts/validate_source_dump.sh` für ihr reproduzierbares Beispiel. Führen Sie diese im Rehost-Repository aus. Dessen Verzeichnis `artifacts` liefert `source-postgresql.dump` und `source-postgresql.manifest` an den Replatform-Workflow. Das Manifest erfasst Version 1, `table=public.album`, `row_count`, `album_fingerprint` und `dump_sha256`. Führen Sie ausschließlich für das reproduzierbare Beispiel die folgenden Befehle vom Replatform-Checkout in der vorbereiteten Laborumgebung aus. Die Skripte erstellen aus dem versionierten Beispiel-SQL eine temporäre PostgreSQL-Instanz, exportieren sie und führen einen unabhängigen Test-Restore aus. Verwenden Sie ein frisches Artefaktverzeichnis; überschreiben Sie keine Nachweise einer bereits laufenden Migration. ```bash umask 077 pushd ../stackit-cmf-Rehost-springboot bash scripts/create_source_dump.sh bash scripts/validate_source_dump.sh popd ``` Erwartet wird eine erfolgreiche Validierung von acht Zeilen mit passendem Fingerprint. Diese Befehle lesen keine Quell-VM aus. Verwenden Sie für Probe und Cutover genau diese Artefakte weiter. Ersetzen Sie für eine reale Quelle den Beispielgenerator durch ein freigegebenes Exportverfahren: Frieren Sie alle Schreibzugriffe ein und leiten Sie Dump im Custom-Format und Manifest aus demselben konsistenten Quellsnapshot ab. Das generierte Beispiel mit acht Alben ist kein Export einer beliebigen laufenden VM. Prüfen Sie vor dem Export PostgreSQL-Kompatibilität, Erweiterungen, Eigentümerschaft und Schemaabhängigkeiten. Stellen Sie nur vertrauenswürdige Dumps wieder her, da sie SQL ausführen. Diese Implementierung migriert das Anwendungsschema `public` und prüft `public.album`; von Flex verwaltete Schemas sind bewusst ausgeschlossen. Andere Workloads benötigen eigene Invarianten und einen angepassten Schemaumfang. ## Ziel bereitstellen Stellen Sie das Ziel aus einem geprüften Plan mit expliziten Angaben zu Projekt, Kapazität, Zugriff und DNS bereit. Verwenden Sie Terraform, kubectl, curl, jq, getent und Python ab Version 3.11 unter Linux. Kopieren Sie `env.tfvars.example` nach `env.tfvars` und passen Sie die tatsächlichen Variablen dieser Datei an. Behalten Sie die getestete Provider-Lockdatei und unveränderliche Image- und JAR-Referenzen bei. Bestätigen Sie vor dem Plan die Verfügbarkeit der SKE-Version, Node-Pool-Kapazität, Projektberechtigungen und DNS-Delegation. > Aus der STACKIT-Doku: [Lifecycle of Kubernetes Engine › Kubernetes end-of-life dates](https://docs.stackit.cloud/de/products/runtime/kubernetes-engine/reference/lifecycle/#kubernetes-end-of-life-dates) (Stand der Quelle 24.08.2026, übernommen 05.10.2026) Starting with Kubernetes v1.33, we remove minor versions on the [patch day](https://docs.stackit.cloud/de/products/runtime/kubernetes-engine/reference/lifecycle/#operating-system-patch-days) that precedes the upstream maintenance end-of-life (EOL) date. The following table below lists the upstream EOL date for each Kubernetes minor version and the corresponding expiration date in SKE: | Kubernetes minor version | End-of-life date | Expiration in SKE | | --- | --- | --- | | v1.32 | 2026-02-28 | 2026-04-15 | | v1.33 | 2026-06-28 | 2026-06-10 | | v1.34 | 2026-10-27 | 2026-10-14 | | v1.35 | 2027-02-28 | 2027-02-10 | Please refer to the official Kubernetes Release History for up-to-date announcements of new versions. Bevorzugen Sie ein freigegebenes Application-Landing-Zone-Projekt. Setzen Sie `create_project = false` und geben Sie Projekt-ID und Pfad zum Service-Account-Schlüssel an. Die alternative Projekterstellung setzt einen freigegebenen übergeordneten Container und Berechtigungen voraus; sie ersetzt keine Landing-Zone-Governance. Zugangsdaten, State, gespeicherte Pläne und Migrationsnachweise gehören nie in die Versionsverwaltung. Erstellen Sie für einen neuen Checkout die private Variablendatei, ohne eine vorhandene zu überschreiben: ```bash umask 077 test -e env.tfvars || cp env.tfvars.example env.tfvars chmod 600 env.tfvars ``` Bearbeiten Sie diese Datei vor dem Plan: Tragen Sie freigegebenes Projekt und Service-Account-Pfad, Region, unterstützte SKE-Version, verfügbaren Node-Pool-Flavor samt Zone und delegierte DNS-Einstellungen aus dem Repository-Beispiel ein. Prüfen Sie Backend-Zugriff und Sperren, Quotas, Kosten sowie die Grenzen von HTTP und öffentlichen Metriken. Die folgenden Funktionsschalter bilden keine vollständige Umgebungskonfiguration. ## Einheitliche Automatisierungs-Flags Der optionale gemeinsame Wrapper bildet `setup_project`, `setup_observability`, `setup_database`, `setup_workload`, `setup_loadgen` und `setup_dns` auf die Terraform-Schalter des Repositorys ab. Sie wählen ausschließlich den Bereitstellungsumfang: Das Aktivieren der Datenbank erlaubt keinen Datenaustausch und ersetzt niemals die separate Migrationsfreigabe. ## Minimale Zielkonfiguration Diese Werte aktivieren den vollständigen Workload- und Datenbankpfad. Sie ergänzen die Angaben zu Projekt, Region, Node Pool und DNS im Repository-Beispiel, ersetzen sie aber nicht. ```hcl deploy_workload = true dns_enabled = true enable_postgres_flex = true postgres_flex_target_database = "springmusic" postgres_flex_target_app_acl_cidrs = [] observability_enabled = true create_observability_instance = true create_grafana_dashboard = true enable_springboot_hpa = false enable_load_generator = false deploy_postgres_migration_job = false ``` Lassen Sie HPA und Lastgenerierung während der Migration deaktiviert. Wählen Sie Alarmeinstellungen bewusst; die Alarmzustellung wurde im End-to-End-Test nicht validiert. `springboot_image` wählt die Java-Laufzeit, nicht ein beliebiges vorgefertigtes Anwendungsimage. Der Init-Container lädt das auf einen Commit fixierte Rehost-JAR und prüft vor dem Start seinen SHA-256-Wert. Spiegeln Sie unveränderliche Artefakte für die Produktion in freigegebene Artefakt- und Image-Dienste. Führen Sie die Befehle im Replatform-Repository aus und prüfen Sie den gespeicherten Plan vor dem Apply: ```bash umask 077 terraform init terraform validate terraform plan -var-file=env.tfvars -out=tfplan terraform apply tfplan bash scripts/validate_gateway.sh ``` ## Zugriffskontrolle und temporäre ACL-Erweiterung für Migration Bei leeren Anwendungs-ACL-Eingaben verwendet Terraform die tatsächlichen Egress-CIDRs des SKE-Clusters für PostgreSQL Flex. Explizite Anwendungs- oder ältere ACL-Werte überschreiben diesen Standard und müssen geprüft werden. Erlauben Sie nicht `0.0.0.0/0`. Der temporäre PostgreSQL-Client läuft in SKE und erhält den Dump über kubectl. Er verbindet sich nicht direkt mit der Quell-VM; weder Quell- noch Arbeitsplatz-CIDRs benötigen temporären Flex-Zugriff. JDBC und Datenbankwerkzeuge verwenden `sslmode=require`: Das erzwingt Verschlüsselung, bietet aber nicht die Hostnamenprüfung von `verify-full`. Schützen Sie Zugangsdaten in Kubernetes Secrets und im Terraform-Backend und validieren Sie bei Bedarf eine stärkere Zertifikatsprüfung. ## Migration proben Stellen Sie den finalen Dump in der isolierten Probedatenbank wieder her und verlangen Sie passende Nachweise, die jünger als 24 Stunden sind. Führen Sie nach dem Infrastruktur-Apply einen isolierten Restore in `springmusic_rehearsal` aus. Passen Sie das Quellverzeichnis an die freigegebenen Artefakte an und halten Sie den Nachweispfad privat. ```bash python3 scripts/migrate_postgres.py rehearse \ --artifacts ../stackit-cmf-Rehost-springboot/artifacts \ --evidence .tmp/migration-run ``` Die Probe validiert Manifest, Dump-Prüfsumme, Zielidentität, Zeilenanzahl und Fingerprint, ohne die Anwendungsdatenbank zu ersetzen. Proben Sie nach dem Schreibstopp auf der Quelle erneut mit dem finalen Dump. Der Cutover verlangt passende Nachweise, die jünger als 24 Stunden sind. Eine erfolgreiche Probe mit einem älteren oder anderen Dump gibt die finale Eingabe nicht frei. ## Option: VM-PostgreSQL nach PostgreSQL Flex migrieren Der alte Pfad `deploy_postgres_migration_job = true` wird durch die Validierung gesperrt. Nutzen Sie stattdessen den freigabegesteuerten Workflow. Stoppen Sie HPA, Lastgenerierung und alle anderen Zielschreiber. Pausieren Sie Terraform- und GitOps-Reconciliation, solange das Skript die Replikazahl steuert. Seine lokale Sperre schützt nur einen Checkout, nicht vor gleichzeitigen Bedienern auf unterschiedlichen Rechnern. ```bash python3 scripts/migrate_postgres.py cutover \ --artifacts ../stackit-cmf-Rehost-springboot/artifacts \ --evidence .tmp/migration-run \ --source-write-frozen --confirm-target springmusic ``` Das Quellschreibstopp-Flag ist eine Bestätigung des Betreibers, keine automatische Abschaltung der Quelle. Der Cutover skaliert die Anwendung auf null, sichert das Ziel vor dem Cutover und prüft die Sicherung per Prüfsumme. Er weist ihre Wiederherstellbarkeit in der Probedatenbank nach und stellt erst dann die Quelle transaktional wieder her. Vor dem Wiederanlauf mit ursprünglicher Replikazahl werden die Daten geprüft. Bei Fehlern bleibt die Anwendung zur Untersuchung gestoppt. Bewahren Sie Nachweisjournal und Backup auf; überschreiben Sie sie nicht für einen erneuten Versuch. ## Validieren und zurückrollen Vergleichen Sie Datenbanknachweise mit dem Quellmanifest, prüfen Sie das Anwendungsverhalten über das Gateway und bestätigen Sie den Zustand beider Metrik-Jobs. Traffic-Umschaltung und fachliche Abnahme bleiben Betreiberaufgaben; das Skript ändert den Endpunkt der Quellanwendung nicht. So stellen Sie die geschützte Zieldatenbank aus der Zeit vor dem Cutover wieder her: ```bash python3 scripts/migrate_postgres.py rollback \ --evidence .tmp/migration-run --confirm-target springmusic ``` Der Rollback prüft Zielidentität und Backup-Integrität, sichert das aktuelle Ziel separat, stellt die ursprünglichen Daten wieder her und verifiziert vor dem Wiederanlauf deren Fingerprint. Schreibzugriffe nach dem Cutover werden nicht zusammengeführt; bewahren Sie den Dump vor dem Rollback für einen expliziten Abgleich auf. Dies ist ein Zieldatenbank-Rollback, kein automatischer Failback zur Quell-VM. ## Datenbank-Metriken in Observability sichtbar machen Terraform verwaltet den Grafana-Ordner `SCF Replatform` und das Dashboard mit acht Panels an der vorhandenen Datenquelle `Thanos`. Öffnen Sie es über `grafana_dashboard_url`. Cluster-CPU, Cluster-Speicher, laufende Pods, Anwendungsanfragen sowie PostgreSQL-Zustand und -Auslastung unterstützen Abnahme und spätere Optimierung. Ein manueller Dashboard-Import ist nicht nötig. Anwendungsmetriken stammen aus dem pod-lokalen Boot-2-Actuator über den Metrikadapter auf Port 9090; der PostgreSQL-Exporter nutzt Port 9187. Prüfen Sie beide tatsächlichen Scrape-Ergebnisse, nicht nur die Dashboard-Darstellung. Fehlende Telemetrie ist ein Untersuchungsgrund, niemals der Nachweis fehlender Last. ## Validierung mit kubectl Exportieren Sie eine kurzlebige Kubeconfig mit privaten Berechtigungen und prüfen Sie den Standard-Namespace der Referenz: ```bash umask 077 mkdir -p .tmp terraform output -raw kubeconfig > .tmp/replatform.kubeconfig export KUBECONFIG="$PWD/.tmp/replatform.kubeconfig" kubectl get deploy,svc,pods -n springboot kubectl get gateway,httproute -n springboot kubectl rollout status deployment/springboot -n springboot bash scripts/validate_gateway.sh ``` Der Gateway-Validator prüft Akzeptanz, aufgelöste Routenreferenzen, DNS und Anwendungsantwort. Entfernen Sie die lokale Kubeconfig nach Gebrauch und beziehen Sie nach Ablauf eine neue. Ein erfolgreicher Rollout allein ist keine Daten- oder fachliche Abnahme. ## Grenze zwischen Backup und Recovery Trennen Sie Migrations-Rollback von Flex-Service-Recovery und bewahren Sie geschützte Nachweise außerhalb kurzlebiger Ausführungsumgebungen auf. Die Flex-Aufbewahrung wird explizit konfiguriert; der Standard dieser Referenz beträgt 32 Tage. Managed-Datenbankbackups und der Migrationsdump vor dem Cutover dienen unterschiedlichen Zwecken. Die Probe mit Letzterem weist weder Managed-Service-Restore noch Point-in-Time-Recovery oder Disaster Recovery der Anwendung nach. Benennen Sie Recovery-Verantwortliche und testen Sie den benötigten Service-Recovery-Pfad separat. Bewahren Sie geschützte Nachweise und Backups bis zum Ende des Rollback-Fensters außerhalb eines kurzlebigen Dev Containers auf. Prüfen Sie nach einem abgebrochenen Migrationsprozess verbliebene Pods mit Präfix `springmusic-migration-*`, bevor Sie fortfahren; starten Sie ein ungeprüftes Ziel nicht durch Terraform neu. ## Was dieses Asset zeigt Dieses Asset zeigt, wie das Anwendungsverhalten beim Wechsel der Betriebsmodelle für Laufzeit und Datenbank erhalten bleibt: - **Plattformwechsel**: Dasselbe Spring-Boot-JAR auf SKE betreiben, über TLS mit PostgreSQL Flex verbinden und über Gateway API und DNS erreichbar machen. - **Kontrollierte Datenmigration**: Quelldump und Manifest qualifizieren, einen isolierten Restore proben und vor dem Cutover eine explizite Freigabe sowie ein verifiziertes Zielbackup verlangen. Bei erforderlichem Rollback den Zielzustand vor dem Cutover wiederherstellen. - **Unabhängige Validierung**: Datenintegrität, Anwendungsantworten, Gateway- und DNS-Bereitschaft sowie tatsächliche Scrape-Ergebnisse prüfen. Den Terraform-Plan auf unerklärte Drift prüfen, statt erfolgreiche Bereitstellung als Migrationsabnahme zu behandeln. - **Wiederholbare Observability**: Observability-Integration und Grafana-Dashboard mit acht Panels durch Terraform verwalten. Anwendungs- und Datenbanksignale für Abnahme, Stabilisierung und spätere Optimierung nutzen. ## Nicht abgedeckt Diese Nachweise bestätigen weder einen vollständigen Greenfield-Durchlauf noch eine Migration aus einer produktiven Live-Quelle, unterbrechungsfreien Betrieb, Hochverfügbarkeit, öffentliches Gateway-TLS, interaktiven IDP-Login, Alarmzustellung oder Managed-Flex-Recovery. Der getestete Ein-Worker-Aufbau mit HTTP stellt Metriken ohne Authentifizierung bereit; erfüllen Sie die Produktionsanforderungen vor der Verwendung sensibler Daten. Aktualisieren Sie die Beispielanwendung und validieren Sie eine geeignete unterstützte Kubernetes-Version als separate kontrollierte Änderungen.