Containerbasierte Installation – Orchestrierte Umgebung

Informationen

• Die einzelnen Komponenten von PLANTA Project Manager, Worker, Customizing (Datenbank), Web-Client und optional Pulse werden als Container-Images im Docker-Container-Format bereitgestellt und über Helm in einer Kubernetes-Umgebung installiert.

  • Manager ist verantwortlich für die Zugriffe auf die Datenbank sowie für Geschäftslogik, Datenverarbeitung und API-Dienste.

  • Worker stellt Client- bzw. Web-Client-Verbindungen her und führt Hintergrundprozesse aus.

  • Customizing ist ein Initialisierungsjob und enthält Standard-Customizing und kundenspezifische Anpassungen. Er bereitet die Datenbank vor und wird anschließend beendet.

  • Web-Client stellt die Benutzeroberfläche von PLANTA Project im Webbrowser bereit.

  • Pulse (optional) ist die agile PLANTA-Komponente für das Aufgaben-Management und die Kollaboration.

• Für Produktions-Workloads empfehlen wir, die Secure-Komponente als Reverse Proxy vorzuschalten (TLS‑Terminierung, Single Sign-On mit OIDC usw.).

• Die Container-Images können überall dort bereitgestellt werden, wo eine OCI‑kompatible Container Runtime bzw. Plattform vorhanden ist. In einer orchestrierten Umgebung erfolgt der Betrieb auf einem Kubernetes‑Cluster.

• Die Komponenten werden als Deployments oder Jobs mit den erforderlichen Services, PersistentVolumeClaims und Ingress-Ressourcen angelegt. Zusammen bilden sie eine vollständige PLANTA-Projektmanagement-Umgebung.

Was ist Helm?

Helm ist ein Paketmanager für Kubernetes, mit dem Anwendungen paketiert, verteilt und mit einem Kommando installiert oder aktualisiert werden können. Anstatt mehrere Kubernetes‑Ressourcendefinitionen manuell zu erstellen, wird die Anwendung als sogenanntes Chart bereitgestellt.

Wichtige Begriffe:

• Chart: Paket, das alle benötigten Kubernetes‑Ressourcen für eine Anwendung beschreibt.

• Release: Eine installierte Instanz eines Charts in einem Kubernetes‑Cluster.

• Values: Konfigurationswerte, mit denen ein Release angepasst wird (z. B. Datenbank‑Zugriffe, Lizenzinformationen, Ressourcenlimits).

Weitere Informationen zu Helm siehe offizielle Dokumentation unter https://helm.sh/docs/.

Voraussetzungen

Vor der Installation in einer orchestrierten Umgebung müssen folgende Voraussetzungen erfüllt sein:

1. Kubernetes‑Cluster (Version 1.21 oder höher)
   Geeignet sind z. B. AKS, EKS, GKE, OpenShift oder On‑Premises‑Kubernetes.

2. Helm (Version 3.x oder höher)
   Installationsanleitung Helm

3. kubectl mit Zugriff auf den Cluster
   Prüfung mit: kubectl cluster-info

4. Zugriff auf die PLANTA OCI‑Registry

   • Registry‑URL: registry.planta.services

   • Anleitung zur Anmeldung: https://help.planta.de/en/tec/Container-ab-39.5.24/anmeldung-planta-oci-registry

5. Unterstützte Datenbankinstanz
   Details siehe Systemvoraussetzungen und Plattformen → Abschnitt Database Requirements:

6. PLANTA‑Lizenz
   Entweder als Lizenznummer oder als Lizenzdatei.

7. Persistente Speicherung im Cluster

   • Für gemeinsam genutzte Daten: Unterstützung des Modus ReadWriteMany (RWX).

8. Ingress‑Controller für produktive Umgebungen
   z. B. NGINX, Traefik oder OpenShift Routes.

Helm‑Chart der PLANTA‑Registry herunterladen

Alle Container-Images und das Helm‑Chart sind in der PLANTA‑Registry unter https://registry.planta.services verfügbar. Die Zugangsdaten erhalten Sie von PLANTA. Details zur Anmeldung: https://help.planta.de/en/tec/Container-ab-39.5.24/anmeldung-planta-oci-registry

