1. Einleitung

Die CaaS-Plattform stellt das Bindeglied zwischen FirstSpirit und der Endanwendung des Kunden dar. Die REST-Schnittstelle empfängt Informationen und aktualisiert diese in der internen Persistenzschicht der CaaS-Plattform. Eine Aktualisierung der Daten in der Endanwendung des Kunden erfolgt durch Requests an die REST-Schnittstelle.

Die CaaS-Plattform umfasst folgende Komponenten, die als Docker-Container vorliegen:

REST-Schnittstelle (caas-rest-api)

Die REST-Schnittstelle dient sowohl der Übertragung als auch der Abfrage von Daten in das bzw. aus dem CaaS-Repository. Dafür stellt sie einen REST-Endpoint bereit, der von beliebigen Diensten verwendet werden kann. Sie unterstützt zudem Authentifizierung und Autorisierung.

Zwischen CaaS Version 2.11 und 2.13 (inklusive) wurde die Authentifizierungs- und Autorisierungsfunktionalität durch einen separaten Security Proxy bereitgestellt.

CaaS-Repository (caas-mongo)

Das CaaS-Repository ist nicht vom Internet aus erreichbar und ist innerhalb der Plattform nur von der REST-Schnittstelle aus erreichbar. Es dient als Ablage aller Projektdaten sowie interner Konfiguration.

2. Technische Voraussetzungen

Der Betrieb der CaaS-Plattform ist mit Kubernetes zu realisieren.

Sollten Sie sich nicht in der Lage fühlen, einen Kubernetes-Cluster betreiben, konfigurieren, überwachen und Betriebsprobleme der Cluster-Infrastruktur entsprechend analysieren und beheben zu können, so raten wir ausdrücklich von einem On-Premises Betrieb ab und verweisen auf unser SaaS-Angebot.

Da die CaaS-Plattform als Helm-Artefakt ausgeliefert wird, muss Helm als Client verfügbar sein.

Es ist wichtig, dass Helm auf sichere Art und Weise installiert ist. Nähere Informationen dazu sind in der Helm-Installationsanleitung enthalten.

Für die Systemvoraussetzungen konsultieren Sie bitte das technische Datenblatt der CaaS-Plattform .

3. Installation und Konfiguration

Die Einrichtung der CaaS-Plattform für den Betrieb mit Kubernetes erfolgt über den Einsatz von Helm-Charts. Diese sind Bestandteil der Auslieferung und enthalten bereits alle erforderlichen Komponenten.

Die nachfolgenden Unterkapitel beschreiben die erforderlichen Installations- und Konfigurationsschritte.

3.1. Import der Images

Die Einrichtung der CaaS-Plattform erfordert im ersten Schritt den Import der Images in Ihre zentrale Docker-Registry (z. B. Artifactory). Die Images sind in der Auslieferung in der Datei caas-docker-images-14.9.0.zip enthalten.

Die Credentials für den Zugriff des Clusters auf die Registry müssen bekannt sein.

Die für den Import notwendigen Schritte entnehmen Sie bitte der Dokumentation der von Ihnen eingesetzten Registry.

3.2. Konfiguration des Helm-Charts

Nach dem Import der Images ist die Konfiguration des Helm-Charts notwendig. Dieser ist Bestandteil der Auslieferung und in der Datei caas-14.9.0.tgz enthalten. Eine Standardkonfiguration des Charts ist bereits in der values.yaml-Datei vorgenommen. Alle Parameter, die in dieser values.yaml angegeben sind, können mit einer manuell anzulegenden custom-values.yaml durch einen spezifischen Wert überschrieben werden.

3.2.1. Authentifizierung

Alle Authentifizierungs-Einstellungen zur Kommunikation mit bzw. innerhalb der CaaS-Plattform werden im credentials-Block der custom-values.yaml festgelegt.

So finden sich hier Benutzernamen und Standard-Passwörter sowie der CaaS-Master API Key. Es wird dringend empfohlen, die Standard-Passwörter und den CaaS-Master API Key anzupassen.

Alle gewählten Passwörter müssen alphanumerisch sein. Andernfalls treten Probleme in Verbindung mit dem CaaS auf.

Der CaaS-Master API Key wird während der Installation der CaaS-Plattform automatisch angelegt und ermöglicht demnach die direkte Benutzung der REST-Schnittstelle.

3.2.2. CaaS-Repository (caas-mongo)

Die Konfiguration des Repositories umfasst zwei Parameter:

storageClass

Die Möglichkeit des Überschreibens von Parametern aus der values.yaml-Datei betrifft vor allem auch den Parameter mongo.persistentVolume.storageClass.

Aus Performance-Gründen empfehlen wir, dass das unterliegende Dateisystem der MongoDB mit XFS provisioniert ist.

clusterKey

Für den Authentifizierungsschlüssel des Mongo-Cluster wird eine Standardkonfiguration mit ausgeliefert. Der Schlüssel kann im Parameter credentials.clusterKey festgelegt werden. Es wird dringend empfohlen, für den Produktivbetrieb mit dem folgenden Befehl einen neuen Schlüssel zu erzeugen:

openssl rand -base64 756

Dieser Wert darf nur während der initialen Installation verändert werden. Wird er zu einem späteren Zeitpunkt geändert, kann dies zu einer dauerhaften Nichtverfügbarkeit der Datenbank führen, die nur noch manuell reparierbar ist.

3.2.3. Docker-Registry

Eine Anpassung der Parameter imageRegistry und imageCredentials ist notwendig, um die verwendete Docker-Registry zu konfigurieren.

Beispielkonfiguration in einer custom-values.yaml
imageRegistry: docker.company.com/e-spirit

imageCredentials:
   username: "username"
   password: "special_password"
   registry: docker.company.com
   enabled: true

3.2.4. Ingress Konfigurationen

Ingress-Definitionen steuern den eingehenden Datenverkehr auf die jeweilige Komponente. Die im Chart enthaltenen Definitionen werden mit der Standardkonfiguration jedoch nicht erstellt. Die Parameter restApi.ingress.enabled und restApi.ingressPreview.enabled erlauben die Ingress-Konfiguration für die REST-Schnittstelle.

Die Ingress-Definitionen des Helm-Charts setzen den NGINX Ingress Controller voraus, da Annotationen sowie die Klasse dieser konkreten Implementierung verwendet werden. Sollten Sie eine abweichende Implementierung einsetzen, so müssen Sie die Annotationen und das Attribut spec.ingressClassName der Ingress-Definitionen in Ihrer custom-values.yaml-Datei entsprechend an Ihre Gegebenheiten anpassen.

