Wie Sie ZETA-Guard in einem Kubernetes-Cluster installieren und konfigurieren

Status: In Arbeit

Zielgruppe: Systemadministratoren der Anbieter

Inhalt: Beschreibung der erforderlichen Hardware und Software, mögliche Betriebssysteme und -Versionen, vorausgesetzte Software-Umgebung wie etwa Standardbibliotheken und Laufzeitsysteme. Erläuterung der Prozeduren zur Installation, außerdem zur Pflege (Updates) und De-Installation, bei kleinen Produkten eine Readme-Datei. Zielgruppe sind Administratoren beim Anwender, die die Software nicht zwangsläufig unmittelbar selbst nutzen müssen.

[TOC]

Überblick

Abbildung Zero Trust-Architektur der TI 2.0

Voraussetzungen

  • ein Kubernetes-Cluster
    • mindestens in Version 1.32 (entspr. OpenShift 4.19 oder neuer)
    • in dem sich Resource Server und Application Authorization Backend befinden
    • mit einem Ingress-Controller
    • mit Zugang zu einer anbietereigenen Container Registry
      • für den Testbetrieb kann in Absprache mit der gematik direkt die Container Registry der gematik verwendet werden
    • Persistent Volumes mit AccessMode ReadWriteOnce müssen verfügbar sein
    • Netzwerkzugang zu diversen externen Diensten (siehe Egress konfigurieren)
    • eine geeignete Imagesignaturprüfung z.B. via Kyverno (signierte Images kommen in späterem Meilenstein)
    • mit Gateway API CRDs
  • eine lokale, cachende OCI Registry
  • alle Dienste aus der Liste der Abhängigkeiten unten
  • einen OpenTelemetry-Collector

Optionale Voraussetzungen:

  • Falls der ZETA eigene Ingress Controller nicht verwendet wird: ein geeigneter Ingress Controller
  • Falls das ZETA eigene Service Mesh nicht verwendet wird: eine alternative Lösung die TLS Kommunikation der ZETA Komponenten untereinander sicherstellt

Überblick über die Konfiguration des ZETA Guard

Zentraler Dreh- und Angelpunkt der Konfiguration und auch Installation des ZETA Guard ist das ZETA Guard Helm Chart. Zusätzlich relevant sind die PDP Terraform Templates, welche für diverse Konfiguration des PDP relevant sind und in dieser Hinsicht das Helm Chart begleitet. Diese beiden Konfigurationswerkzeuge gehören praktisch mit zum ZETA Guard und werden ebenfalls in Updates des ZETA Guard gepflegt.

Nicht zu verwechseln mit den PDP Terraform Templates sind die optionalen Terraform Templates zum beispielhaften Aufsetzen eines geeigneten Kubernetes Clusters.

Empfehlungen für das Konfigurationsmanagement

  • Bauen Sie ihr eigenes Helm Chart, welches das ZETA Guard Helm Chart als Subchart nutzt. So können Sie Anpassungen an Ihre eigenen Bedürfnisse und Infrastruktur konsistent managen.
  • Setzen Sie einen CD Server in Verbindung mit einem Versionskontrollsystem für die Konfigurationsdateien ein (→ GitOps). Der ZETA Guard beinhaltet zukünftig als optionale Komponente einen ArgoCD.

Vorgehen bei der Installation

Letztlich besteht die Installation aus den 2 Schritten helm upgrade --install und terraform apply, wie im Quickstart beschrieben. Damit sind dann alle Komponenten des ZETA Guard installiert.

Im Folgenden soll auf die Konfiguration der einzelnen Komponenten etwas mehr im Detail eingegangen werden. Ergänzend dazu gibt es die Referenzdokumente.

Übersicht zu den wichtigsten Konfigurationsparametern der einzelnen Komponenten

1. Ingress-Controller und Ingress konfigurieren

In dem Cluster muss ein Ingress-Controller installiert sein und erlaubter Ingress definiert werden. Das ZETA Guard Helm Chart beinhaltet einen optionalen Ingress Controller ( F5 nginx-ingress ). Über die values kann dieser an- bzw. abgewählt werden (nginx-ingress.enabled: false).