Option 1: Helm‑Chart direkt installieren

Beispiel:

helm install my-planta oci://registry.planta.services/planta/helm \
  --version 1.0.0 \
  --namespace planta \
  --create-namespace \
  --values my-values.yaml

Option 2: Helm‑Chart zuerst lokal ziehen

# Chart lokal herunterladen und entpacken
helm pull oci://registry.planta.services/planta/helm \
  --version 1.0.0 --untar
# Installation aus lokalem Chart
helm install my-planta ./helm \
  --namespace planta \
  --create-namespace \
  --values my-values.yaml

Bereitstellung im Kubernetes‑Cluster

1. Namespace anlegen (falls nicht über Helm erstellt):

   CODE

   kubectl create namespace planta

2. Konfigurationsdatei erstellen
   my-values.yaml mit allen benötigten Parametern anlegen bzw. anpassen (Datenbank, Lizenz, Ressourcen, Ingress usw.), siehe den Abschnitt "Konfiguration des helm-Charts".

3. Helm‑Chart installieren:

   CODE

   helm install my-planta oci://registry.planta.services/planta/helm \
     --namespace planta \
     --values my-values.yaml \
     --timeout 10m

4. Installation überwachen:

   CODE

   # Pods beobachten
   kubectl get pods -n planta -w
   # Release-Status prüfen
   helm status my-planta -n planta

Konfiguration des Helm‑Charts

Die Konfiguration der Container in der orchestrierten Umgebung erfolgt – analog zur Einzelumgebung mit Docker Compose – über Umgebungsvariablen. In Kubernetes/Helm werden diese entweder direkt über values.yaml oder über Kubernetes‑Secrets gesetzt.

Eine Übersicht über alle verfügbaren Parameter finden Sie im Topic Server- und Client‑Konfiguration.

Minimale erforderliche Konfiguration

Erstellen Sie eine Kopie der Datei values.yaml mit dem Namen my-values.yaml und setzen Sie folgende Parameter:

• Manager

  • planta__server__hibernate__connection__url

  • planta__server__hibernate__connection__username

  • planta__server__hibernate__connection__password

  • planta__server__ppms_license

• Pulse (falls verwendet)

  • MONGO_URL

  • MONGO_OPLOG_URL

Diese Parameter entsprechen inhaltlich den Parametern aus den Docker‑Compose‑Templates und werden im Chart als Umgebungsvariablen an die jeweiligen Container übergeben.

Datenbank‑Konfiguration

Konfiguration über Umgebungsvariablen (z. B. Test‑/Entwicklungssysteme)

manager:
  env:
    # Beispiel Oracle
    planta__server__hibernate__connection__url: "jdbc:oracle:thin:@hostname:1521/servicename"
    planta__server__hibernate__connection__username: "planta_user"
    planta__server__hibernate__connection__password: "ihr-passwort"

Konfiguration über Kubernetes‑Secrets (empfohlen für produktive Systeme)

Für Datenbank‑Zugangsdaten und andere sensible Konfigurationen sollten Kubernetes‑Secrets verwendet werden. Ein vollständiges Beispiel finden Sie in secret-example.yaml.

Beispielreferenz in den Values:

manager:
  secrets:
    userSecretName: "planta-db-secret"

Weitere Details zu verfügbaren Parametern siehe Server- und Client‑Konfiguration.

Lizenz‑Konfiguration

Für die Lizenzierung sind zwei Dinge erforderlich: die als Umgebungsvariable festgelegte Lizenznummer und die Datei license.conf, die über eine der unten aufgeführten Optionen bereitgestellt wird.

Lizenznummer als Umgebungsvariable

manager:
  env:
    planta__server__ppms_license: "ihre-lizenznummer"

Lizenzdatei: Option 1 - Eigener Secret

Variante mit eigenem Secret:

manager:
  license:
    enabled: true
    secretName: "ihr-license-secret"

Lizenzdatei: Option 2 - Chart-Secret

Variante, bei der das Chart das Secret automatisch aus einer lokalen Lizenzdatei erzeugt:

manager:
  license:
    enabled: true
    path: "license.conf"

Image‑Konfiguration und Registry‑Zugriff

Standardmäßig werden die Images aus der PLANTA‑Registry gezogen. Dafür wird ein ImagePullSecret verwendet:

imagePullSecrets:
  - name: registry-credentials

Secret anlegen:

kubectl create secret docker-registry registry-credentials \
  --docker-server=registry.planta.services \
  --docker-username=IHR-BENUTZERNAME \
  --docker-password=IHR-PASSWORT \
  --namespace planta

Detaillierte Anleitung zur Authentifizierung siehe Registry‑Dokumentation Anmeldung PLANTA OCI Registry

Zugriff auf PLANTA

Nach erfolgreicher Installation den Status der Pods überprüfen:

kubectl get pods -n planta

Alle relevanten Pods sollten im Status Running sein. Der Zugriff auf den Web‑Client erfolgt in produktiven Umgebungen über den konfigurierten Ingress bzw. die Route.

Für Testzwecke ohne Ingress kann Port‑Forwarding verwendet werden:

# Zugriff auf den Web-Client
kubectl port-forward svc/my-planta-webclient 5000:5000 -n planta
# Aufruf im Browser:
# http://localhost:5000

Aktualisierung (Upgrade) einer bestehenden Installation

Vorgehensweise:

1. Konfigurationsdatei my-values.yaml an neue Anforderungen oder Chart‑Version anpassen.

2. Release aktualisieren:

   CODE

   helm upgrade my-planta oci://registry.planta.services/planta/helm \
     --namespace planta \
     --values my-values.yaml \
     --version 1.1.0

3. Upgrade überwachen:

   CODE

   kubectl rollout status deployment/my-planta-manager -n planta
   kubectl get pods -n planta

Deinstallation

Um eine PLANTA‑Installation aus dem Cluster zu entfernen:

# Uninstall the Helm release
helm uninstall my-planta -n planta

# Optionally, delete the namespace and all resources
kubectl delete namespace planta

Erweiterte Konfiguration

Ressourcenlimits (CPU/RAM)

Beispielkonfiguration:

manager:
  resources:
    requests:
      memory: "2Gi"
      cpu: "1000m"
    limits:
      memory: "4Gi"
      cpu: "2000m"

webclient:
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"

Empfehlungen zur Dimensionierung siehe Systemvoraussetzungen und Plattformen.

Speicherklassen und Persistenz

Speicherklassen für für persistente Volumes definieren:

storageClassName: "fast-ssd"  # Global storage class

# Per-component storage configuration
transfer:
  persistence:
    size: 1Gi
    accessMode: ReadWriteMany
    # Optionally override storage class for shared volume
    storageClassName: ""

webclient:
  persistence:
    size: 5Gi
    accessMode: ReadWriteOnce

pulse:
  persistence:
    size: 10Gi
    accessMode: ReadWriteOnce

Selbstverwaltete PVCs

Standardmäßig erstellt das Chart automatisch PersistentVolumeClaims und bindet diese in jede Bereitstellung/jeden Job für jede Komponente ein, die persistenten Speicher benötigt. Wenn Sie die volle Kontrolle wünschen – beispielsweise um benutzerdefinierte Labels, Anmerkungen oder Volume-Bindungsmodi festzulegen oder vorab bereitgestellte Volumes wiederzuverwenden –, können Sie die automatische PVC-Erstellung pro Komponente deaktivieren.

Wenn persistence.create: false:

• Die PVC-Ressource wird nicht vom Diagramm erstellt.

• Sie stellen das Volume selbst über additionalVolumes / additionalVolumeMounts bereit, die auf das von Ihnen erstellte PVC verweisen.

Eigene PVCs verwenden

Falls PVCs nicht automatisch durch das Chart erzeugt werden sollen:

transfer:
  persistence:
    create: false
manager:
  additionalVolumes:
    - name: my-transfer
      persistentVolumeClaim:
        claimName: my-company-transfer-pvc
  additionalVolumeMounts:
    - name: my-transfer
      mountPath: /mnt/transfer
      readOnly: true
