Upgrade Guide 3.0 → 3.1

Dieser Leitfaden beschreibt den Wechsel einer bestehenden UDSP-Installation von 3.0 auf 3.1. Er ergänzt den allgemeinen Prozess unter Plattform aktualisieren. Führen Sie das Upgrade zuerst in Staging durch und übernehmen Sie anschließend den abgenommenen Stand nach Produktion.

Die Reihenfolge ist relevant: Zunächst werden Inventory und Gateway API migriert, danach PostgreSQL-Operator und Keycloak aktualisiert. Das erste vollständige Deployment erfolgt mit deaktivierter Harbor-Integration. Falls Harbor eingesetzt wird, werden vor dem zweiten Deployment die Registry-Zugänge vorbereitet. Nicht mehr benötigte Komponenten werden zuletzt entfernt.

Beispiele an die eigene Umgebung anpassen

Domains unter example.org und Werte in spitzen Klammern sind Platzhalter. Ersetzen Sie diese durch Ihre freigegebenen Hostnamen, Inventory-Dateien und Zugangsdaten. YAML-Ausschnitte sind Ergänzungen vorhandener Blöcke; ersetzen Sie damit keine vollständigen Inventories oder Mandantenlisten. Geheimnisse beziehen Sie aus dem freigegebenen Secrets-Store.

1. Vorbereitung und Rückfallpunkt

• Umgebungsbezogene Änderungen in den Plattform-Fork zurückführen und mit dem Zielrelease abgleichen: insbesondere Replicas, Ressourcen, PVC-Größen und zusätzliche Ingresses.
• Plattform-Fork auf den freigegebenen 3.1-Stand aktualisieren und Änderungen bei Bedarf in den vorgesehenen Umgebungsbranch übernehmen. Branch-Namen richten sich nach Ihrem Repository.
• Repository klonen und den vorgesehenen Umgebungsbranch beziehungsweise freigegebenen Commit auschecken.
• Inventory und Kubeconfig aus dem freigegebenen Secrets-Store beziehen.
• Aktuelle, erfolgreich abgeschlossene Backups prüfen; bei Velero muss der Status Completed sein. Die Wiederherstellung und der Rückfallplan müssen gemäß Rückfallpunkt vorbereiten geprüft sein.
• Den bisherigen Release-Stand, das Inventory, lokale Anpassungen und relevante Helm-Revisionen sichern.
• Zugang zum freigegebenen Gateway-Migrationswerkzeug und bei Harbor-Nutzung zum Skript add-imagepullsecret-to-postgresql-serviceaccounts.sh bereitstellen. Diese Werkzeuge gehören nicht zum Dokumentationsrepository; Bezugsquelle und Version müssen vor Beginn feststehen.

Prüfen Sie vor jedem Deployment den ausgewählten Cluster:

export KUBECONFIG="$HOME/.kube/<cluster-config>"
kubectl config current-context
kubectl cluster-info

2. Inventory auf 3.1 umstellen

Übernehmen Sie die Struktur aus 02_core_platform/default_inventory.yml des Zielreleases und erhalten Sie weiterhin gültige Werte Ihrer Umgebung. Die Einordnung der Blöcke erläutern Plattformbasis konfigurieren und Mandanten konfigurieren.

2.1 Gateway API und Registries

Ergänzen Sie gateway_api im vorhandenen Block inv_k8s. load_balancer_ip muss der bisherigen externen Load-Balancer-IP entsprechen; die Ermittlung folgt in Phase 3.

inv_k8s:
  gateway_api:
    enable: true
    gateway_namespace: "nginx-gateway"
    gateway_cluster_issuer: "letsencrypt-gateway-prod"
    load_balancer_ip: "<existing-load-balancer-ip>"

inv_registry:
  dockerio: "docker.io"
  quayio: "quay.io"
  github: "ghcr.io"
  gitlab: "registry.gitlab.com"

Setzen Sie inv_idm.keycloak.theme_url auf die zum Zielrelease freigegebene Theme-JAR-URL. Übernehmen Sie eine vorhandene kundenspezifische Theme-Version nur nach Kompatibilitätsprüfung.

2.2 Abgelöste Inventory-Blöcke