Das Attribut spec.ingressClassName wurde in Kubernetes 1.18 eingeführt und wird in der Standardkonfiguration genutzt. Sollte dieses Attribut in Ihrer Kubernetes-Version nicht zur Verfügung stehen, so müssen Sie es an allen vorkommenden Stellen durch die Angabe ingressClassName: null löschen und stattdessen die Annotation kubernetes.io/ingress.class hinzufügen. Die Änderungen erfolgen über Ihre custom-values.yaml.

Ingress-Erzeugung in einer custom-values.yaml
restApi:
   ingress:
      enabled: true
      hosts:
         - caas.company.com
   ingressPreview:
      enabled: true
      hosts:
         - caas-preview.company.com

Sind die Einstellungsmöglichkeiten für den spezifischen Anwendungsfall nicht ausreichend, lässt sich der Ingress auch selbst eigenständig erzeugen. In diesem Fall ist der entsprechende Parameter auf den Wert enabled: false zu setzen. Das folgende Codebeispiel bietet eine Orientierung für die Definition.

Ingress-Definition für die REST-Schnittstelle
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
   labels:
   name: caas
spec:
   rules:
   - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: caas-rest-api
            port:
              number: 80
   host: caas-rest-api.mydomain.com
   ingressClassName: my-ingress-caas

3.3. Installation des Helm-Charts

Nach der Konfiguration des Helm-Charts ist dieser in den Kubernetes-Cluster zu installieren. Die Installation erfolgt über die nachfolgenden Befehle, die im Verzeichnis des Helm-Charts ausgeführt werden müssen.

Installation des Chart
kubectl create namespace caas
helm install RELEASE_NAME . --namespace=caas --values /path/to/custom-values.yaml

Der Name des Release kann frei gewählt werden.

Soll der Namespace einen anderen Namen tragen, müssen Sie die Angaben innerhalb der Befehle entsprechend ersetzen.

Soll ein bereits existierender Namespace verwendet werden, so entfällt die Erstellung und der gewünschte Namespace ist innerhalb des Installationsbefehls anzugeben.

Da die Container zunächst von der verwendeten Image-Registry heruntergeladen werden, kann die Installation einige Minuten in Anspruch nehmen. Im Idealfall sollte eine Zeitspanne von fünf Minuten jedoch nicht überschritten werden, bevor die CaaS-Plattform einsatzfähig ist.

Der Status der einzelnen Komponenten ist mit dem folgenden Befehl abrufbar:

kubectl get pods --namespace=caas

Sobald alle Komponenten den Status Running besitzen, ist die Installation abgeschlossen.

NAME                                 READY     STATUS        RESTARTS   AGE
caas-mongo-0                         2/2       Running       0          4m
caas-mongo-1                         2/2       Running       0          3m
caas-mongo-2                         2/2       Running       0          1m
caas-rest-api-1851714254-13cvn       1/1       Running       0          5m
caas-rest-api-1851714254-13cvn       1/1       Running       0          4m
caas-rest-api-1851714254-xs6c0       1/1       Running       0          4m

3.4. TLS

Die Kommunikation der CaaS-Plattform nach außen ist standardmäßig nicht verschlüsselt. Soll sie per TLS geschützt werden, existieren zwei Konfigurationsmöglichkeiten:

Verwendung eines offiziell signierten Zertifikats

Für die Verwendung eines offiziell signierten Zertifikats wird ein TLS-Secret benötigt, das zunächst zu erzeugen ist. Dieses muss die Schlüssel tls.key und das Zertifikat tls.crt enthalten.

Die für die Erzeugung des TLS-Secrets notwendigen Schritte sind in der Kubernetes Ingress-Dokumentation beschrieben.

Automatisierte Zertifikatsverwaltung

Alternativ zur Verwendung eines offiziell signierten Zertifikats ist es möglich, die Verwaltung mithilfe des Cert-Managers zu automatisieren. Dieser ist innerhalb des Clusters zu installieren und übernimmt die Erzeugung, Verteilung sowie Aktualisierung aller benötigten Zertifikate. Die Konfiguration des Cert-Managers ermöglicht dabei beispielsweise die Verwendung und automatische Erneuerung von Let’s-Encrypt-Zertifikaten.

Die notwendigen Schritte zur Installation sind in der Cert-Manager-Dokumentation erläutert.

3.5. Skalierung

Um die in den CaaS übertragenen Informationen schnell verarbeiten zu können, muss die CaaS-Plattform jederzeit eine optimale Lastverteilung gewährleisten. Aus diesem Grund sind die REST-Schnittstelle und die Mongo-Datenbank skalierbar und hinsichtlich des Aspekts der Ausfallsicherheit bereits so konfiguriert, dass jeweils mindestens drei Instanzen deployed werden. Diese Mindestanzahl von Instanzen ist insbesondere für den Mongo-Cluster zwingend erforderlich.

3.5.1. REST-Schnittstelle

Die Skalierung der REST-Schnittstelle erfolgt mithilfe eines Horizontal Pod Autoscalers. Dessen Aktivierung sowie Konfiguration ist in der custom-values.yaml-Datei vorzunehmen, um die in der values.yaml-Datei definierten Standard-Werte zu überschreiben.

Standard-Konfiguration der REST-Schnittstelle
restApi:
  horizontalPodAutoscaler:
    enabled: false
    minReplicas: 3
    maxReplicas: 9
    targetCPUUtilizationPercentage: 50

Der Horizontal Pod Autoscaler ermöglicht die Herunter- bzw. Heraufskalierung der REST-Schnittstelle in Abhängigkeit der aktuellen CPU-Last. Der Parameter targetCPUUtilizationPercentage gibt dabei an, ab welchem Prozentwert eine Skalierung stattfinden soll. Gleichzeitig definieren die Parameter minReplicas und maxReplicas die minimale und maximal Anzahl der möglichen REST-Schnittstellen-Instanzen.

Der Schwellwert für die CPU-Last ist mit Bedacht zu wählen:
Ist ein zu niedriger Prozentwert gewählt, skaliert die REST-Schnittstelle im Fall ansteigender Last zu früh hoch. Ist ein zu hoher Prozentwert gewählt, kann die Skalierung der REST-Schnittstelle im Fall ansteigender Last nicht schnell genug erfolgen.

Eine falsche Konfiguration kann somit die Stabilität des Systems gefährden.

