CaaS Platform

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 Endandwendung 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.

Abgekündigt: CaaS Admin Interface (caas-admin-webapp)

Das CaaS Admin Interface ermöglicht die Verwaltung der in den CaaS übertragenen Informationen und stellt eine einfache, webbasierte Administrationsoberfläche bereit. Dafür kommuniziert es über die REST-Schnittstelle mit dem Repository und ist selbst per HTTP(S) erreichbar.

Hinweis zur Abkündigung: Das CaaS Admin Interface ist mit Version 7 abgekündigt. Wir empfehlen dringend die Nutzung eines REST-Clients Ihrer Wahl.

Das CaaS Admin Interface wird im Dezember 2021 entfernt.

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-7.0.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-7.0.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 und werden standardmäßig nicht von der Auslieferung erstellt. Die Parameter adminWebapp.ingress.enabled und restApi.ingress.enabled erlauben die Ingress-Konfiguration für die REST-Schnittstelle und das CaaS Admin Interface.

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

Ingress-Erzeugung in einer custom-values.yaml

adminWebapp:
   ingress:
      enabled: true
      hosts:
         - caas-webapp.company.com

restApi:
   ingress:
      enabled: true
      hosts:
         - caas.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: extensions/v1beta1
kind: Ingress
metadata:
   labels:
   name: caas
spec:
   rules:
      - http:
      paths:
      - backend:
         serviceName: caas-rest-api
         servicePort: 80
   host: caas-rest-api.mydomain.com

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-admin-webapp-1055845989-0s4pg   1/1       Running       0          5m
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.

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.

Mongo-Datenbank

Im Gegensatz zur REST-Schnittstelle ist die 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.

Ü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:

monitoring:
  prometheus:
    alerts:
      prometheusRuleLabels:
        app: "prometheus-operator"
        release: "prometheus-operator"
      caas:
        enabled: true

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:

monitoring:
  grafana:
    dashboards:
      enabled: true
      configmapNamespace: ""
      configMapLabels: {}

4. Entwicklungsumgebung

Während Kubernetes die Basis aller produktiven Installationen bildet, können für Entwicklungsszenarien auch Docker oder Minikube genutzt werden.

Der Betrieb von Minikube unter Windows ist aktuell als experimentell gekennzeichnet und nicht in jeder Situation stabil.

Dieses Kapitel beschreibt die Umsetzung mit Docker.

Für die lokale Entwicklungsumgebung enthält die CaaS-Auslieferung die folgenden zwei Zip-Dateien:

caas-docker-images-7.0.0.zip
caas-docker-configuration-7.0.0.zip

Diese beinhalten zum einen die benötigten Docker-Images und zum anderen die benötigte Konfiguration des Docker Compose-Stacks.

Importieren Sie zunächst die Docker-Images in Ihre lokale Docker-Registry. Führen Sie dafür je nach Betriebssystem entweder das Skript install.cmd oder install.sh aus. Das Skript ist Teil der ZIP-Datei mit den Docker-Images.

Nach der Durchführung der in den folgenden Absätzen beschriebenen Konfigurationen kann die Docker Compose-Konfiguration mit dem Befehl docker-compose config überprüft und mittels docker-compose up gestartet werden.

Weitere Parameter zur Steuerung der CaaS-Plattform per Docker Compose können Sie der Docker Compose Dokumentation entnehmen.

Ressourcenlimits

Falls Sie die in der Datei docker-compose.yml hinterlegten Ressourcenlimits anpassen möchten, so beachten Sie bitte, dass die Werte der Java-Optionen Xms und Xmx jeweils niedriger sein müssen als die Werte der Parameter mem_reservation und mem_limit. Um wie viel niedriger die Werte einzustellen sind, hängt vom konkreten Lastszenario ab. Es wird ein Wert von mindestens 76 MiB für alle Komponenten empfohlen.

Authentifizierung

Das in der Auslieferung enthaltene Verzeichnis Configuration beinhaltet die Konfigurationsdatei caas-docker.env. Sie enthält alle sicherheitsrelevanten Authentifizierungsdaten, die über die Container hinweg geteilt werden.

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

CaaS Admin Interface

Das CaaS Admin Interface besitzt die Konfigurationsdatei env.js, die im Verzeichnis Configuration der Auslieferung enthalten ist. Die Datei enthält verschiedene Parameter, aus denen sich die URL der REST-Schnittstelle zusammensetzt:

Konfigurationsdatei env.js

(function (window) {
  window.__caas_config = window.__caas_config || {};
  window.__caas_config.host = 'http://CHANGE_ME';
  window.__caas_config.port = '8080';
  window.__caas_config.path = '/';
}(this));

Es ist zwingend der Parameter window.__caas_config.host anzupassen, welcher definiert, unter welchem Hostnamen die REST-Schnittstelle zu erreichen ist. Dabei ist zu beachten, dass der eingetragene Host für alle Benutzer des CaaS Admin Interfaces erreichbar sein muss. Für die lokale Entwicklung sollte daher entsprechend localhost verwendet werden

5. REST-Schnittstelle

5.1. Speicherung von Inhalten

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

http://Servername:Port/Database/Collection/Document

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

http://Servername:Port/Database/MediaCollection.files/Media

5.2. 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.2.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.

API Keys steuern die Zugriffsrechte auf Projekte und können ausschließlich vom Admin-Benutzer verwaltet werden. Details finden Sie im Abschnitt Verwaltung von API Keys.

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.2.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.2.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 generiert ein Sicherheitstoken. 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 generiert ein Sicherheitstoken-Cookie. 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.2.4. Authentifizierungsreihenfolge

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

Der Query Parameter securetoken.
Der Authorization Header.
Das Cookie securetoken.

5.3. Verwaltung von API Keys

API Keys können, wie alle anderen Ressourcen im CaaS auch, über REST-Endpunkte verwaltet werden.

Da die Verwaltung von API Keys als Teil der administrativen Aufgaben angesehen wird, sind sowohl der lesende als auch der schreibende Zugriff ausschließlich durch den Admin-Benutzer möglich.

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

GET /caas_admin/apikeys
POST /caas_admin/apikeys
zu beachten: die Parameter _id und key müssen übergeben werden und identische Werte besitzen
PUT /caas_admin/apikeys/{id}
zu beachten: der Parameter key muss denselben Wert haben wie die {id} in der URL
DELETE /caas_admin/apikeys/{id}

Zum Zugriff verwenden Sie bitte einen REST-Client Ihrer Wahl.

5.3.1. 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 /caas_admin/_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.

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 speziell diese Eigenschaft noch nicht überprüft, so wird solch eine Validierung in Zukunft sehr wahrscheinlich noch ergänzt werden.

5.4. Verwaltung von Inhalten

5.4.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.4.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. Weitere Informationen finden Sie in der RESTHeart-Dokumentation.

5.4.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.5. 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.

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 potentiell 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 des 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-7.0.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");

  (async function(){
    // Retrieving temporary auth token
    const token = await fetch(new URL("_logic/securetoken", 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.