Prüfen Sie für jede Komponente, ob noch Anwendungen oder Daten davon abhängen. Die folgenden alten Blöcke entfallen im 3.1-Inventory:

Komponente	Globale Blöcke entfernen	Pro Eintrag in inv_tenants entfernen
Gravitee	inv_am.apim, inv_replicas.gravitee	apim
Orion	inv_cm.fiware	fiware
OAuth2 Proxy	inv_pub	general_oauth_proxy
KomMonitor	inv_kom	kommonitor

Noch genutzte Komponenten

Wenn eine dieser Komponenten weiterhin benötigt wird, muss deren Ablösung oder Weiterbetrieb vor dem Upgrade geklärt sein. Das Entfernen eines Inventory-Blocks ersetzt keine Datenmigration. Die Kubernetes-Ressourcen werden erst in Phase 9 bereinigt.

2.3 Security Stack und optionale Integrationen

Ergänzen Sie den Security Stack zunächst im Audit-Modus. Aktivieren Sie die Durchsetzung der Kyverno-Policies erst nach Prüfung der Policy-Verstöße und Freigabe für die Zielumgebung.

inv_security:
  ns_name: "{{ ENVIRONMENT }}-security-stack"
  kyverno:
    enable: true
    enforce_policies: false
  policy_reporter:
    enable: true
    ui_enabled: true
    kyverno_plugin_enabled: true

GitLab Runner und Wazuh sind optional und können deaktiviert bleiben. Bei Aktivierung benötigen Sie einen für Ihre GitLab-Instanz geeigneten Runner-Token beziehungsweise die Wazuh-Zugangsdaten und Gruppen. Stimmen Sie die Runner-Registrierung einschließlich nicht getaggter Jobs mit Ihrer CI-Konfiguration ab.

inv_gitlab_runner:
  enable: false
  ns_name: "{{ ENVIRONMENT }}-gitlab-runner"
  token: "<gitlab-runner-token>"
  url: "https://gitlab.com/"
  replicas: 2

inv_wazuh_agent:
  enable: false
  ns_name: "{{ ENVIRONMENT }}-external-agent-stack"
  manager_hostname: "<wazuh-manager-host>"
  registration_password: "<wazuh-registration-password>"
  api_hostname: "<wazuh-api-host>"
  api_user: "<wazuh-api-user>"
  api_password: "<wazuh-api-password>"
  groups:
    - "<wazuh-group>"

Für Wazuh ist container_sock_path optional. Der Standard ist /var/run/containerd/containerd.sock; bei MicroK8s verwenden Sie /var/snap/microk8s/common/run/containerd.sock.

2.4 Observability: Alloy und optional Thanos

Deaktivieren Sie Promtail und aktivieren Sie Alloy im vorhandenen Block inv_ml. Falls Thanos bereits konfiguriert ist, erhalten Sie dessen Einstellungen. Thanos bleibt andernfalls zunächst deaktiviert.

inv_ml:
  thanos:
    enable: false
    unique_labels:
      - key: cluster
        value: "{{ DOMAIN }}"
    s3_storage:
      bucket: "<bucket>"
      endpoint: "<s3-endpoint>"
      region: "<region>"
      access_key: "<access-key>"
      secret_key: "<secret-key>"
  promtail:
    enable: false
  alloy:
    enable: true
    replicas: 1

Bei aktiviertem Thanos muss das Cluster-Label über alle Prometheus-Instanzen eindeutig sein. Der S3-Endpunkt wird ohne http:// oder https:// angegeben.

2.5 Harbor zunächst deaktivieren

Auch wenn Sie Harbor später nutzen, bleibt die Integration bis zur Vorbereitung in Phase 7 deaktiviert:

inv_harbor:
  enable: false
  pull_secret_name: "harbor-registry-credentials"
  registry: "registry.example.org"
  robot_account:
    username: "<robot-username>"
    password: "<robot-password>"

2.6 Hypersensus und Mandantendomains

inv_hypersensus:
  version: "v2.0.5"
  registry:
    url: "{{ inv_registry.gitlab }}"
  frontend:
    common_url: "portal.example.org"
    tenant_dropdown_enabled: true