Die offizielle Kubernetes Horizontal Pod Autoscaler-Dokumentation sowie die in ihr aufgeführten Beispiele enthalten weitere Informationen zum Einsatz eines Horizontal Pod Autoscalers.

3.5.2. Mongo-Datenbank

Wir unterscheiden hier die horizontale Skalierung von der vertikalen. Horizontale Skalierung bedeutet zusätzliche Instanzen, welche den Traffic übernehmen. Vertikale Skalierung bedeutet existierenden Instanzen mehr CPU/RAM zuweisen.

Horizontale Skalierung

Im Gegensatz zur REST-Schnittstelle ist die horizontale Skalierung der Mongo-Datenbank nur manuell möglich. Sie kann daher nicht automatisch mithilfe eines Horizontal Pod Autoscalers durchgeführt werden.

Die Skalierung der Mongo-Datenbank erfolgt über den Parameter replicas. Dieser ist in die custom-values.yaml-Datei einzutragen, um den in der values.yaml-Datei definierten Standard-Wert zu überschreiben.

Für den Betrieb des Mongo-Clusters sind mindestens drei Instanzen notwendig, da sonst kein Primary-Knoten zur Verfügung steht und die Datenbank nicht schreibbar ist. Unterschreitet die Anzahl verfügbarer Instanzen einen Wert von 50 % der konfigurierten Instanzen, kann kein Primary-Knoten mehr gewählt werden. Dieser ist für die Funktionsfähigkeit der REST-Schnittstelle jedoch unerlässlich.

Das Kapitel Consider Fault Tolerance der MongoDB-Dokumentation beschreibt, wie viele Knoten explizit ausfallen können, bis die Bestimmung eines neuen Primary-Knoten unmöglich ist. Die in der Dokumentation enthaltenen Informationen sind bei der Skalierung der Installation zu berücksichtigen.

Weitere Informationen zur Skalierung und Replizierung der Mongo-Datenbank sind in den Kapiteln Replica Set Deployment Architectures und Replica Set Elections enthalten.

Definition des Replica-Parameters
mongo:
  replicas: 3

Ein Herunterskalieren der Mongo-Datenbank ist nicht ohne einen direkten Eingriff möglich und erfordert eine manuelle Verkleinerung des Replicasets der Mongo-Datenbank. Die MongoDB-Dokumentation beschreibt die dafür notwendigen Schritte.

Ein solcher Eingriff erhöht das Risiko eines Ausfalls und wird daher nicht empfohlen.

Vertikale Skalierung

Die vertikale Skalierung erfolgt mithilfe eines Vertical Pod Autoscalers. Vertical Pod Autoscaler sind Custom Resources in Kubernetes, daher müssen Sie als Erstes die Unterstützung in Ihrem Cluster gewährleisten.

Anschließend können Sie folgende Parameter in Ihrer custom-values.yaml konfigurieren:

Konfiguration des Vertical Pod Autoscaler
mongo:
  verticalPodAutoscaler:
    enabled: false
    apiVersion: autoscaling.k8s.io/v1beta2
    updateMode: Auto
    minAllowed:
      cpu: 100m
      memory: 500Mi
    maxAllowed:
      cpu: 1
      memory: 2000Mi

Übernahme der Konfiguration

Die aktualisierte custom-values.yaml-Datei muss nach den Konfigurationsänderungen für die REST-Schnittstelle bzw. die Mongo-Datenbank mit dem folgenden Befehl übernommen werden.

Upgrade-Befehl
helm upgrade -i RELEASE_NAME path/to/caas-<VERSIONNUMBER>.tgz --values /path/to/custom-values.yaml

Der Release-Name ist mit dem Befehl helm list --all-namespaces ermittelbar.

3.6. Monitoring

Die CaaS-Plattform ist eine Microservice-Architektur und setzt sich daher aus unterschiedlichen Komponenten zusammen. Um ihren Status jederzeit ordnungsgemäß überwachen und im Fehlerfall kurzfristig reagieren zu können, ist für den Betrieb mit Kubernetes die Einbindung in ein clusterweites Monitoring zwingend notwendig.

Die CaaS-Plattform ist für ein Monitoring mit Prometheus-Operator bereits vorkonfiguriert, da dieses Szenario im Kubernetes-Umfeld weit verbreitet ist. Es sind sowohl Prometheus-ServiceMonitors zum Erfassen von Metriken, Prometheus-Alerts zur Benachrichtigung bei Problemen als auch vordefinierte Grafana-Dashboards zur Visualisierung der Metriken enthalten.

3.6.1. Voraussetzungen

Es ist unerlässlich, ein Monitoring und eine Persistenz der Logs für den Kubernetes-Cluster einzurichten. Ohne diese Voraussetzungen sind im Fehlerfall kaum Analyse-Möglichkeiten gegeben und dem Technical Support fehlen wichtige Informationen.

Metriken

Zur Installation des Prometheus-Operator nutzen Sie bitte das offizielle Helm-Chart, so dass darauf aufbauend das Cluster-Monitoring eingerichtet werden kann. Weitere Informationen entnehmen Sie bitte den entsprechenden Dokumentationen.

Sollten Sie keinen Prometheus-Operator betreiben, so müssen Sie die Prometheus-ServiceMonitors sowie die Prometheus-Alerts abschalten.

Logging

Mit dem Einsatz von Kubernetes ist es möglich, diverse Container bzw. Dienste automatisiert sowie skalierbar bereitzustellen. Damit die Logs in einem solchen dynamischen Umfeld auch nach der Beendung einer Instanz bestehen bleiben, muss eine Infrastruktur eingebunden werden, die diese zuvor persistiert.

Daher empfehlen wir die Verwendung eines zentralen Logging-Systems, wie zum Beispiel des Elastic-Stacks. Der Elastic- bzw. ELK-Stack ist eine Sammlung von Open-Source-Projekten, die dabei helfen, Log-Daten in Echtzeit zu persistieren, durchsuchen sowie analysieren.

Auch hierfür können Sie für die Installation auf ein bestehendes Helm-Chart zurückgreifen.

3.6.2. Prometheus-ServiceMonitors

Das Deployment des von der CaaS-Plattform mitgelieferten ServiceMonitors für die REST-Schnittstelle und die Mongo-Datenbank, wird über die custom-values.yaml-Datei des Helm-Charts gesteuert.

Der Zugriff auf die Metriken der REST-Schnittstelle ist mittels HTTP Basic Auth und der Zugriff auf die Metriken der MongoDB über einen entsprechenden MongoDB-Benutzer gesichert. Die jeweiligen Zugangsdaten sind im Credentials-Block der values.yaml-Datei des Helm-Charts enthalten.