worker:
  additionalVolumes:
    - name: my-transfer
      persistentVolumeClaim:
        claimName: my-company-transfer-pvc
  additionalVolumeMounts:
    - name: my-transfer
      mountPath: /mnt/transfer
      readOnly: true
customizing:
  additionalVolumes:
    - name: my-transfer
      persistentVolumeClaim:
        claimName: my-company-transfer-pvc
  additionalVolumeMounts:
    - name: my-transfer
      mountPath: /mnt/transfer
      readOnly: false

Analog für Web‑Client und Pulse:

webclient:
  persistence:
    create: false
  additionalVolumes:
    - name: my-webclient-data
      persistentVolumeClaim:
        claimName: my-company-webclient-pvc
  additionalVolumeMounts:
    - name: my-webclient-data
      mountPath: /var/planta
pulse:
  persistence:
    create: false
  additionalVolumes:
    - name: my-pulse-data
      persistentVolumeClaim:
        claimName: my-company-pulse-pvc
  additionalVolumeMounts:
    - name: my-pulse-data
      mountPath: /app/data

Hinweis: Wenn create: false gesetzt ist, werden PVCs bei der Deinstallation nicht automatisch gelöscht.

Platzierung der Pods (Node Affinity, Tolerations)

manager:
  nodeSelector:
    disktype: ssd
  tolerations:
    - key: "dedicated"
      operator: "Equal"
      value: "planta"
      effect: "NoSchedule"
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: kubernetes.io/zone
            operator: In
            values:
            - zone-1
            - zone-2

Zusätzliche Volumes

manager:
  additionalVolumes:
    - name: custom-config
      configMap:
        name: my-custom-config
  additionalVolumeMounts:
    - name: custom-config
      mountPath: /etc/custom
      readOnly: true

Sitzungsaffinität (Sticky Sessions)

Bei der Skalierung des Web-Clients (oder anderer Komponenten) auf mehrere Replikate stellt die Sitzungsaffinität sicher, dass ein Client immer zum selben Pod geleitet wird. Das Chart unterstützt zwei ergänzende Mechanismen:

Service‑seitige ClientIP‑Affinität

Standardmäßig auf dem Web-Client- und Worker-Service aktiviert. Kube-proxy leitet Datenverkehr von derselben Client-IP an denselben Pod.

webclient:
  service:
    sessionAffinity:
      enabled: true
      timeoutSeconds: 3600

Der Web-Client verbindet sich mit Workern über langlebige TCP-Sockets durch den Worker-Service. Die ClientIP-Affinität auf dem Worker-Service stellt sicher, dass ein Web-Client-Pod (identifiziert durch seine Pod-IP) bei der Wiederverbindung konsistent zum selben Worker-Pod geleitet wird.

Hinweis: Die ClientIP-Affinität kann bei externem Datenverkehr hinter NAT oder Load Balancern weniger wirksam sein, bei denen viele Clients dieselbe Quell-IP teilen.

Skalierungshinweise

• Empfohlen: worker.replicaCount: 1 für Einfachheit und Zuverlässigkeit beibehalten.

• Experimentell: Das Skalieren von Web-Client und Worker auf gleiche Replikat-Anzahl (z. B. beide auf 3) ist möglich. Jeder Web-Client-Pod wird über ClientIP-Affinität an einen Worker-Pod gebunden. Dieser Ansatz hat jedoch Einschränkungen:

  • Die initiale Pod-zu-Pod-Zuweisung ist wahrscheinlichkeitsbasiert und nicht garantiert gleichmäßig verteilt.

  • Pod-Neustarts, Rolling Updates oder Skalierungsereignisse können dazu führen, dass Sitzungen einem anderen Worker zugewiesen werden, was zu Sitzungsverlust führt.

  • Affinitätseinträge werden im Kernel-Speicher abgelegt und sind nicht über Node-Neustarts hinweg persistent.

Ingress‑seitige Cookie‑basierte Affinität (z. B. NGINX)