Bisherige Konfiguration	Konfiguration für 3.1
frontend_url	inv_hypersensus.frontend.common_url
tenant_dropdown	inv_hypersensus.frontend.tenant_dropdown_enabled
Mandanten ohne Anzeigenamen	display_name bei Bedarf ergänzen
Abweichende Hypersensus-Domain	Optional hypersensus_domain ergänzen

common_url, tenant_domain und hypersensus_domain sind Hostnamen ohne Protokoll und ohne abschließenden Schrägstrich. common_url ist optional und kann leer bleiben. Dann muss jeder Mandant über eine eigene Domain erreichbar sein. Ein gesetztes hypersensus_domain hat Vorrang vor tenant_domain für den Hypersensus-Link; die Basisdomain der übrigen Mandantendienste bleibt tenant_domain.

inv_tenants:
  - tenant_realm: "<tenant-realm>"
    tenant_prefix: "<tenant-prefix>"
    tenant_domain: "tenant.example.org"
    display_name: "Beispielmandant"
    hypersensus_domain: "portal.tenant.example.org"

Gateway-Migrationswerkzeug auf kompatible Parameter prüfen

Die ursprünglichen Migrationsnotizen verlangen, frontend_url für das Gateway-Migrationswerkzeug vorübergehend beizubehalten. Die lokal vorliegenden Gateway-Templates verwenden dagegen unter anderem inv_hypersensus.frontend.common_domain, während die Plattform common_url nutzt. Diese Stände sind nicht unmittelbar konsistent. Prüfen Sie vor Phase 3 die konkret freigegebene Werkzeugversion und deren Inventory-Erwartungen. Übertragen Sie die gemeinsame Domain in die dort erwarteten Felder und prüfen Sie die erzeugten Listener und Routen. Entfernen Sie benötigte Legacy-Felder erst nach der Gateway-Migration.

2.7 APISIX, Superset und Geodata

Ergänzen beziehungsweise ändern Sie in jedem betroffenen Eintrag unter inv_tenants:

Komponente	Anpassung
APISIX	apisix.session_secret ergänzen: mindestens 16 Zeichen. Bestehende api_credentials.admin_role und viewer_role mit jeweils 32 Zeichen erhalten.
Superset	analytics.redis_storage_size: "1Gi" ergänzen beziehungsweise an den Bedarf anpassen. Optional analytics.subdomain für eine abweichende Subdomain setzen.
Geodata	Das bisherige Feld keycloak_pub_signing_key im Geodata-Block entfernen.

Beispiel für den APISIX-Block eines Mandanten:

apisix:
  enable: true
  api_credentials:
    admin_role: "<admin-role-api-key>"
    viewer_role: "<viewer-role-api-key>"
  session_secret: "<session-secret>"

2.8 CKAN pro Mandant konfigurieren

inv_mds liegt innerhalb des jeweiligen Eintrags in inv_tenants, nicht auf globaler Ebene. Übernehmen Sie in diesen Block die folgenden Einstellungen und erhalten Sie vorhandene Datenbank-, Storage- und weitere Mandantenwerte:

inv_tenants:
  - tenant_realm: "<tenant-realm>"
    # Weitere vorhandene Mandantenfelder bleiben erhalten.
    inv_mds:
      enable: true
      ns_name: "{{ ENVIRONMENT }}-metadata-stack"
      enable_logical_backup: false
      ckan:
        app_host: "ckan"
        ckan_plugins: "dcat dcatde scheming_datasets harvest ckan_harvester oauth"
        ckan_views_plugins: "image_view text_view webpage_view geo_view geojson_view wmts_view shp_view pdf_view datatables_view resource_proxy piechart linechart barchart"
        footer:
          impressum_url: "https://ckan.{{ DOMAIN }}/pages/impressum"
          datenschutz_url: "https://ckan.{{ DOMAIN }}/pages/datenschutz"
          nutzungsbedingungen_url: "https://ckan.{{ DOMAIN }}/pages/nutzungsbedingungen"
          extra_link_name: "About CKAN"
          extra_link_url: "https://ckan.org/"
        locale_default: "de"
        custom_resources:
          enable: false
          gitlab:
            url: "<custom-resources-repository-url>"
            token_name: "<deploy-token-name>"
            token_secret: "<deploy-token-secret>"