Bitte passen Sie die Zugangsdaten aus Sicherheitsgründen in ihrer custom-values.yaml-Datei an.

Typischerweise ist Prometheus so konfiguriert, dass nur ServiceMonitors mit bestimmten Labels berücksichtigt werden. Die Labels können daher in der custom-values.yaml-Datei konfiguriert werden und gelten für alle ServiceMonitors des CaaS Helm-Charts. Des Weiteren ermöglicht der Parameter scrapeInterval eine Definition der Häufigkeit, mit welcher die jeweiligen Metriken abgerufen werden.

monitoring:
  prometheus:
    # Prometheus service monitors will be created for enabled metrics. Each Prometheus
    # instance has a configured serviceMonitorSelector property, to be able to control
    # the set of matching service monitors. To allow defining matching labels for CaaS
    # service monitors, the labels can be configured below and will be added to each
    # generated service monitor instance.
    metrics:
      serviceMonitorLabels:
        release: "prometheus-operator"
      mongo:
        enabled: true
        scrapeInterval: "30s"
      caas:
        enabled: true
        scrapeInterval: "30s"

Die Metriken der MongoDB werden über einen Sidecar-Container bereitgestellt und mit Hilfe eines separaten Datenbank-Benutzers abgerufen. Die Konfiguration des Datenbank-Benutzers können Sie im credentials-Block der custom-values.yaml vornehmen. Der Sidecar-Container ist mit folgender Standard-Konfiguration hinterlegt:

mongo:
  metrics:
    image: mongodb-exporter:0.11.0
    syncTimeout: 1m

3.6.3. Prometheus-Alerts

Das Deployment der von der CaaS-Plattform mitgelieferten Alerts wird über die custom-values.yaml-Datei des Helm-Charts gesteuert.

Typischerweise ist Prometheus so konfiguriert, dass nur Alerts mit bestimmten Labels berücksichtigt werden. Die Labels können daher in der custom-values.yaml-Datei konfiguriert werden und gelten für alle Alerts des CaaS Helm-Charts:

caas-common:
  monitoring:
    prometheus:
      alerts:
        # Labels for the PrometheusRule resource
        prometheusRuleLabels:
          app: "prometheus-operator"
          release: "prometheus-operator"
        # Additional Prometheus labels to attach to alerts (or overwrite existing labels)
        additionalAlertLabels: {}
        caas:
          enabled: true
          useAlphaAlerts: false
          # Namespace(s) that should be targeted by the alerts (supports Go template and regular expressions)
          targetNamespace: "{{ .Release.Namespace }}"

3.6.4. Grafana-Dashboards

Das Deployment der von der CaaS-Plattform mitgelieferten Grafana-Dashboards wird über die custom-values.yaml-Datei des Helm-Charts gesteuert.

Typischerweise ist der Grafana Sidecar Container so konfiguriert, dass nur Configmaps mit bestimmten Labels und in einem definierten Namespace berücksichtigt werden. Die Labels der Configmap sowie der Namespace, in welchen diese deployed wird, können daher in der custom-values.yaml-Datei konfiguriert werden:

caas-common:
  monitoring:
    grafana:
      dashboards:
        enabled: true
        # Namespace that the ConfigMap resource will be created in (supports Go template and regular expressions)
        configmapNamespace: "{{ .Release.Namespace }}"
        # Additional labels to attach to the ConfigMap resource
        configMapLabels: {}

4. Entwicklungsumgebung

Kubernetes und Helm bilden die Grundlage aller Installationen der CaaS-Plattform. Bei Entwicklungsumgebungen empfehlen wir die Installation der CaaS-Plattform in einem separaten Namespace auf Ihrem Produktionscluster oder einem ähnlich konfigurierten Cluster. Wir raten davon ab, lokale Instanzen der CaaS-Plattform zu verwenden, auch für die Entwicklung.

Wenn Sie eine lokale Umgebung auf den Entwicklungsmaschinen benötigen, müssen Sie einen lokalen Kubernetes-Cluster zur Verwendung erstellen. Dazu kann eines der folgenden Projekte verwendet werden:

Diese Liste erhebt keinen Anspruch auf Vollständigkeit. Vielmehr soll sie einige Beispiele aufführen, von denen wir wissen, dass der Betrieb generell möglich ist, ohne dass wir diese Projekte selbst permanent nutzen.

Jedes dieser Projekte kann verwendet werden, um Kubernetes-Cluster lokal zu verwalten. Wir sind jedoch nicht in der Lage, Ihnen Unterstützung für eines dieser spezifischen Projekte zu geben. Die CaaS Plattform verwendet nur Standardfunktionen von Helm und Kubernetes und ist daher unabhängig von einer bestimmten Kubernetes Distribution.

Bitte stellen Sie sicher, dass die folgenden Funktionen korrekt konfiguriert sind, wenn Sie einen lokalen Kubernetes-Cluster verwenden:

  • Kubernetes Image Pull Secrets zum Auflösen der Docker-Images aus Ihrer lokalen oder firmeneigenen Docker-Registry

  • Deaktivieren des Monitorings in der custom-values.yaml oder Installieren der benötigten Voraussetzungen

  • Anpassen der DNS-Einstellungen des Hostsystems, um mit Kubernetes Ingress-Ressourcen arbeiten zu können, oder Verwendung lokaler Port-Weiterleitungen in den lokalen Cluster

5. REST-Schnittstelle

5.1. Authentifizierung

Jede Anfrage an die REST-Schnittstelle muss authentifiziert werden, ansonsten wird sie abgewiesen. Die verschiedenen Möglichkeiten der Authentifizierung werden nachfolgend erläutert.

5.1.1. Authentifizierung als Admin-Benutzer

Die Authentifizierung des Admin-Benutzers erfolgt mit HTTP Basic Authentication und den konfigurierten Zugangsdaten. Der Admin-Benutzer ist für administrative Tätigkeiten vorgesehen, wie z.B. der Verwaltung von API Keys. Alle anderen Operationen sollten mithilfe von API Keys authentifiziert werden.

Die Anmeldedaten des Admin-Benutzers sind in den Parametern credentials.webAdminUser und credentials.webAdminPassword des Helm-Charts definiert.

Details finden sich in Kapitel Authentifizierung.

5.1.2. Authentifizierung mit API Key

Anfragen mit API Key müssen einen HTTP-Header der Form Authorization: apikey="<key>" enthalten. Als Wert von key wird der Wert des key-Attributs des entsprechenden API Keys erwartet.

