ZETA-Guard Helm Chart Referenz

Hier folgt eine Referenzdokumentation der wichtigsten Values des Helm Charts. Als vollständige Vorlage mit Standardwerten dient die values-demo.yaml.

Inhaltsverzeichnis

Authserver

ServiceAccount

Für den Authserver wird standardmäßig ein dedizierter ServiceAccount erzeugt, der den automatischen Token-Mount deaktiviert:

zeta-guard:
    authserver:
        serviceAccount:
            create: true
            name: authserver

Setzen Sie create: false, um einen bereits bestehenden ServiceAccount zu nutzen.

Replicas und PodDisruptionBudget 

zeta-guard:
    authserver:
        replicaCount: 2
        podDisruptionBudget:
            enabled: true
            minAvailable: 1

Das PodDisruptionBudget ist standardmäßig deaktiviert. Es kann entweder minAvailable oder maxUnavailable konfiguriert werden, aber nicht beides gleichzeitig.

Ressourcen

Ressourcen werden separat für den Hauptcontainer ( authserver.container.resources) und den Keycloak-Build-Init-Container (authserver.initContainer.resources) konfiguriert. Der Provisioning-Processor-Init-Container ist ein gemeinsamer Container und wird separat unter provisioningProcessor.* konfiguriert (siehe unten und Wie Sie Ressourcen für ZETA-Guard-Pods verwalten):

zeta-guard:
    authserver:
        container:
            resources:
                limits:
                    cpu: "8"
                    memory: "4Gi"
                requests:
                    cpu: "4"
                    memory: "4Gi"
        initContainer:
            resources:
                limits:
                    cpu: "2"
                    memory: "2Gi"
                requests:
                    cpu: "500m"
                    memory: "512Mi"

Security Contexts

Pod- und Container-Security-Contexts sind konfigurierbar:

zeta-guard:
    authserver:
        podSecurityContext:
            seccompProfile:
                type: RuntimeDefault
        container:
            containerSecurityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: true
                runAsNonRoot: true
                capabilities:
                    drop: [ "ALL" ]
        initContainer:
            containerSecurityContext:
                allowPrivilegeEscalation: false
                readOnlyRootFilesystem: false
                runAsNonRoot: true
                capabilities:
                    drop: [ "ALL" ]

Hinweis: runAsUser wird standardmäßig nicht gesetzt, da OpenShift dies nicht unterstützt.

Probes

Die Parameter für Liveness-, Readiness- und Startup-Probes sind konfigurierbar:

zeta-guard:
    authserver:
        probes:
            liveness:
                initialDelaySeconds: 0
                periodSeconds: 15
                failureThreshold: 5
            readiness:
                initialDelaySeconds: 30
                periodSeconds: 10
                failureThreshold: 5
            startup:
                initialDelaySeconds: 30
                periodSeconds: 10
                failureThreshold: 20

Admin-API-Absicherung