Footer-Konfiguration benötigt das Plugin footer in ckan_plugins; ergänzen Sie es bei Nutzung oder entfernen Sie den ungenutzten Footer-Block. Prüfen Sie, dass die verlinkten rechtlichen Seiten tatsächlich vorhanden sind. Die Plugins pages und theming sind keine allgemein erforderlichen Migrationsvorgaben.

Für eigene Datenschemata oder Übersetzungen aktivieren Sie custom_resources und stellen ein dafür vorgesehenes Repository bereit. Die Migrationsnotizen sehen dort ausschließlich dataset.yaml und translation.json vor; die lokal vorliegenden Tasks unterstützen zusätzlich Theming-Dateien. Entfernen Sie bestehende Pages- oder Theming-Anpassungen daher nicht pauschal, sondern gleichen Sie diese mit dem konkret eingesetzten CKAN-Stand ab. Bei öffentlichen Ressourcen-Repositories können die Token-Felder entfallen.

3. Ingress auf Gateway API migrieren

3.1 Werkzeug und Load Balancer vorbereiten

• Freigegebenes Gateway-Migrationswerkzeug bereitstellen und dessen inventory.yaml ausfüllen.
• Bestehende externe Load-Balancer-IP ermitteln und in beiden Inventories konsistent setzen.
• Ingress-Load-Balancer-Service sowie bisherige Ingress-, Zertifikats- und Keycloak-Konfiguration sichern.

kubectl get service ingress-nginx-controller \
  --namespace=ingress-nginx \
  --output=jsonpath='{.status.loadBalancer.ingress[0].ip}'

kubectl get service ingress-nginx-controller \
  --namespace=ingress-nginx \
  --output=yaml > svc-ingress-lb.yaml

Das Werkzeug legt beim ersten Lauf mit vorhandenem Ingress-Load-Balancer zusätzlich backup-ingress-lb.yaml an. Verlassen Sie sich für den Rückfallpunkt nicht ausschließlich auf diese automatische Sicherung.

3.2 Node-RED und optional MicroK8s vorbereiten

Ergänzen Sie für jede Node-RED-Instanz den Gateway-Namespace als erlaubtes Ziel in den Egress-Netzwerkregeln. Verwenden Sie bei abweichendem Gateway-Namespace den tatsächlich konfigurierten Namen:

- namespaceSelector:
    matchLabels:
      kubernetes.io/metadata.name: nginx-gateway

Dies erlaubt Verbindungen zu Diensten im Gateway-Namespace. Prüfen Sie die übrigen Egress-Regeln separat; dieser Ausschnitt allein erlaubt keinen allgemeinen Internetzugriff.

Nur bei einer Hetzner-VM mit MicroK8s: Führen Sie nach Prüfung des vorgesehenen Load-Balancer-Verfahrens auf der VM die Umstellung aus. Ersetzen Sie den Platzhalter durch die für diesen Server vorgesehene IP:

microk8s disable ingress
microk8s enable metallb:<server-ip>-<server-ip>

3.3 Gateway-Playbook ausführen

Führen Sie den Befehl im Verzeichnis des Gateway-Migrationswerkzeugs aus. Beide Inventories sind erforderlich:

ansible-playbook playbook.yaml \
  -i inventory.yaml \
  -i ../my-platform/my-inventory.yaml

Bei einem Fehler zum Parameter reset_then_reuse_values während des cert-manager-Upgrades nennen die Migrationsnotizen folgende Aktualisierung der lokalen Collection:

ansible-galaxy collection install "kubernetes.core:>=6.0.0,<7.0.0" --upgrade

Dieser Workaround ist nicht für jede Werkzeugkombination verifiziert. Gleichen Sie ihn mit der freigegebenen Ansible-/Helm-Version und den Requirements des eingesetzten Werkzeugs ab.

3.4 Routen und Anwendungen prüfen