Für den Browser-Verkehr sind Cookie-basierte Sticky-Sessions zuverlässiger. Diese werden über globale ingress.annotations konfiguriert und gelten für alle Ingress-Ressourcen.

ingress:
  enabled: true
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/affinity-mode: "balanced"
    nginx.ingress.kubernetes.io/session-cookie-name: "PLANTASESSIONID"
    nginx.ingress.kubernetes.io/session-cookie-expires: "3600"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "3600"
    nginx.ingress.kubernetes.io/session-cookie-path: "/"
    nginx.ingress.kubernetes.io/session-cookie-samesite: "Lax"
    nginx.ingress.kubernetes.io/session-cookie-secure: "true"
    nginx.ingress.kubernetes.io/session-cookie-change-on-failure: "true"

Für andere Ingress-Controller (Traefik, HAProxy usw.) passen Sie die Anmerkungen entsprechend an. Die richtigen Anmerkungsschlüssel finden Sie in der Dokumentation Ihres Ingress-Controllers.

Hinweis: Die Cookie-basierte Affinität wird vom Ingress-Controller verarbeitet und hat Vorrang vor der ClientIP-Affinität für externen Datenverkehr. Beide Mechanismen können sicher nebeneinander existieren – die Cookie-Affinität verarbeitet den externen/Browser-Datenverkehr, während ClientIP den internen oder direkten Servicezugriff abdeckt.

Sticky Sessions auf Ingress-Ebene wirken sich nur auf das Routing von Browser → Webclient aus, nicht auf die interne Verbindung von Webclient → Worker (die ClientIP-Affinität auf dem Worker-Service verwendet).

Eigene Ingress-/Route‑Definitionen

Falls Ingress‑Ressourcen extern verwaltet werden sollen (z. B. über GitOps), kann die im Chart eingebaute Ingress‑Erzeugung deaktiviert und eigene Ingress‑Definitionen erstellt werden. Die vom Chart angelegten Services dienen dann als Ziele für diese Ingress‑ oder Route‑Ressourcen.

Gateway API (HTTPRoute)

Als Alternative zu ingress (NGINX/Traefik) und OpenShift route kann das Chart den Manager, den Web-Client und Pulse über die herstellerneutrale Kubernetes Gateway API bereitstellen. Diese verwendet standardmäßige gateway.networking.k8s.io/v1-Ressourcen (Gateway + HTTPRoute) und funktioniert mit jeder konformen Implementierung – Istio, Envoy Gateway, NGINX Gateway Fabric, Cilium, Kong und anderen. Implementierungsspezifische CRDs sind nicht erforderlich.

Die HTTPRoutes verwenden dieselben komponentenspezifischen *.ingress.hosts-Einträge wie die Ingress-Templates, sodass Hostnamen und Pfade unabhängig vom verwendeten Routing-Mechanismus an einer einzigen Stelle konfiguriert werden.

Es darf jeweils nur ein Routing-Mechanismus aktiv sein. Bei Verwendung der Gateway API: ingress.enabled: false und route.enabled: false setzen.

Voraussetzungen (Gateway API)

1. Die Gateway API CRDs (v1.0 oder höher) müssen im Cluster installiert sein:

   CODE

   kubectl get crd gateways.gateway.networking.k8s.io

   Falls nicht vorhanden, installieren (siehe Gateway API-Dokumentation).

2. Eine Gateway API-Implementierung (Controller) muss laufen und eine referenzierbare GatewayClass bereitstellen:

   CODE

   kubectl get gatewayclass

Gateway API aktivieren

Minimale Konfiguration – das Chart erstellt ein Gateway und die HTTPRoutes:

ingress:
  enabled: false
route:
  enabled: false

gateway:
  enabled: true
  create: true
  gatewayClassName: istio   # PFLICHT: Name aus `kubectl get gatewayclass`

manager:
  ingress:
    hosts:
      - host: api.planta.example.com
        paths:
          - path: /api
            pathType: Prefix
            portName: genericService
          - path: /secure
            pathType: Prefix
            portName: secure

webclient:
  ingress:
    hosts:
      - host: planta.example.com
        paths:
          - path: /
            pathType: Prefix