Der eingesetzte Ingress Controller muss die Kubernetes APIs für Ingresses und Gateways unterstützen.

Die Verwaltung der TLS Zertifikate obliegt dem Anbieter und erfolgt in der Regel über Kubernetes Secrets oder eine HSM Anbindung.

Bei Verwendung von mehreren ZETA Guard in unterschiedlichen Namespaces ist es möglich, über ingress classes die Ingress Controller der jeweiligen Installationen voneinander zu isolieren. Hierfür müssen die values ingressClassName und nginx-ingress.controller.ingressClass.name auf denselben jeweils für die Installation einzigartigen Namen gesetzt werden (sinnvollerweise enthält dies den Namen des Namespace).

Es folgt hier in späteren Releases noch die Möglichkeit, die Ingressressourecen insb. über Annotationen für andere IngressController besser nutzbar zu machen.

2. Egress konfigurieren

Egresses werden über Kubernetes Network-Policies kontrolliert. Das ZETA Guard Helm Chart wird einige universell für alle ZETA Guards benötigte Network Policies beinhalten. Weitere Fachdienstabhängige Network Policies, z.B. für die Kommunikation mit einem anderen Fachdienst und dessen ZETA Guard, obliegen dem Anbieter.

Bekannte, valide Egress Ziele außerhalb des Clusters sind insbesondere:

  • Momentan werden manche Images (z.B. OPA) noch von docker.io bezogen. Dies soll in Zukunft konfigurierbar gestaltet werden, um eine eigene Registry verwenden zu können.
  • Aufrufende Clients (Responses)
  • TI Dienste
    • OCSP Responder der TI TSL (! d.h. der Responder im Internet nicht der im TI 1.0 Netz)
    • TI-Monitoring
    • TI-SIEM
    • Federation Master
    • Federated IDP bzw. Sektorale IdPs
  • ZETA spezifische TI Dienste
    • ZETA Container-Registry
    • ZETA PIP & Service
  • anbietereigene Dienste
    • Dienstanbieter-Monitoring
    • Dienstanbieter-SIEM
    • Diensthersteller-Monitoring
  • weitere Dienste
    • Clientsystem Notification Service(s) – Apple Push Notifications, Firebase
    • Email Confirmation-Code – Mailversand
    • im Testbetrieb zu dockerhub

3. Management Service (ArgoCD) installieren und konfigurieren

Die Verwendung des Management Service ist optional und das ZETA Guard Helm Chart beinhaltet einen optionalen Ingress Controller. Über die values kann dieser an- bzw. abgewählt werden (management_service.enabled: true).

  • Kommt mit späterem Meilenstein
  • To-Do: Sidecar Container mit OpenTelemetry Collector
  • Ggf. mit Zugang zur UI für Administratoren einrichten

Verwandte Dokumentation

4. Telemetriedaten Service (OpenTelemetry Collector) konfigurieren

Zunächst erfassen Komponenten-spezifische Collector-Instanzen Telemetriedaten. Ein zentraler Collector – das Telemetry-Gateway – bündelt und filtert diese, bevor sie an die Monitoring- und SIEM-Dienste der TI weitergeleitet werden.

Um eigene Observability-Backends anzuschließen, empfehlen wir einen eigenen OpenTelemetry-Collector einzurichten, der den Fanout an Ihre Observability-Backends (wie etwa Prometheus, OpenSearch und Jaeger) vornimmt. Ferner empfehlen wir Collectoren über das OpenTelemetry Protocol (OTELP) kommunizieren zu lassen, da es alle Signalarten (Logs, Metriken, und Traces) übertragen kann und der dafür notwendige Receiver in allen offiziellen Distributionen enthalten ist.

Der Telemetriedaten Service ist Teil des zeta-guard-Charts, und ist standardmäßig eingeschaltet – benötigt jedoch eine valide Zieladresse für seinen OTELP-Exporter. Sie können die Konfiguration des Exporters wie folgt überschreiben:

telemetry-gateway:
    config:
        exporters:
            otlp/observability-backends:
                endpoint: <Adresse Ihres OTELP-Receivers>