Weitere Informationen finden Sie im Abschnitt Validierung von API Keys.

5.1.3. Authentifizierung mit Sicherheitstoken

Es ist möglich, zu einem API Key ein kurzlebiges (bis zu 24 Stunden) Sicherheitstoken zu generieren. Das Token beinhaltet dieselben Berechtigungen wie der API Key, zu dem es generiert wurde. Es gibt zwei Möglichkeiten, diese Token zu generieren und zu nutzen:

Query Parameter

Eine mit API Key authentifizierte GET-Anfrage auf /_logic/securetoken?tenant=<db> generiert ein Sicherheitstoken. Solch ein Token kann nur für eine konkrete Datenbank ausgestellt werden, unabhängig davon ob der API Key Berechtigungen auf mehrere Datenbanken hat. Ein Parameter &ttl=<Lebensdauer in Sekunden> wird unterstützt und ist optional. Das Sicherheitstoken steht in der JSON-Rückgabe.

Jede Anfrage an die REST-Schnittstelle kann optional über einen Query-Parameter ?securetoken=<token> authentifiziert werden.

Eine mit API Key authentifizierte GET-Anfrage auf /_logic/securetokencookie?tenant=<db> generiert ein Sicherheitstoken-Cookie. Solch ein Cookie kann nur für eine konkrete Datenbank ausgestellt werden, unabhängig davon, ob der API Key Berechtigungen auf mehrere Datenbanken hat. Ein Parameter &ttl=<Lebensdauer in Sekunden> wird unterstützt und ist optional. Die Rückgabe beinhaltet einen Set-Cookie-Header mit dem Sicherheitstoken.

Alle Anfragen mit diesem Cookie werden automatisch authentifiziert.

5.1.4. Authentifizierungsreihenfolge

Sollten mehrere Authentifizierungsmechanismen gleichzeitig in einer Anfrage verwendet werden, so wird nur der erste von ihnen evaluiert. Die Reihenfolge ist wie folgt:

  1. Der Query Parameter securetoken.

  2. Der Authorization Header.

  3. Das Cookie securetoken.

5.2. Abfrage von Dokumenten und Medien

Über die REST-Schnittstelle lassen sich Inhalte in Form von JSON Dokumenten über HTTP verwalten und abfragen. Sie werden in sogenannten Collections abgelegt, die Datenbanken unterstellt sind. Es gilt dabei das folgende dreiteilige URL-Schema:

http://<server>:<port>/<database>/<collection>/<document>

database

Dieser Teil der URL beinhaltet die Tenant ID.

collection

Die Collection setzt sich aus der FirstSpirit-Projekt UUID sowie den jegeiligen Vorschau- bzw. Freigabestand zusammen.

document

Hier wird die UUID des FirstSpirit-Elements zusammen mit der Sprachlocale verwendet.

Binäre Inhalte (Medien) bilden insofern eine Ausnahme, als sie in sogenannten Buckets gespeichert werden. Die zugehörigen Collections enden immer mit das Suffix .files:

https://<server>:<port>/<tenant>/<project>.<release|preview>.files/<document>

Bitte beachten Sie, dass binäre Inhalte bei unserem Cloud-Offering nicht in die CaaS-Buckets übertragen werden.

5.2.1. HAL-Format

Die Schnittstelle liefert alle Ergebnisse im HAL-Format zurück. Es handelt sich bei ihnen somit nicht um schlichte Rohdaten, wie zum Beispiel traditionell unstrukturierte Inhalte im JSON-Format.

Das HAL-Format bietet den Vorteil einer einfachen, aber mächtigen Strukturierung. Neben den geforderten Inhalten enthalten die Ergebnisse zusätzliche Meta-Informationen zur Struktur dieser Inhalte.

Beispiel

{  "_size": 5,
   "_total_pages": 1,
   "_returned": 3,
   "_embedded": { CONTENT }
}

In diesem Beispiel wurde eine gefilterte Abfrage abgesetzt. Ohne die genauen Inhalte zu kennen, ist ihre Struktur aufgrund der Meta-Informationen direkt ablesbar. Die REST-Schnittstelle liefert an dieser Stelle aus einer Menge von fünf Dokumenten drei den Filterkriterien entsprechende Ergebnisse zurück und stellt diese auf einer einzigen Seite dar.

Handelt es sich bei einem angefragten Element um ein Medium, ermittelt die URL lediglich dessen Metadaten. Das HAL-Format enthält entsprechende Links, welche auf die URL mit den eigentlichen Binärdaten verweisen. Weitere Informationen entnehmen Sie bitte der Dokumentation.

5.2.2. Seitengröße der Abfragen

Die Ergebnisse der REST-Schnittstelle werden immer paginiert ausgeliefert. Zur Steuerung der Seitengröße und der angefragten Seite können bei GET-Anfragen die HTTP-Query-Parameter pagesize und page verwendet werden. Der Standardwert für den pagesize-Parameter ist in der CaaS-Plattform auf 20 gesetzt und das Maximum auf 100. Diese Werte können im Falle einer On-Premises-Installation in der Datei custom-values.yaml geändert werden. Weitere Informationen finden Sie in der RESTHeart-Dokumentation.

5.2.3. Einsatz von Filtern

Filter kommen immer dann zum Einsatz, wenn Dokumente nicht über ihre Id, sondern über deren Inhalt ermittelt werden sollen. Auf diesem Weg lassen sich sowohl einzelne als auch mehrere Dokumente abrufen.

Die Abfrage aller englischsprachiger Dokumente aus der Collection products besitzt beispielsweise folgenden Aufbau:

http://Servername:Port/Database/products?filter={fs_language:"EN"}

Über dieses Beispiel hinaus existieren weitere Filtermöglichkeiten. Weitere Informationen hierzu finden Sie in der Query-Dokumentation.

5.3. Speicherung von Dokumenten

Zur Speicherung von Dokumenten können die HTTP Methoden POST, PUT und PATCH benutzt werden. Dokumente können darüberhinaus mit dem Verb DELETE gelöscht werden.

Der folgende Ausschnitt zeigt das Anlegen eines Dokumentes my-document innerhalb der Collection my-collection, die sich in der Datenbank my-db befindet.

curl --location --request PUT 'http://my-caas-api/my-db/my-collection/my-document' \
--header 'Authorization: apikey="my-api-key"' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": "some-data"
}'

Weitere Informationen zur Speicherung von Dokumenten können den entsprechenden Abschnitten in der RESTHeart Dokumentation entnommen werden.