Die Manager-HTTPRoute ordnet jeden Pfad über portName dem entsprechenden Backend-Service-Port zu (dieselben manager.service.ports-Schlüssel wie beim Ingress), sodass mehrere Manager-Ports auf einem einzigen Host bereitgestellt werden können.

An einen vorhandenen (gemeinsamen) Gateway anbinden

In vielen Clustern betreibt ein Plattform-Team einen einzelnen gemeinsamen Gateway. Mit create: false kann dieser referenziert werden, anstatt einen neuen zu erstellen:

gateway:
  enabled: true
  create: false          # kein neues Gateway erstellen
  name: shared-gateway   # Name des vorhandenen Gateways
  namespace: gateway-system   # dessen Namespace (weglassen, falls im Release-Namespace)

Befindet sich das Gateway in einem anderen Namespace, muss es Routen aus dem Release-Namespace über seine allowedRoutes-Konfiguration erlauben (und für Namespace-übergreifende Service-Backends kann je nach Implementierung ein ReferenceGrant erforderlich sein).

TLS

Wenn das Chart das Gateway erstellt, kann durch Referenzieren eines oder mehrerer TLS-Secrets (kubernetes.io/tls) im Namespace des Gateways ein HTTPS-Listener auf Port 443 aktiviert werden:

gateway:
  enabled: true
  create: true
  gatewayClassName: istio
  tls:
    enabled: true
    certificateRefs:
      - name: planta-tls
    # hostname: "*.planta.example.com"   # optional: HTTPS-Listener einschränken

Mit gateway.tls.enabled: true verwenden die in den Post-Install-Hinweisen angezeigten URLs das https-Schema. Bei Anbindung an ein vorhandenes Gateway (create: false) ist TLS direkt an diesem Gateway zu konfigurieren.

Sticky Sessions

Browser → Web-Client-Datenverkehr erfordert Sticky Sessions: Eine PLANTA-Browser-Sitzung ist an einen einzigen Web-Client-Pod gebunden, sodass ein Client, dessen Anfragen auf mehrere Pods verteilt werden, nicht korrekt funktioniert (siehe Sitzungsaffinität). Das Chart setzt cookiebasierte Sitzungspersistenz auf den Web-Client- und Pulse-HTTPRoutes über das Gateway API-Feld sessionPersistence:

gateway:
  sessionPersistence:
    enabled: true
    sessionName: "PLANTASESSIONID"
    absoluteTimeout: "1h"
    cookieLifetimeType: Permanent   # oder Session für ein browsersitzungsbasiertes Cookie

Wichtig: Bei Verwendung der Gateway API den Web-Client (und Pulse) mit nur einem Replikat betreiben, solange sessionPersistence nicht tatsächlich wirksam ist.

Anders als bei Ingress verteilt eine Gateway-Implementierung den Datenverkehr direkt auf Pod-Endpunkte und umgeht den Service – die Service-seitige ClientIP-Affinität gilt daher nicht für Browser-Datenverkehr und bietet auf diesem Pfad keine Stickiness (sie deckt nur internen, cluster-internen ClusterIP-Zugriff ab, z. B. Web-Client → Worker). Das einzige Mittel, das einen Browser an einen Web-Client-Pod bindet, ist das cookiebasierte Feld sessionPersistence.

sessionPersistence gehört zum experimentellen Kanal der Gateway API und ist noch nicht weit verbreitet implementiert:

• Das Standard-Kanal-HTTPRoute-CRD deklariert das Feld nicht. Je nach Apply-Modus wird es entweder abgelehnt (field not declared in schema, serverseitiges Apply – Helm 3.16+/4) oder stillschweigend ignoriert (clientseitiges Apply), sodass es nie wirksam wird.

• Selbst mit installierten Experimental-Channel-CRDs muss die Implementierung GEP-1619 unterstützen. Einige verbreitete Implementierungen tun dies derzeit nicht (z. B. NGINX Gateway Fabric und Envoy Gateway). Prüfung mit: kubectl get gatewayclass <class> -o jsonpath='{.status.supportedFeatures[*].name}'.