Die Keycloak Admin REST API und die Admin Console (/auth/admin/*) dürfen nicht über den öffentlichen Hostnamen zugänglich sein. Das Helm Chart unterstützt eine integrierte Absicherung über einen separaten Admin-Hostnamen.

Wenn authserver.adminHostname gesetzt ist, aktiviert das Chart zwei Schutzschichten:

  1. PEP-Proxy blockiert /auth/admin — ein location ~ ^/auth/admin-Block im NGINX-PEP gibt 403 Forbidden zurück, bevor die Anfrage Keycloak erreicht. Alle anderen /auth/*-Pfade (Token-Exchange, Well-Known-Endpunkte) werden ohne PEP-Token-Prüfung an den Authserver weitergeleitet.
  2. Separater Admin-Ingress — für den Admin-Hostnamen werden zwei zusätzliche Ingress-Ressourcen erzeugt, die /auth direkt an den Authserver routen (unter Umgehung des PEP-Proxy-Blocks). Terraform und CI/CD-Runner verwenden ausschließlich diesen Hostnamen.

Die Absicherung ist ingress-controller-unabhängig und funktioniert mit F5 NIC, Standard-nginx-Ingress, OpenShift Routes, GKE Ingress und anderen Controllern, da die Enforcement im PEP-Proxy stattfindet.

zeta-guard:
    authserver:
        hostname: "zeta.example.com"
        # Separater Hostname für den Keycloak-Admin-Zugriff.
        # Wenn gesetzt, wird /auth/admin auf dem Haupthostnamen über den PEP-Proxy
        # gesperrt und ein dedizierter Admin-Ingress für diesen Hostnamen erzeugt.
        adminHostname: "admin.zeta.example.com"

Für Umgebungen, in denen kein ClusterIssuer für den Admin-Hostnamen verfügbar ist (z.B. KIND), kann ein bestehendes TLS-Secret wiederverwendet werden:

zeta-guard:
    authserver:
        adminTlsSecretName: "zeta-guard-tls"  # bestehendes Secret wiederverwenden

Um die Funktion zu deaktivieren, entfernen Sie adminHostname (oder setzen Sie es auf "") und führen Sie helm upgrade aus. Der Admin-Ingress und die PEP-Proxy-Location-Blöcke werden automatisch entfernt.

Einschränkung: Wenn routeViaTigerProxy: true gesetzt ist, hat die Admin-API-Absicherung keine Wirkung, da Tiger-Proxy /auth intern direkt an den Authserver weiterleitet und die PEP-Proxy-Location-Blöcke umgeht. Tiger-Proxy ist ausschließlich ein Testwerkzeug und wird in Produktionsdeployments nicht eingesetzt.

IP-basierte Zugriffsbeschränkung für den Admin-Hostnamen muss auf Infrastrukturebene konfiguriert werden: Cloud Armor (GKE), NetworkPolicy/Route-Annotation (OpenShift) oder Firewall-Regeln. Das Chart erzwingt keine IP-basierte Zugriffsbeschränkung.

CloudNativePG-Datenbankverbindung

Im Datenbankmodus cloudnative sind JDBC-URL, Secret-Name und Schema konfigurierbar:

zeta-guard:
    databaseMode: cloudnative
    cloudnativeDbUrl: "jdbc:postgresql://keycloak-db-rw:5432/keycloak"
    cloudnativeDbSecretName: "keycloak-db-app"
    cloudnativeDbSchema: "public"

Die Standardwerte verweisen auf den vom CloudNativePG-Operator erzeugten Service und das zugehörige Secret. Passen Sie diese an, wenn Sie eine abweichende Datenbankinstanz verwenden.

HSM-Konfiguration

HSM-Integration für TLS und Token-Signierung:

zeta-guard:
    authserver:
        hsm:
            enabled: false                                          # HSM-Proxy-Anbindung aktivieren
            endpoint: "hsm-proxy:50051"                             # gRPC-Endpunkt des HSM-Proxy
            tls:
                enabled: false                                      # Pod-Level TLS via HSM
                keyId: "zeta-guard-keycloak-tls-es256-v1.p256"      # Schlüssel-ID für TLS
            tokenSigning:
                enabled: false                                      # HSM_PROXY_TOKEN_KEY_ID setzen
                keyId: "zeta-guard-keycloak-token-es256-v1.p256"    # Schlüssel-ID für Token-Signierung
Value Beschreibung Standard
authserver.hsm.enabled HSM-Proxy-Anbindung aktivieren (setzt HSM_PROXY_ENDPOINT) false
authserver.hsm.endpoint gRPC-Endpunkt des HSM-Proxy ""
authserver.hsm.tls.enabled Pod-Level TLS mit HSM-Schlüssel false
authserver.hsm.tls.keyId Schlüssel-ID für TLS im HSM ""
authserver.hsm.tokenSigning.enabled Token-Signierung via HSM (setzt HSM_PROXY_TOKEN_KEY_ID) false
authserver.hsm.tokenSigning.keyId Schlüssel-ID für Token-Signierung im HSM ""

Hinweis: Die Helm-Values aktivieren die HSM-Proxy-Verbindung im Authorization Service (Keycloak). Die Registrierung des HSM-KeyProviders im Keycloak-Realm erfolgt separat über Terraform (siehe Quickstart – PDP konfigurieren) mit den Variablen hsm_token_signing_enabled, hsm_token_signing_endpoint und hsm_token_signing_key_id.

PEP-Proxy

ServiceAccount 

zeta-guard:
    pepproxy:
        serviceAccount:
            create: true
            name: pep-proxy

Security Context 

zeta-guard:
    pepproxy:
        podSecurityContext:
            seccompProfile:
                type: RuntimeDefault

Infinispan

Infinispan wird über globale Values konfiguriert und kann entweder als In-Cluster-Deployment oder als Verbindung zu einer externen Instanz genutzt werden (siehe auch Wie Sie externen Infinispan konfigurieren).

Image 

global:
    infinispanExternal:
        image:
            repository: infinispan/server
            tag: "15.2"

ServiceAccount 

global:
    infinispanExternal:
        serviceAccount:
            create: true
            name: infinispan

PodDisruptionBudget 

global:
    infinispanExternal:
        podDisruptionBudget:
            enabled: true
            minAvailable: 1

Security Contexts 

global:
    infinispanExternal:
        podSecurityContext:
            seccompProfile:
                type: RuntimeDefault
        containerSecurityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: false
            runAsNonRoot: true
            capabilities:
                drop: [ "ALL" ]

JVM-Optionen

Zusätzliche JVM-Optionen können über extraJavaOptions konfiguriert werden. Die Basis-Optionen für JGroups-Clustering werden automatisch gesetzt.

global:
    infinispanExternal:
        extraJavaOptions: "-XX:MaxRAMPercentage=75.0 -XX:InitialRAMPercentage=50.0"

Provisioning Processor

Der Provisioning Processor ist ein gemeinsamer Init-Container, der von Authserver, OPA, OPA-Simulation und PEP-Proxy verwendet wird:

zeta-guard:
    provisioningProcessor:
        resources:
            limits:
                cpu: "1"
                memory: "200Mi"
            requests:
                cpu: "100m"
                memory: "100Mi"
        containerSecurityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: false
            runAsNonRoot: true
            capabilities:
                drop: [ "ALL" ]

Eigene Registry für den Provisioning Container

Standardmäßig lädt der Provisioning Processor das Daten-Image von der gematik-Registry. Für Umgebungen ohne direkten Internetzugang kann eine eigene Registry-Spiegelung konfiguriert werden:

zeta-guard:
    provisioningProcessor:
        provisioningContainer: "my.registry.corp.internal/zetaguard-provisioning:latest"

Hinweis: Das gespiegelte Image muss zusammen mit seiner cosign-Signatur übertragen werden. Ein einfaches docker pull/push überträgt die Signatur nicht. Siehe Wie Sie eine eigene OCI Registry verwenden.

CA-Zertifikat für die Provisioning-Container-Registry

Wenn die Registry ein TLS-Zertifikat verwendet, das von einer internen CA ausgestellt wurde, muss das CA-Zertifikat dem Init-Container mitgegeben werden. Das Zertifikat wird aus einem Kubernetes Secret als Datei in den Init-Container gemountet. Diese Variante vermeidet das Kernel-Limit ARG_MAX, das bei der Übergabe von Zertifikatsketten als Umgebungsvariable überschritten werden kann.

zeta-guard:
    provisioningProcessor:
        provisioningContainerCaSecretRef:
            name: registry-ca        # Name des Kubernetes Secrets
            key: ca.crt              # Key innerhalb des Secrets

Cosign-Vertrauenskette für Image-Verifikation

Der Helm Value imageTrustCertchainSecretRef benennt ein Kubernetes Secret, das die CA-Zertifikatskette der gematik enthält. Der Provisioning Processor prüft damit die cosign-Signatur des Provisioning-Daten-Images beim Pod-Start.

Das Secret muss den Key certchain.pem mit einer PEM-kodierten X.509-Zertifikatskette enthalten (CA- und Zwischenzertifikate, kein Leaf-Zertifikat). Es wird als Volume image-trustchain in den Init-Container des Provisioning Processors jedes der folgenden Deployments eingebunden: Authserver, PEP-Proxy, OPA und OPA-Simulation. Der Pfad im Container lautet /var/image-trustchain/certchain.pem (Umgebungsvariable TRUST_CERTCHAIN_FILE).

Pflichtfeld: Das Helm Chart bricht beim Rendern mit einem Fehler ab, wenn imageTrustCertchainSecretRef nicht gesetzt ist.

zeta-guard:
    imageTrustCertchainSecretRef: my-image-signer

Das Secret wird typischerweise so angelegt:

kubectl create secret generic my-image-signer \
  --from-file=certchain.pem=/path/to/gematik-certchain.pem \
  --namespace NAMESPACE

Die Zertifikatskette ist von der gematik zu beziehen. Für Testumgebungen enthält das Helm Chart im Verzeichnis templates/ ein vorgefertigtes Secret gematik-image-signer-test mit den Testzertifikaten GEM.KOMP-CA61 und GEM.RCA7 (jeweils TEST-ONLY). Der Standardwert in values-demo.yaml verweist auf dieses Test-Secret.

Wichtig: Das Test-Secret gematik-image-signer-test enthält Testzertifikate und darf nicht in Produktivumgebungen verwendet werden. Für den Produktivbetrieb muss das Secret mit den von der gematik bereitgestellten Produktivzertifikaten befüllt werden.

Terraform-Konfiguration (PDP)

Die PDP-Konfiguration erfolgt über Terraform. Zu den wichtigsten Variablen gehört:

Variable Standard Beschreibung
use_kubernetes true Terraform-Betriebsmodus (true = K8s-Backend, false = lokal)
keycloak_url — Externe URL des Keycloak-Servers (bei Admin-API-Absicherung: URL des Admin-Hostnamens)
keycloak_namespace — Kubernetes-Namespace des Authservers
pdp_scopes [] Zusätzliche PDP-Scopes
audience_scope_name "zero:audience" Name des Audience-Scopes
audience "" Expliziter Audience-Wert im Access Token. Erforderlich, wenn keycloak_url auf einen Admin-Hostnamen zeigt (siehe unten).
insecure_tls false Selbst signierte Zertifikate zulassen

Wenn adminHostname gesetzt ist und keycloak_url auf den Admin-Hostnamen zeigt, muss audience explizit auf den öffentlichen Haupthostnamen gesetzt werden — andernfalls würde der Audience-Wert aus der URL abgeleitet und stimmte nicht mit dem überein, was die Access Tokens tragen:

keycloak_url = "https://admin.zeta.example.com/auth"
audience     = "https://zeta.example.com"

Details zu den Terraform-Betriebsmodi finden sich im Quickstart.

This site uses Just the Docs, a documentation theme for Jekyll.