Bei der Speicherung von Dokumenten mittels der Verben POST, PUT oder PATCH wird abweichend zu RESTHeart als default der Write Mode upsert benutzt. Weitere Informationen zu dem Write Mode können der RESTHeart Dokumentation entnommen werden.

5.4. Verwaltung von Datenbanken und Collections

Im Gegensatz zur Speicherung von Dokumenten ist die Verwaltung von Datenbanken und Collections lediglich auf die HTTP Methoden PUT und DELETE beschränkt.

Folgender Ausschnitt zeigt das Anlegen der Datenbank my-db mit einem PUT Request.

curl --location --request PUT 'http://my-caas-api/my-db' \
--header 'Authorization: apikey="my-api-key"'

Weitere Informationen zur Verwaltung von Datenbanken können den entsprechenden Abschnitten in der RESTHeart Dokumentation entnommen werden.

Das Verwalten von Datenbanken ist unserem SaaS-Angebot aufgrund von eingeschränkter Zugriffsberechtigung nicht unterstützt.

Eine Collection my-collection kann wie folgt in der Datenbank my-db mit einem PUT Request angelegt werden.

curl --location --request PUT 'http://my-caas-api/my-db/my-collection' \
--header 'Authorization: apikey="my-api-key"'

Weitere Informationen zur Verwaltung von Collections können den entsprechenden Abschnitten in der RESTHeart Dokumentation entnommen werden.

5.5. Verwaltung von API Keys

API Keys können, wie alle anderen Ressourcen im CaaS auch, über REST-Endpunkte verwaltet werden. Generell gilt es dabei zu unterscheiden, dass API Keys auf zwei Ebenen verwaltet werden können: global oder lokal pro Datenbank. Globale API Keys unterscheiden sich von den lokalen API Keys durch ihren Gültigkeitsbereich.

Bei der Authentifizierung mit API Key durchsucht die CaaS-Plattform immer zunächst die lokalen API Keys. Wird kein passender API Key gefunden, so werden danach die globalen API Keys evaluiert.

5.5.1. Globale API Keys

Globale API Keys sind datenbankübergreifend und werden in der apikeys Collection der caas_admin Datenbank verwaltet. Im Gegensatz zu lokalen API Keys ermöglichen sie es, Berechtigungen für mehrere oder gar alle Datenbanken zu definieren.

5.5.2. Lokale API Keys

Lokale API Keys sind pro Datenbank definiert und werden dementsprechend in der apikeys Collection einer beliebigen Datenbank verwaltet. Anders als globale API Keys können lokale API Keys nur Berechtigungen für Ressourcen innerhalb derselben Datenbank definieren.

5.5.3. Autorisierungsmodell

Die Autorisierung eines API Keys wird anhand seines url-Attributs durchgeführt. Dieser Wert wird gegen den URL-Pfad des Requests geprüft.

Hierbei ergibt sich eine grundlegende Unterscheidung zwischen der Funktionsweise von globalen und lokalen API Keys. Globale API Keys prüfen immer gegen den gesamten Pfad des Requests, lokale API Keys hingegen nur gegen den Teil des Pfads nach der Datenbank.

Das folgende Beispiel veranschaulicht dieses Vorgehen:

Tabelle 1. API Key Autorisierung
Berechtigung im API Key (Attribut url) Typ des API Keys Request URL-Pfad Erlaubt

/

global

/

ja

/project/

ja

/project/content/

ja

/other-project/

ja

/other-project/content/

ja

/project/

global

/

nein

/project/

ja

/project/content/

ja

/other-project/

nein

/other-project/content/

nein

/

lokal in project

/

nein

/project/

ja

/project/content/

ja

/other-project/

nein

/other-project/content/

nein

/content/

lokal in project

/

nein

/project/

nein

/project/content/

ja

/other-project/

nein

/other-project/content/

nein

5.5.4. REST Endpunkte

Die folgenden Endpunkte stehen für die Verwaltung von API Keys zur Verfügung:

  • GET /<database>/apikeys

  • POST /<database>/apikeys
    zu beachten: die Parameter _id und key müssen übergeben werden und identische Werte besitzen

  • PUT /<database>/apikeys/{id}
    zu beachten: der Parameter key muss denselben Wert haben wie die {id} in der URL

  • DELETE /<database>/apikeys/{id}

Zur Verwaltung von API Keys kann auch ein API Key als Autorisierungsmethode eingesetzt werden. In dem Fall muss der verwendete API Key Schreibrechte auf der entsprechenden API Keys-Collection besitzen. Dies gilt insbesondere auch bei nur lesenden Anfragen und dient dazu, eine Rechteausweitung zu verhindern.

Die Datenbank richtet sich nach dem Typ des API Keys.

Der folgende Ausschnitt zeigt das beispielhafte Anlegen von einem lokalen API Key.

curl "https://<caas-base-url>/<tenant>/apikeys" \
     -H 'Content-Type: application/json' \
     -u '<USER>:<PASSWORD>' \
     -d $'{
  "_id": "1e0909b7-c943-45a5-ae96-79f294249d48",
  "key": "1e0909b7-c943-45a5-ae96-79f294249d48",
  "name": "New-Apikey",
  "description": "Some descriptive text",
  "permissions": [
    {
      "url": "/<collection>",
      "methods": [
        "GET",
        "PUT",
        "POST",
        "PATCH",
        "DELETE",
        "HEAD",
        "OPTIONS"
      ]
    }
  ]
}'

In diesem Beispiel wird über cURL ein neuer ApiKey erstellt, welcher im Permissions-Array entsprechend eingestellte Zugriffsrechte (über das Attribut url) auf die angegebene Collection besitzt.

Die apikeys Collections sind für API Keys reserviert und können nicht für normale Inhalte genutzt werden. Sie werden zusammen mit einem Validierungsschema automatisch beim Start der Anwendung zu bestehenden Datenbanken hinzugefügt sowie zudem während des Betriebes bei der Anlage/Aktualisierung von Datenbanken erstellt.

5.5.5. Validierung von API Keys

Jeder API Key wird bei Anlage und Aktualisierung gegen ein hinterlegtes JSON-Schema validiert. Das JSON-Schema sichert die grundlegende Struktur von API Keys ab und kann unter /<database>/_schemas/apikeys abgefragt werden.

Weitere Validierungen stellen sicher, dass keine zwei API Keys mit demselben key angelegt werden können. Ebenso darf ein API Key eine URL nicht mehrfach enthalten.

Genügt ein API Key den Anforderungen nicht, so wird der entsprechende Request mit HTTP-Status 400 abgewiesen.