Solange die verwendete Implementierung sessionPersistence nicht unterstützt, ist der Betrieb von Web-Client/Pulse hinter dem Gateway mit mehreren Replikaten nicht möglich. Ein Replikat verwenden oder einen implementierungsspezifischen Cookie-Affinitätsmechanismus außerhalb dieses Charts konfigurieren (z. B. eine Envoy Gateway BackendTrafficPolicy mit Consistent-Hash-Cookie).

Pro-Route-Anfrage-Timeouts werden auf alle HTTPRoute-Regeln angewendet und können angepasst (oder durch Setzen auf "" deaktiviert) werden:

gateway:
  timeouts:
    request: "30s"
    backendRequest: "30s"

Zugriff auf Worker-Port von außerhalb des Clusters (Development / Troubleshooting)

Warnung: Verwenden Sie dies NICHT in der Produktion. In der Produktion sollte der native PLANTA .NET-Client eine Verbindung über PLANTA secure (Port 8181 auf dem Manager) herstellen, das eine ordnungsgemäße TLS-Verschlüsselung bietet. Das Öffnen des rohen Worker-TCP-Ports nach außen ist nur für lokale Entwicklungs- oder Fehlerbehebungsszenarien geeignet.

Der native PLANTA .NET-Client kommuniziert mit dem Worker über eine Raw-TCP-Verbindung auf dem Sitzungsport des Workers. Standardmäßig ist dieser Port nur von innerhalb des Clusters zugänglich. Um von außerhalb des Clusters (z. B. von einer Entwickler-Workstation) darauf zuzugreifen, können Sie einen zusätzlichen NodePort oder LoadBalancer aktivieren:

worker:
  service:
    external:
      enabled: true
      type: NodePort
      nodePort: 30001  # leave empty for a Kubernetes-assigned port

Wenn diese Option aktiviert ist, wird neben dem bestehenden internen ClusterIP-Dienst ein zusätzlicher Dienst mit dem Namen <release>-worker-external erstellt. Der interne Dienst bleibt davon unberührt.

LoadBalancer-Beispiel (z. B. für Cloud-Anbieter):

worker:
  service:
    external:
      enabled: true
      type: LoadBalancer
      externalTrafficPolicy: Local
      # loadBalancerIP: "1.2.3.4"  # optional static IP

Rufen Sie nach der Bereitstellung den zugewiesenen Port oder die IP-Adresse ab:

kubectl get svc <release>-worker-external -n planta

Komponenten deaktivieren

pulse:
  enabled: false

webclient:
  enabled: false

Customizing‑Deployments (Export/Import)