Bitte beachten Sie, dass telemetry-gateway.config ein direktes Fenster in die Konfiguration des Collectors ist, und Sie bei Bedarf weitere Exporter hinzufügen und existierende deaktivieren können:

telemetry-gateway:
    config:
        exporters:
            otlp/observability-backends:
                endpoint: <Adresse Ihres OTELP-Receivers>
                tls: ...
            otlp/gematik:
                endpoint: <Adresse des gematik-OTELP-Receivers>
                tls: ...
        service:
            pipelines:
                logs:
                    exporters: [ debug, otlp/observability-backends, otlp/gematik ]
                metrics:
                    exporters: [ debug, otlp/observability-backends, otlp/gematik ]
                traces:
                    exporters: [ debug, otlp/observability-backends, otlp/gematik ]

Das Telemetry-Gateway verwendet die Distribution opentelemetry-collector-k8s (latest). Hier finden sie das Manifest mit allen Exportern, die Sie verwenden können.

  • To-do: als Kubernetes Sidecar Container für jede Komponente
  • To-do: Telemetriedatentransfer an gematik einrichten
  • To-do: Telemetriedatentransfer mit TLS und Authentifizierung absichern

Verwandte Dokumentation

Abhängigkeiten / erforderliche Konfiguration

  • Muss wahrscheinlich die Adressen der Open-Telemetrie-Endpunkte kennen, von denen er Telemetrie-Daten einsammeln soll
  • Muss ggf. die Adresse des nächsten Telemetrie-Dienstes in der Kette kennen

5. Notification Service konfigurieren

  • Kommt erst in Umsetzungsstufe 2

Abhängigkeiten / erforderliche Konfiguration

  • APN-Konfiguration (Apple Push Notification)
  • Firebase-Konfiguration (Android Push Notification)

6. Policy Decision Point konfigurieren

6.1 PDP Datenbank (PostgreSQL) installieren und konfigurieren

Keycloak benötigt eine PostgreSQL-Datenbank die aktuell in Form des Zalandos Postgres-Operator installiert werden sollte. (Für größere Deploymentszenarien mit Multicluster ggf. abweichend).

Als Anschauungsbeispiel kann das entsprechende Terraform Template herangezogen werden. Zukünftig wird dieser Teil ggf. noch in das ZETA Guard Helm Chart integriert.

Die Datenbank wird als Active-Passive eingesetzt. Durch den gut abgestimmten Einsatz eines verteilten 2nd level Datenbankcaches im PDP skaliert dies trotzdem gut.

To-do: Sidecar Container mit OpenTelemetry Collector

6.2 Policy Engine (OPA) konfigurieren

Jede OPA-Instanz muss Policys vom PIP abfragen und Metriken für seinen OpenTelemetry Collector bereitstellen.

Zur Veranschaulichung dienen Deployment- und Service-Definitionen in folgendem Helm-Chart als Beispiel.

OPA kann horizontal skaliert werden (-> helm values).

  • _To-do: Skalierung
Verwandte Dokumentation
Abhängigkeiten / erforderliche Konfiguration
  • PIP stellt Policy Bundles und Bundle Signer Zertifikate bereit

6.3 Authorization Service (Keycloak) konfigurieren

Keycloak muss mit seiner Datenbank und seinem OPA verbunden sein, einen eigenen Open Telemetry Collector besitzen und von außerhalb des Clusters erreichbar sein.

Die Installation erfolgt über den Helm-Chart. Zusätzlich zur Konfiguration im Helm Chart erfolgt ein großer Teil der Konfiguration zur Laufzeit des deployten Keycloak und wird mittels Terraform vorgenommen.

Der Authorization Service kann horizontal skaliert werden (→ helm values). Ab 4 Knoten ist ein Tuning des Keycloak internen Infinispan Caches angeraten.

  • To-do: Sidecar Container mit OpenTelemetry Collector
Abhängigkeiten / erforderliche Konfiguration
  • Der externe Hostname muss konfiguriert werden:
    • in helm via authserver.hostname=auth.example.com.internal
    • in Terraform via
      • keycloak_url = "https://zeta-dev.westeurope.cloudapp.azure.com/auth"
Datenbankverbindung und Benutzer-Credentials für die PDP Datenbank