Sollte das JSON-Schema zuvor nicht erfolgreich in der Datenbank hinterlegt worden sein, so werden Requests mit HTTP-Status 500 beantwortet.

Das key-Attribut eines API Keys sollte eine valide UUID enthalten. Das Format einer UUID ist nach RFC 4122 strikt vorgegeben. Dazu gehört insbesondere auch das Vorliegen von Kleinbuchstaben. Auch wenn die CaaS-Plattform diese Eigenschaft aktuell noch nicht validiert, behalten wir uns vor diese Einschränkung in Zukunft zu aktivieren.

5.6. Indizes für eine effiziente Abfrageausführung

Die Laufzeit von Abfragen mit Filtern kann sich bei steigender Anzahl an Dokumenten in einer Collection vergrößern. Übersteigt sie einen bestimmten Wert, so wird die Abfrage von der REST-Schnittstelle mit HTTP-Status 408 beantwortet. Eine effizientere Ausführung lässt sich erreichen, indem auf den Attributen, die in den betroffenen Filterabfragen verwendet werden, ein Index erstellt wird.

Detaillierte Informationen zu Datenbank-Indizes entnehmen Sie bitte der Dokumentation der MongoDB.

5.6.1. Vordefinierte Indizes

Falls Sie CaaS Connect im Einsatz haben, werden bereits vordefinierte Indizes erstellt, die einige häufig vorkommende Filterabfragen unterstützen.

Die genauen Definitionen können unter http://Servername:Port/Database/Collection/_indexes/ abgerufen werden.

5.6.2. Kundenindividuelle Indizes

Sollten die vordefinierten Indizes Ihre Anwendungsfälle nicht abdecken und Sie bei Abfragen lange Antwortzeiten bis hin zu Request Timeouts beobachten, so können Sie eigene Indizes erstellen. Zum Management der gewünschten Indizes kann die REST-Schnittstelle genutzt werden. Die Vorgehensweise ist in der RESTHeart-Dokumentation beschrieben.

Bitte legen Sie nur die Indexe an, die Sie benötigen.

5.7. Push-Benachrichtigungen (Change Streams)

Es ist oft gewünscht, über Änderungen in der CaaS-Plattform informiert zu werden. Hierzu bietet die CaaS-Plattform Change Streams. Dieses Feature ermöglicht es eine Websocket-Verbindung zur CaaS-Plattform aufzubauen, worüber Events zu den verschiedenen Änderungen publiziert werden.

Change Streams werden angelegt, indem eine Definition in den Metadaten einer Collection abgelegt wird. Falls Sie CaaS Connect nutzen, so werden für Sie bereits einige vordefinierte Change Streams erstellt. Sie haben auch die Möglichkeit eigene Change Streams zu definieren.

Das Format der Events entspricht den Standard MongoDB Events.

Wir empfehlen bei der Arbeit mit Websockets möglicherweise auftretende Verbindungsabbrüche zu berücksichtigen. Regelmäßige ping Nachrichten und ein Mechanismus zur automatischen Wiederherstellung der Verbindung sollten in Ihrer Implementierung eingebaut werden.

Sie finden ein Beispiel für die Nutzung von Change Streams im Browser im Appendix.

5.8. Zusätzliche Informationen

Weitere Informationen über die Funktionalität der REST-Schnittstelle finden Sie in der offiziellen Restheart-Dokumentation.

6. Metriken

Metriken dienen der Überwachung (Monitoring) und der Fehleranalyse der CaaS-Komponenten im laufenden Betrieb und sind über HTTP-Endpunkte abrufbar. Sofern Metriken im Prometheus-Format vorliegen, werden dafür entsprechende ServiceMonitors erzeugt, siehe auch Prometheus-ServiceMonitors.

6.1. REST-Schnittstelle

Healthcheck

Der Healthcheck-Endpunkt stellt Informationen über die Funktionsfähigkeit der entsprechenden Komponente in Form eines JSON-Dokuments bereit. Dieser Zustand wird aus mehreren Prüfungen berechnet. Sind alle Prüfungen erfolgreich, hat die JSON-Antwort den HTTP-Status 200. Sobald mindestens eine Prüfung den Wert false besitzt, erfolgt eine Antwort mit dem HTTP-Status 500.

Die Abfrage erfolgt unter der URL: http://REST-HOST:PORT/_logic/healthcheck

Die Funktionsfähigkeit der REST-Schnittstelle hängt sowohl von der Erreichbarkeit des MongoDB-Clusters als auch von der Existenz eines Primary Nodes ab. Besitzt der Cluster keinen Primary Node, ist die Durchführung von Schreiboperationen auf der MongoDB nicht möglich.

HTTP-Metriken

Metriken zu den HTTP-Anfragen und Antworten der REST-Schnittstelle können als JSON-Dokument oder im Prometheus-Format unter der folgenden URL abgerufen werden: http://REST-HOST:PORT/_metrics

Weitere Informationen sind in der RESTHeart-Dokumentation enthalten.

6.2. MongoDB

Die Metriken der MongoDB werden über einen Sidecar Container zu Verfügung gestellt. Dieser greift mit einem separaten Datenbank-Benutzer auf die Metriken der MongoDB zu und stellt diese über HTTP bereit.

Die Metriken können unter der folgenden URL abgerufen werden: http://MONGODB-HOST:METRICS-PORT/metrics

Bitte beachten Sie, dass die Metriken der MongoDB über einen separaten Port ausgeliefert werden. Dieser Port ist nicht von außerhalb des Clusters zugreifbar und daher auch nicht durch Authentifizierung geschützt.

7. Wartung

Die Übertragung von Daten in den CaaS kann nur funktionieren, wenn die einzelnen Komponenten einwandfrei arbeiten. Treten Störungen auf oder ist eine Aktualisierung notwendig, sind daher stets alle CaaS-Komponenten zu betrachten. Die nachfolgenden Unterkapitel beschreiben die notwendigen Schritte einer Fehleranalyse bei einer vorliegenden Störung sowie die Durchführung eines Backups bzw. Updates.

7.1. Fehleranalyse

Der CaaS ist ein verteiltes System und basiert auf dem Zusammenspiel unterschiedlicher Komponenten. Jede einzelne dieser Komponente kann potenziell Fehler erzeugen. Tritt während der Verwendung des CaaS eine Störung auf, können dieser daher verschiedene Ursachen zugrunde liegen. Nachfolgend werden die grundlegenden Analyseschritte zur Ermittlung von Störungsursachen erläutert.