PLANTA unterstützt das Customizing‑Deployments (Änderungen, die zwischen Umgebungen durch den Export und Import übertragen werden können (z. B. von einem Entwicklungssystem in die Produktion) über einen separaten Kubernetes‑Job auf Basis des Manager‑Images. Ein Beispiel für eine Jobdefinition finden Sie in der cu-deployment-example.yaml. Kopieren Sie diese Datei als Ausgangspunkt und passen Sie sie an Ihre Umgebung an.

Ausführliche Beschreibung zu Kundecustomizing-Deployment finden Sie hier.

Voraussetzungen

• Laufende PLANTA‑Installation mit erreichbarer Datenbank

• PLANTA-Registry‑Zugriff für das Manager‑Image

• Gemeinsames Volume für .par‑ und .zip‑Dateien

• Datenbank‑Zugangsdaten (möglichst über Secret; siehe secret-example.yaml)

Wichtig: Der Customizing Deployment Job stellt eine direkte Verbindung zur Datenbank her. Stellen Sie sicher, dass während des Exports oder Imports keine konkurrierenden Vorgänge auf derselben Datenbank ausgeführt werden.

So funktioniert es

Vorgehensweise:

1. Der Job führt den PLANTA Manager-Container mit einem speziellen Export- oder Importargument aus. Der Container:

2. Stellt mithilfe der bereitgestellten Anmeldedaten eine Verbindung zur Datenbank her.

3. Liest die .par-Datei, in der festgelegt ist, welche Anpassungsobjekte exportiert oder importiert werden sollen.
   Schreibt eine exportierte .zip-Datei auf das gemountete Volume (Exportmodus) oder liest eine .zip-Datei und wendet sie auf die Datenbank an (Importmodus).

4. Beendet den Vorgang nach Abschluss – Kubernetes markiert den Job als erfolgreich oder fehlgeschlagen.

Job anwenden:

kubectl apply -f cu-deployment.yaml -n IHR_NAMESPACE

Job überwachen:

# Check job status
kubectl get jobs -n YOUR_NAMESPACE

# Follow the job logs
kubectl logs job/cu-deployment -n YOUR_NAMESPACE -f

Der Job ist wie folgt konfiguriert:

• 30-minütige Zeitüberschreitung (activeDeadlineSeconds: 1800) – der Job wird beendet, wenn diese Dauer überschritten wird

• Keine Wiederholungsversuche (backoffLimit: 0) – ein fehlgeschlagener Lauf wird nicht automatisch wiederholt

• Automatische Bereinigung nach 1 Stunde (ttlSecondsAfterFinished: 3600) – die abgeschlossene/fehlgeschlagene Job-Ressource wird automatisch entfernt

Um den Job erneut auszuführen, löschen Sie zunächst den vorherigen Job:

kubectl delete job cu-deployment -n YOUR_NAMESPACE
kubectl apply -f cu-deployment.yaml -n YOUR_NAMESPACE

• Verwenden Sie Secrets für Anmeldedaten in der Produktion. Vermeiden Sie es, Datenbankpasswörter direkt in die Job-YAML einzufügen. Erstellen Sie stattdessen ein Secret (siehe secret-example.yaml) und verweisen Sie darauf über envFrom.secretRef.

• Sichern Sie Ihre Datenbank vor dem Ausführen eines Imports, insbesondere in Produktionsumgebungen.

• Die .par-Datei muss innerhalb des Containers unter dem in args angegebenen Pfad zugänglich sein. Sie muss in dem Verzeichnis abgelegt werden, das unter /var/planta/export/ gemountet ist.

• Volume-Typ: Das Beispiel verwendet hostPath, das für Single-Node-Cluster und lokale Entwicklung geeignet ist. Verwenden Sie für Produktions- oder Multi-Node-Cluster einen geeigneten Volume-Typ (z. B. NFS, PersistentVolumeClaim oder cloudspezifischer Speicher).

• Image-Tag: Aktualisieren Sie das Image-Feld entsprechend der PLANTA-Version Ihrer Installation.

Fehlerbehebung

Pods starten nicht

kubectl get pods -n planta
kubectl describe pod <pod-name> -n planta
kubectl logs <pod-name> -n planta

Typische Ursachen:

• ImagePullBackOff: ImagePullSecret oder Registry‑Zugang prüfen.

• CrashLoopBackOff: Anwendungslogs auf Fehler prüfen.

• Pending: Ressourcenmangel oder Probleme bei PVC‑Binding prüfen.

Datenbankverbindung schlägt fehl

Überprüfen Sie die Datenbankverbindung:

kubectl logs -n planta deployment/my-planta-manager
kubectl run -it --rm debug --image=busybox \
  --restart=Never -n planta -- sh
# innerh. Container:
# telnet datenbank-host 1521

Probleme mit Persistent Volumes

PVC-Status überprüfen:

kubectl get pvc -n planta
kubectl describe pvc <pvc-name> -n planta
kubectl get storageclass

Wenn PVCs ausstehen, stellen Sie Folgendes sicher:

• Speicherklasse existiert: kubectl get storageclass

• Ausreichend Speicherplatz verfügbar

• Zugriffsmodus wird unterstützt (insbesondere ReadWriteMany)

Ingress funktioniert nicht

kubectl get ingress -n planta
kubectl describe ingress <ingress-name> -n planta

Prüfen Sie, ob

• ein Ingress‑Controller läuft

• DNS korrekt gesetzt ist und

• ggf. TLS‑Zertifikate gültig sind

Aktuelle Helm‑Werte anzeigen

helm get values my-planta -n planta

oder

helm get values my-planta -n planta --all