• Bei Keycloak-HTTPRoutes parentRefs.name mit dem tatsächlich vorhandenen mandantenspezifischen ListenerSet abgleichen; ebenso namespace und sectionName prüfen.
• Hypersensus-Domains und Routen prüfen. Unterschiedliche Zwischenstände von Frontend, Backend und Migrationstemplates können die Erreichbarkeit beeinträchtigen.
• Im Masterportal-Deployment PORTAL_BACKEND von der bisherigen öffentlichen HTTPS-Adresse auf http://portal-backend umstellen, sofern dies der interne Service-Name Ihrer Installation ist. Dadurch nutzt der NGINX-Proxy den internen Backend-Service statt des externen TLS-Endpunkts.
• TLS, Keycloak-Anmeldung, Mandantenrouten und die aktivierten Anwendungen prüfen.

Beispiel für eine mandantenspezifische Referenz:

parentRefs:
  - group: gateway.networking.k8s.io
    kind: ListenerSet
    name: "<tenant-prefix>"
    namespace: nginx-gateway
    sectionName: "idm.tenant.example.org"

3.5 Alte Ingress-Ressourcen bereinigen

Erst wenn die Gateway-Routen funktionieren und die Konfiguration gesichert ist, entfernen Sie die ersetzten Ingress-Ressourcen gezielt. Verbleibende alte Ressourcen können die Zertifikatserneuerung stören. Entfernen Sie auch den alten Admission-Webhook, sofern kein weiterhin genutzter Ingress-Controller davon abhängt:

kubectl delete validatingwebhookconfiguration ingress-nginx-admission

3.6 Rückfall auf Ingress

Der Gateway-Rückfall stellt nur die zuvor gesicherte Ingress-Anbindung wieder her. Datenbank- oder spätere Komponenten-Upgrades benötigen den umfassenden Rückfallplan aus Phase 1.

Providerabhängiger Rückfall

Das folgende Verfahren aus dem Gateway-README setzt OpenStack und eine wiederverwendbare Floating-IP voraus. Für MicroK8s/MetalLB oder andere Provider ist ein gesondert geprüfter Rückfallplan erforderlich. Nach dem Entfernen alter Ingress-Ressourcen müssen diese ebenfalls aus der Sicherung wiederhergestellt werden.

1. Ermitteln und notieren Sie die Gateway-Load-Balancer-IP vor dem Löschen des Gateway-Service.
2. Setzen Sie am Gateway-Service die OpenStack-Annotation zum Erhalten der Floating-IP.
3. Löschen Sie den Gateway und warten Sie, bis sein Load-Balancer-Service entfernt ist.
4. Stellen Sie den gesicherten Ingress-Load-Balancer-Service mit derselben IP wieder her. Prüfen Sie die providerbezogenen Annotationen loadbalancer.openstack.org/keep-floatingip: "true" und loadbalancer.openstack.org/load-balancer-address sowie spec.loadBalancerIP. Bereinigen Sie serverseitig erzeugte Metadaten vor dem Wiederanlegen und prüfen Sie NodePorts und Selektoren.
5. Stellen Sie gegebenenfalls die gesicherten Ingress-Ressourcen wieder her, rollen Sie cert-manager auf die gesicherte Helm-Revision zurück und stellen Sie die vorherige Keycloak-Konfiguration wieder her. Die während der Migration ergänzten Felder spec.http.httpEnabled und spec.proxy.headers müssen anhand der Sicherung zurückgesetzt werden.
6. Prüfen Sie IP-Zuordnung, TLS, Anmeldung und alle betroffenen Anwendungen.

Die ersten drei Schritte für die im Werkzeug verwendeten Standardnamen:

kubectl get service default-nginx --namespace=nginx-gateway \
  --output=jsonpath='{.status.loadBalancer.ingress[0].ip}'

kubectl annotate service default-nginx --namespace=nginx-gateway \
  loadbalancer.openstack.org/keep-floatingip=true --overwrite

kubectl delete gateway default --namespace=nginx-gateway

4. PostgreSQL-Operator aktualisieren

Die temporären Änderungen erfolgen in 02_core_platform/templates/01_op_postgres_operator/postgres-operator-values.yaml im freigegebenen Plattformstand. Sichern Sie vorher den Ausgangszustand einschließlich eigener Anpassungen.

Vorübergehend nur eine Datenbankinstanz

max_instances: 1 reduziert die vom Operator verwalteten PostgreSQL-Cluster auf eine Instanz. Während dieser Phase entfällt deren Replica-Redundanz. Planen Sie den Schritt im Wartungsfenster ein und fahren Sie erst nach erfolgreicher Bereitschaftsprüfung fort.