Das Helm Chart unterstützt einen Datenbankmodus für Testsetups mit einer Postgres über ein Legacy Bitnami Helm Chart und einen produktivtauglichen Modus aufbauend auf einem existierenden Zalando Postgres Operator.

Für die Verwendung des Operator ist databaseMode: operator als helm value zu setzen. Weitere Konfiguration ist dann nicht erforderlich, es wird dann über das Helm Chart vom Operator eine Datenbank angefordert und der Keycloak passend konfiguriert.

Es ist möglich, eine externe Datenbank für den PDP zu konfigurieren. Dazu ist einerseits databaseMode: external zu setzen. Anderseits werden untenstehende Helm Values eingerichtet, die entsprechend den Keycloak Umgebungsvariablen für diesen Zweck verwendet werden. Siehe dazu hier.

Helm Value Keycloak Entsprechung Bemerkung
authserverDb.kcDb KC_DB  
authserverDb.kcDbUrl KC_DB_URL  
authserverDb.kcDbUsername KC_DB_USERNAME  
authserverDb.kcDbPasswordSecretName KC_DB_PASSWORD Hierbei ist im Helm Value der Name eines Secrets zu konfigurieren. Aus dem Secret wir das Feld password ausgelesen und dieses in die entsprechende Keycloak Umgebungsvariable geschrieben.
authserverDb.kcDbSchema KC_DB_SCHEMA  
Verwandte Dokumentation

7. Policy Enforcement Point (nginx) konfigurieren

Zur Veranschaulichung der Installation und Konfiguration des HTTP-Proxys eignet sich die Deployment-Definition in diesem Helm-Chart.

Für die korrekte Funktion des PEP sind folgende Konfigurationswerte entscheidend:

  • Issuer URL des Authorization Server pepproxy.nginxConf.pepIssuer. Diese ergibt sich normalerweise aus dem öffentlichen Hostnamen des Authorization Server nach dem Muster https://<authserver_name>/auth/realms/zeta-guard
  • Öffentliche URL des PEP. Diese fließt in das Well-Known Discovery Dokument im Value pepproxy.wellKnownBase ein nach folgendem Muster: https://<pep_name>
  • Konfiguration des Fachdienst Resource Server über den Helm Value pepproxy.nginxConf.locations. Dieser wird mit nginx location Blöcken welche proxy_pass auf den Fachdienst Resource Server nutzen eingerichtet. Wichtig sind hierbei in den Locations folgende 2 Direktiven:
    • pep on; damit sich der HTTP Proxy hier wie ein PEP verhält
    • pep_require_aud https://<pep_name> <other_audiences_here>; zur Validierung der geforderten und mit der gematik abgestimmten Audiences (die gematik muss diese in zentrale Policys für den OPA integrieren).
    • Eventuelle Konfiguration für WebSockets findet hier mit nginx Standardmethoden statt.
  • Für die Verwendung von ASL muss der Value pepproxy.asl_enabled auf true gesetzt werden.
    • ASL Zertifikate werden momentan bei Serverstart generiert. Zukünftig werden diese via Kubernetes Secrets bereitgestellt oder in der VAU via HSM verfügbar gemacht
  • kommt noch
    • To-do: Horizontale Skalierung via Helm Values verfügbar machen

8. Servie Mesh konfigurieren

Hier sei beschrieben, wie Istio im ambient mode installiert wird um mTLS für service-zu-service Kommunikation im Kubernetes Cluster für den ZETA Guard, zu installieren.

Es wird hier davon ausgegangen, dass das ZETA Guard Helm Chart bereits installiert ist.

0) falls noch nicht geschehen, istioctl auf dem Admin Rechner Installieren ( siehe diese Anweisungen )

1) installieren der Kubernetes Gateway API CRDs, falls nicht schon vorhanden - kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/experimental-install.yaml

2) installieren von Istio Using mit Ambient Profil - istioctl install --set profile=ambient --skip-confirmation