Zustand der Komponenten

Der Zustand der einzelnen Komponenten der CaaS-Plattform lässt sich mithilfe des Befehls kubectl get pods --namespace=<namespace> überprüfen. Weicht der Status einer Instanz vom Status Running bzw. ready ab, ist es empfehlenswert, die Fehlersuche an dieser Stelle zu beginnen und die zugehörigen Logfiles zu überprüfen.

Bestehen Probleme mit der Mongo-Datenbank, ist zu prüfen, ob ein Primary-Knoten existiert. Unterschreitet die Anzahl verfügbarer Instanzen einen Wert von 50 % der konfigurierten Instanzen, kann kein Primary-Knoten mehr gewählt werden. Dieser ist für die Funktionsfähigkeit der REST-Schnittstelle jedoch unerlässlich. Das Fehlen eines Primary-Knotens führt dazu, dass die Pods der REST-Schnittstelle nicht mehr den Status ready besitzen und somit unerreichbar sind.

Das Kapitel Consider Fault Tolerance der MongoDB-Dokumentation beschreibt, wie viele Knoten explizit ausfallen können, bis die Bestimmung eines neuen Primary-Knoten unmöglich ist.

Analyse der Logs

Im Problemfall sind die Logfiles einen guten Ausgangspunkt für die Analyse. Sie bieten die Möglichkeit, alle Vorgänge auf den Systemen nachzuvollziehen. Auf diesem Weg werden eventuelle Fehler und Warnungen ersichtlich.

Aktuelle Logfiles der CaaS-Komponenten sind mittels kubectl --namespace=<namespace> logs <pod> einsehbar, beinhalten jedoch nur Ereignisse, die innerhalb der Lebenszeit der aktuellen Instanz stattgefunden haben. Um dennoch nach einem Absturz bzw. Neustart einer Instanz die Logfiles sinnvoll analysieren zu können, empfehlen wir die Einrichtung eines zentralen Logging-Systems.

Die Logfiles sind grundsätzlich immer nur für den aktuell laufenden Container einsehbar. Aus diesem Grund ist für den Zugriff auf die Logfiles bereits beendeter oder neu gestarteter Container die Einrichtung einer persistenten Speicherung notwendig.

7.2. Backup

Die Architektur des CaaS besteht aus verschiedenen, voneinander unabhängigen Komponenten, die unterschiedliche Informationen erzeugen und verarbeiten. Besteht die Notwendigkeit einer Datensicherung, muss diese daher in Abhängigkeit der jeweiligen Komponente erfolgen.

Ein Backup der im CaaS gespeicherten Informationen muss über die Standardmechanismen der Mongo-Datenbank erfolgen. Dabei kann entweder eine Kopie der zugrundeliegenden Dateien erstellt oder mongodump verwendet werden.

7.3. Update

Der Betrieb der CaaS-Plattform mit Helm in Kubernetes bietet die Möglichkeit einer Aktualisierung auf den neuen Stand, ohne dass dabei eine Neuinstallation notwendig ist.

Vor der Aktualisierung der Mongo-Datenbank wird ein Backup dringend empfohlen.

Der Befehl helm list --all-namespaces liefert zunächst eine Liste aller bereits installierten Helm-Charts. Diese enthält sowohl die Version als auch den Namespace des entsprechenden Releases.

Beispielliste installierter Releases
\$ helm list --all-namespaces
NAME            NAMESPACE    REVISION  UPDATED             STATUS    CHART        APP VERSION
firstinstance   integration  1         2019-12-11 15:51..  DEPLOYED  caas-2.10.4  caas-2.10.4
secondinstance  staging      1         2019-12-12 09:31..  DEPLOYED  caas-2.10.4  caas-2.10.4

Für die Aktualisierung eines Releases sind nacheinander die folgenden Schritte durchzuführen:

Übernahme der Einstellungen

Um einen Verlust der bisherigen Einstellungen zu vermeiden, ist es notwendig, die custom-values.yaml-Datei, mit der die initiale Installation des Helm-Charts durchgeführt wurde, vorliegen zu haben.

Übernahme weiterer Anpassungen

Bestehen Anpassungen an Dateien (z. B. im config-Verzeichnis), sind diese ebenfalls zu übernehmen.

Aktualisierung

Nach der Durchführung der vorherigen Schritte kann anschließend die Aktualisierung gestartet werden. Sie ersetzt die bestehende Installation durch die neue Version, ohne dass eine Downtime entsteht. Dafür ist der folgende Befehl auszuführen, durch den der Vorgang gestartet wird:

helm upgrade RELEASE_NAME caas-14.9.0.tgz --values /path/to/custom-values.yaml

8. Appendix

8.1. Beispiele

Nutzung von Change Streams mit Javascript und Browser API
<script type="module">
  import PersistentWebSocket from 'https://cdn.jsdelivr.net/npm/pws@5/dist/index.esm.min.js';

  // Replace this with your API key (needs read access for the preview collection)
  const apiKey = "your-api-key";

  // Replace this with your preview collection url (if not known copy from CaaS Connect Project App)
  // e.g. "https://caas-host/my-tenant-id/f948bb48-4f6b-4a8a-b521-338c9d352f2b.preview.content"
  const previewCollectionUrl = new URL("your-preview-collection-url");

  const pathSegments = previewCollectionUrl.pathname.split("/");
  if (pathSegments.length !== 3) {
    throw new Error(`The format of the provided url '${previewCollectionUrl}' is incorrect and should only contain two path segments`);
  }

  (async function(){
    // Retrieving temporary auth token
    const token = await fetch(new URL(`_logic/securetoken?tenant=${pathSegments[1]}`, previewCollectionUrl.origin).href, {
      headers: {'Authorization': `apikey="${apiKey}"`}
    }).then((response) => response.json()).then((token) => token.securetoken).catch(console.error);

    // Establishing WebSocket connection to the change stream "crud"
    // ("crud" is the default change stream that the CaaS Connect module provides)
    const wsUrl = `wss://${previewCollectionUrl.host + previewCollectionUrl.pathname}`
      + `/_streams/crud?securetoken=${token}`;
    const pws = new PersistentWebSocket(wsUrl, { pingTimeout: 60000 });

    // Handling change events
    pws.onmessage = event => {
      const {
        documentKey: {_id: documentId},
        operationType: changeType,
      } = JSON.parse(event.data);
      console.log(`Received event for '${documentId}' with change type '${changeType}'`);
    }
  })();
</script>

9. Hilfe

Der Technical Support der e-Spirit AG bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.