1. Setzen Sie kubernetes_use_configmaps: false und max_instances: 1.
2. Führen Sie das Plattform-Playbook mit --tags operator_postgres aus.
3. Warten Sie auf den aktualisierten Operator und die Skalierung aller betroffenen PostgreSQL-StatefulSets auf eine Instanz.
4. Setzen Sie kubernetes_use_configmaps: true; lassen Sie max_instances: 1 zunächst bestehen.
5. Führen Sie denselben Operator-Lauf erneut aus und warten Sie, bis alle neu erzeugten PostgreSQL-Pods bereit sind.
6. Stellen Sie die gesicherte Zielkonfiguration wieder her. Im lokalen Zieltemplate ist max_instances: -1 gesetzt; erhalten Sie bewusst konfigurierte Abweichungen.
7. Führen Sie den Operator-Lauf ein drittes Mal aus und prüfen Sie die vorgesehenen Datenbankinstanzen sowie Lese- und Schreibzugriffe.

Befehl für jeden Operator-Lauf, aus dem Plattformrepository:

ansible-playbook -i inventories/<environment>.yml -l localhost \
  02_core_platform/full_install.yml --tags operator_postgres

Falls die Datei vor dem Upgrade keine lokalen Anpassungen hatte und der Checkout bereits dem freigegebenen Zielstand entspricht, kann sie mit git restore 02_core_platform/templates/01_op_postgres_operator/postgres-operator-values.yaml zurückgesetzt werden. Andernfalls stellen Sie Ihre gesicherte Konfiguration gezielt wieder her.

5. Keycloak aktualisieren

Prüfen Sie vor diesem Lauf, ob Keycloak-Operator und CRDs den Zielstand unterstützen. Der Tag idm_keycloak aktualisiert die Keycloak-Installation, führt aber die separat mit operator_keycloak getaggten Operator-Tasks nicht aus. Falls der Operator ebenfalls aktualisiert werden muss, klären und prüfen Sie dessen Upgrade-Reihenfolge mit dem freigegebenen Releaseverfahren; die ursprünglichen Migrationsnotizen beschreiben diesen Schritt nicht.

ansible-playbook -i inventories/<environment>.yml -l localhost \
  02_core_platform/full_install.yml --tags idm_keycloak

• Operator, Keycloak-Pods und Datenbank auf Bereitschaft prüfen.
• Anmeldung, Mandanten-Realms, Clients, Weiterleitungen und Theme prüfen.
• Erst nach erfolgreicher Prüfung mit dem vollständigen Deployment fortfahren.

6. Release 3.1 vollständig ausrollen

6.1 Temporäre Workarounds prüfen

Die folgenden Hinweise stammen aus den Migrationsnotizen und sind umgebungsabhängig. Wenden Sie sie nur an, wenn der konkrete Zielstand und das Fehlerbild dies erfordern; dokumentieren Sie temporäre Abweichungen.

MinIO-Image: Die Notizen verwenden ein separat bereitgestelltes Image statt des regulären Registry-Pfads. Falls dieses Image benötigt wird, setzen Sie in 02_core_platform/vars/00_software_references.yml den freigegebenen und erreichbaren Pfad. Der Beispielhost und Projektpfad müssen durch Ihre bereitgestellte Registry ersetzt werden; prüfen Sie erforderliche Pull-Zugänge auch bei deaktivierter Harbor-Integration.

dm_minio_tenant:
  helm_repo_url: "https://operator.min.io/"
  helm_repo_name: "minio"
  helm_chart_name: "tenant"
  helm_release_name: "minio-tenant"
  helm_chart_version: "7.1.1"
  image_repository: "registry.example.org/<release-project>/minio/minio"
  image_tag: "RELEASE.2025-04-22T22-12-26Z"

APISIX/etcd-Storage: Das lokale APISIX-Template setzt etcd.persistence.storageClass. Bei vorhandenen StatefulSets kann das Upgrade durch eine unveränderliche Storage-Konfiguration scheitern. Die Notizen schlagen vor, während der Migration dieses Feld im Template 02_core_platform/templates/10_api_management/deployment/apisix-values.yaml auszukommentieren:

etcd:
  persistence:
    enabled: true
    # storageClass: "{{ inv_k8s.storage_class.rwo }}"

Dieser Workaround ist nicht für jeden Altbestand verifiziert. Prüfen Sie zuvor die bestehenden Helm-Werte, StatefulSets und PVCs; lassen Sie die Persistenz aktiviert. Ein Entfernen des Felds garantiert nicht, dass gerenderte Helm-Werte unverändert bleiben. Ein späteres Wiederaktivieren benötigt dieselbe Kompatibilitätsprüfung.

6.2 Vollständiges Playbook ausführen

• inv_harbor.enable steht weiterhin auf false.
• Hypersensus-Registry ist im Inventory definiert, zunächst mit url: "{{ inv_registry.gitlab }}"; erforderliche Registry-Zugangsdaten sind vorhanden.
• Freigegebene Requirements installieren und Syntax prüfen.
• Vollständiges Deployment ausführen.

ansible-galaxy collection install -r requirements.yml

ansible-playbook -i inventories/<environment>.yml -l localhost \
  02_core_platform/full_install.yml --syntax-check

ansible-playbook -i inventories/<environment>.yml -l localhost \
  02_core_platform/full_install.yml

6.3 Bekannte Hypersensus-Routenkonflikte

Durch das Gateway-Migrationswerkzeug erzeugte Ressourcen können mit den Plattform-Routen kollidieren. Die Notizen nennen Ressourcen mit Namen hypersensus-redirect-* und hypersensus-frontend-ingress der Typen HTTPRoute, ProxySettingPolicy, SnippetsFilter und ClientSettingsPolicy.

Prüfen Sie Namespace, Namen, Referenzen und Herkunft der tatsächlich vorhandenen Ressourcen. Sichern und entfernen Sie ausschließlich die überholten Migrationsressourcen, wenn deren Ersatz durch den Plattformstand feststeht. Die genannten Namen und Typen sind keine pauschale Löschliste; das Auftreten hängt von der Werkzeugversion ab. Wiederholen Sie anschließend das Deployment und prüfen Sie Redirects sowie Frontend- und Backend-Erreichbarkeit.

7. Optional: Harbor vorbereiten

Wenn Harbor nicht eingesetzt wird, überspringen Sie die Phasen 7 und 8. Prüfen Sie nach Phase 6 direkt den vollständigen Plattformstand und gehen Sie anschließend zur Bereinigung über.

7.1 Registry-Pfade konfigurieren

Der Inventory-Block heißt inv_registry. Ersetzen Sie die folgenden Beispiel-Projektnamen durch die in Ihrer Harbor-Instanz eingerichteten Proxy-Projekte:

inv_registry:
  dockerio: "registry.example.org/<dockerhub-proxy-project>"
  quayio: "registry.example.org/<quay-proxy-project>"
  github: "registry.example.org/<github-proxy-project>"
  gitlab: "registry.example.org/<gitlab-proxy-project>"

inv_harbor:
  enable: true
  pull_secret_name: "harbor-registry-credentials"
  registry: "registry.example.org"
  robot_account:
    username: "<robot-username>"
    password: "<robot-password>"

Setzen Sie Harbor jetzt im Inventory, führen Sie aber noch keinen Operator- oder vollständigen Plattform-Lauf aus. Zuerst müssen die PostgreSQL-Pull-Zugänge vorbereitet sein.

7.2 PostgreSQL-Pull-Zugänge vorbereiten

Pull-Secrets vor dem Operator-Deployment

Der PostgreSQL-Operator kann nach der Registry-Umstellung alle Datenbank-Pods mit Harbor-Images neu erzeugen. Fehlen die Pull-Secrets in deren Namespaces und ServiceAccounts, können diese Pods nicht starten.

Führen Sie das vorab bereitgestellte Skript im richtigen Cluster aus. Ersetzen Sie die Zugangsdaten und E-Mail durch die für Ihre Registry vorgesehenen Werte:

./add-imagepullsecret-to-postgresql-serviceaccounts.sh \
  --secret-name 'harbor-registry-credentials' \
  --docker-server 'registry.example.org' \
  --docker-username '<robot-username>' \
  --docker-email '<registry-email>' \
  --docker-password '<robot-password>' \
  --dry-run

Prüfen Sie die vorgesehenen Namespaces und ServiceAccounts und führen Sie danach denselben Befehl ohne --dry-run aus. Das Skript erstellt beziehungsweise aktualisiert Registry-Secrets in Namespaces mit Zalando-PostgreSQL-Ressourcen und ergänzt die ServiceAccounts um imagePullSecrets. Der Standard-ServiceAccount ist postgres-pod; bei abweichender Konfiguration verwenden Sie --service-account. Fehlende ServiceAccounts müssen vor dem Deployment geklärt werden.

7.3 Keel und Image-Verfügbarkeit prüfen

Die Migrationsnotizen nennen Einschränkungen für über Keel aktualisierte Images, beispielsweise NGSI-LD Context Hoster und Masterportal. Übernehmen Sie diese Images nicht ungeprüft in den Harbor-Proxy-Pfad. Prüfen Sie das für den Zielstand freigegebene Registry- und Update-Verfahren sowie die Verfügbarkeit aller benötigten Images.

8. Optional: Release 3.1 mit Harbor ausrollen

• Pull-Secrets und ServiceAccount-Referenzen für PostgreSQL sind vorbereitet.
• Robot-Account kann alle erforderlichen Registry-Projekte lesen.
• Vollständiges Plattform-Playbook wie in Phase 6 ausführen.
• Image-Pulls, Datenbankbereitschaft und alle aktivierten Anwendungen prüfen.

Bekanntes MinIO-Problem: Falls das Image im Quay-Proxy-Projekt nicht verfügbar ist, verwenden Sie nach Prüfung den separat bereitgestellten MinIO-Pfad aus Phase 6. Ein nicht vorhandenes Image unter dem Proxy-Pfad wird durch erneutes Deployment nicht verfügbar. Der alternative Pfad und seine Zugangsvoraussetzungen müssen vor dem Rollout feststehen.

9. Abgelöste Komponenten entfernen

Löschung erst nach Abnahme

Namespace-Löschungen entfernen auch darin enthaltene Anwendungen und können persistente Daten betreffen. Prüfen Sie für OAuth2 Proxy, Gravitee, Orion und KomMonitor einzeln, dass keine Nutzung oder Abhängigkeit mehr besteht, notwendige Daten migriert sind und Sicherungen vorliegen. Bereinigen Sie erst nach erfolgreicher Plattformabnahme.

Ermitteln Sie die tatsächlichen Namespace-Namen aus der Altinstallation. Die Migrationsnotizen enthalten einen möglicherweise abweichenden Gravitee-Namen mit doppeltem stack; übernehmen Sie diesen nicht ungeprüft. Löschen Sie jeden freigegebenen Namespace einzeln:

kubectl get namespaces
kubectl delete namespace <confirmed-deprecated-namespace>

Deinstallieren Sie Promtail erst, wenn Alloy Logs erfolgreich übernimmt und der tatsächliche Helm-Release-Name sowie Namespace geprüft sind:

helm list -n <environment>-observability-stack
helm uninstall promtail -n <environment>-observability-stack

10. Abschlussprüfung und Dokumentation

• Installation verifizieren: Kubernetes-/Helm-Status, Datenbanken, TLS, Anmeldung, APIs und aktivierte Anwendungen prüfen.
• PostgreSQL-Replica-Konfiguration entspricht wieder dem freigegebenen Zielzustand; Testdaten können geschrieben und gelesen werden.
• Hypersensus-Domains, Mandantenauswahl und Weiterleitungen funktionieren.
• Metriken, Logs und Alerting prüfen; Alloy übernimmt die vorgesehenen Logquellen.
• Temporäre Template- und Image-Abweichungen mit Grund und weiterem Vorgehen dokumentieren; Änderungen in den Plattform-Fork zurückführen.
• Release-Commit, Inventory, ausgeführte Schritte, Backups und Abnahme im Upgrade-Nachweis festhalten.

Der Rückfallpunkt bleibt bis zum Ende der vereinbarten Beobachtungs- und Aufbewahrungszeit erhalten.