3) Einschalten des Ambient Mode für den Namespace des ZETA Guard (zeta-local in diesem Beispiel - kubectl label namespace zeta-local istio.io/dataplane-mode=ambient

Man kann nun über das Kommando istioctl ztunnel-config workloads verifizieren, dass die workloads korrekt eingerichtet sind. Das erkennt man daran, dass HBONE in der PROTOCOL Spalte angezeigt wird.

Beispielhaft sieht das dann wie folgt aus:

zeta-local         authserver-75899b88f-rvzcr                                   10.244.1.26 zeta-local-worker        None     HBONE
zeta-local         exauthsim-7bbdb8577d-4zbm5                                   10.244.1.14 zeta-local-worker        None     HBONE
zeta-local         frontend-proxy-7d6fd97668-sdbbl                              10.244.1.24 zeta-local-worker        None     HBONE
zeta-local         grafana-7b4994695-d5m2h                                      10.244.1.30 zeta-local-worker        None     HBONE
zeta-local         jaeger-5b7c68bd78-ckvzc                                      10.244.1.16 zeta-local-worker        None     HBONE
zeta-local         keycloak-db-0                                                10.244.1.31 zeta-local-worker        None     HBONE
zeta-local         llm-84df6b4845-cdbmc                                         10.244.1.29 zeta-local-worker        None     HBONE
zeta-local         opa-5459844d9d-b8q2h                                         10.244.1.27 zeta-local-worker        None     HBONE
zeta-local         opensearch-0                                                 10.244.1.20 zeta-local-worker        None     HBONE
zeta-local         pep-deployment-767b676cfd-k9hnb                              10.244.1.13 zeta-local-worker        None     HBONE
zeta-local         popp-mock-55bd588677-fjmjj                                   10.244.1.18 zeta-local-worker        None     HBONE
zeta-local         product-reviews-64998d7fdb-xm5tg                             10.244.1.11 zeta-local-worker        None     HBONE
zeta-local         prometheus-766df54ff-nszqf                                   10.244.1.15 zeta-local-worker        None     HBONE
zeta-local         telemetry-gateway-local-76f8b8b578-x4t7b                     10.244.1.17 zeta-local-worker        None     HBONE
zeta-local         test-monitoring-collector-local-7ff997447f-wjp5w             10.244.1.28 zeta-local-worker        None     HBONE
zeta-local         testdriver-6f8dfcdb98-qlj26                                  10.244.1.25 zeta-local-worker        None     HBONE
zeta-local         testfachdienst-5bd688cdc5-vt2cv                              10.244.1.19 zeta-local-worker        None     HBONE
zeta-local         tiger-proxy-bbf4ccbbf-w292g                                  10.244.1.23 zeta-local-worker        None     HBONE
zeta-local         zeta-testenv-local-log-collector-agent-bk86q                 10.244.1.10 zeta-local-worker        None     HBONE
zeta-local         zeta-testenv-local-nginx-ingress-controller-867757f4d8-wv2db 10.244.1.12 zeta-local-worker        None     HBONE
zeta-local         zeta-testenv-local-tiger-testsuite-79f555b6c8-mcn68          10.244.1.21 zeta-local-worker        None     HBONE

Querschnittliche Konzepte

Verwenden einer eigenen OCI Registry

Das ZETA Guard Helm Chart verweist standardmäßig auf Images bei den Upstream Registries. Für den produktiven Einsatz ist aus Gründen der Verfügbarkeit und Trafficvermeidung eine puffernde lokale Registry vom Anbieter zu nutzen.

Damit dann die Images von dort bezogen werden, muss dies über Helm Values entsprechend gesteuert werden:

  • allgemeine Konfiguration
    • global.registry_host Name der Registry, z.B. my.registry.corp.internal:443
    • global.image_pull_secret (optional) Name eines Image Pull Secrets. Sofern zum Pullen ein Secret erforderlich ist, muss diese als Image Pull Secret in Kubernetes eingerichtet werden. Der Name dieses Secrets wird dann hier konfiguriert.
  • Authorization Server
    • authserver.image.repository Name des authserver Images auf der Registry
    • authserver.image.tag Zu verwendender Image Tag
  • PEP Http Proxy
    • pepproxy.image.repository Name des authserver Images auf der Registry
    • pepproxy.image.tag Zu verwendender Image Tag
  • Analoges wird für die weiteren Images stückweise folgen
This site uses Just the Docs, a documentation theme for Jekyll.