CaaS Platform: Betriebsanleitung

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.

Dieses Dokument richtet sich an den Betreiber der CaaS-Plattform und enthält Hinweise und Anleitungen zum Betrieb und zur technischen Administration der Plattform.
Eine Beschreibung von Funktionen und Nutzungsmöglichkeiten der REST-Schnittstelle der CaaS-Plattform finden Sie in der separaten Dokumentation der REST-Schnittstelle.

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

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 deployt 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. Dieser ermöglicht das Herunter- bzw. Herauf-Skalieren 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-Schnittstelle-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.

Aktivierung des Horizontal Pod Autoscaler

Die Aktivierung des Horizontal Pod Autoscaler sowie dessen Konfiguration sind 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

Die Aktivierung des Horizontal Pod Autoscaler in den custom-values.yaml führt zur Entfernung des Parameters restApi.spec.replicas aus dem Deployment. Beim Ausrollen des Helm-Charts wird daher die Anzahl der REST-Schnittstelle-Pods einmalig auf den Standard-Wert von 1 vermindert, bevor der Horizontal Pod Autoscaler die weitere Skalierung übernimmt.

Falls dieses Verhalten vermieden werden soll, entfernen Sie vor dem Ausrollen das Replica-Feld aus dem Deployment-Manifest im Helm History Secret.

Hintergrundinformationen zur Migration auf einen Horizontal Pod Autoscaler können Sie dieser Dokumentation entnehmen.

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

Skalieren Sie das StatefulSet nicht direkt in K8s. Sollten Sie dies tun, werden bestimmte Verbindungsurls nicht korrekt sein und die zusätzlichen Instanzen werden nicht richtig verwendet. Verwenden Sie stattdessen die Custom Helm Values.

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.
Außerdem empfehlen wir, nach dem Entfernen der gelöschten Instanzen in der Replicaset-Konfiguration auch die entsprechenden Persistent Volume Claims zu löschen. Andernfalls besteht die Gefahr, dass die Instanzen bei einer zukünftigen Hochskalierung nicht mehr automatisch zum Replicaset hinzugefügt werden.

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, sodass 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 API-Key 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 mithilfe 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 deployt 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: {}
        overviewDashboardsEnabled: false

3.7. Konfiguration der REST-Schnittstelle

Die REST-Schnittstelle bietet verschiedene Konfigurationsmöglichkeiten, die in der custom-values.yaml-Datei des Helm-Charts vorgenommen werden können.

3.7.1. Mongo-Connection-String mit DNS-Seed-Liste

Im Standard verwendet die REST-Schnittstelle einen statischen Connection-String mit allen Hostnamen im Replica Set (Standard-Connection-String), um eine Verbindung zur Mongo-Datenbank herzustellen. Optional kann die REST-Schnittstelle auch so konfiguriert werden, dass sie eine DNS-Seed-Liste (SRV connection format) verwendet.

Diese Option kann durch das Setzen von restApi.mongoSrvConnectionFormat.enabled: true aktiviert werden.
Die hierfür genutzte Cluster-Domäne kann bei Bedarf im Parameter restApi.mongoSrvConnectionFormat.domain überschrieben werden.

Eine Seed-Liste ist ausschließlich für die im Chart enthaltene Mongo-Datenbank nutzbar. Für die Verbindung zu einer extern aufgesetzten MongoDB steht weiterhin nur der Standard-Connection-String zur Verfügung.

3.7.2. Metadaten bei Abfragen von Collections

Standardmäßig liefert die REST-Schnittstelle bei Abfragen von Collections, bei denen Filter genutzt werden, keine Metadaten der Collection zurück.
Sollte die Rückgabe von Metadaten gewünscht sein, so kann dies durch das Setzen von restApi.additionalConfigOverrides./noPropertiesInterceptor/enabled: false erreicht werden.

3.7.3. Ausschließen von MongoDB-Query-Operatoren in Filterabfragen

Es können bestimmte MongoDB-Query-Operatoren für die Nutzung in Filterabfragen ausgeschlossen werden. Dies geschieht durch Hinzufügen der gewünschten Operatoren zu einer Blacklist.

Zur Aktivierung des Features ist restApi.filterOperatorBlacklist.enabled: true zu setzen.
Die Operatoren werden dazu in restApi.filterOperatorBlacklist.value: [] angegeben werden.

Weitere Informationen finden Sie in dieser Dokumentation.

3.7.4. Auflösen von Referenzen bei Dokumentenabfragen

Bei der Abfrage von Dokumenten, die Referenzen auf andere Dokumente enthalten, werden diese Referenzen automatisch aufgelöst und die referenzierten Dokumente in das Ergebnis eingebettet.

Die maximale Tiefe der Referenzauflösung kann mit dem Value restApi.additionalConfigOverrides./refResolvingInterceptor/max-depth konfiguriert werden.

Die maximale Anzahl von Referenzen, die in einem Request aufgelöst werden kann, ist mit dem Value restApi.additionalConfigOverrides./refResolvingInterceptor/limit zu konfigurieren.

Die Auflösung kann mit dem Value restApi.additionalConfigOverrides./refResolvingInterceptor/enabled: false deaktiviert werden.

3.7.5. Aktivieren und Konfigurieren von GraphQL

Zur Aktivierung von GraphQL ist restApi.graphql.enabled: true zu setzen.

Standard- und maximale Seitengröße sind mit den Parametern restApi.graphql.pageSize.default und restApi.graphql.pageSize.max konfigurierbar.

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

5.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 der Performance der REST-Schnittstelle können im Prometheus-Format unter den folgenden URLs abgerufen werden:

http://REST-HOST:PORT/_logic/metrics
http://REST-HOST:PORT/_logic/metrics-caas
http://REST-HOST:PORT/_logic/metrics-jvm

5.2. MongoDB

Die Metriken der MongoDB werden über einen Sidecar Container zur 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.

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

6.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 ein guter 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 Protokolldateien können nur für den aktuell laufenden Container eingesehen werden. Aus diesem Grund ist es notwendig, einen persistenten Speicher einzurichten, um auf die Protokolldateien von bereits beendeten oder neu gestarteten Containern zugreifen zu können.

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

6.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 Kommando

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

7. Appendix

7.1. Troubleshooting: Bekannte Fehler

7.1.1. Dateiupload mit PUT Request schlägt fehl

Die Fehlermeldungen

E11000 duplicate key error collection: [some-file-bucket].chunks index: files_id_1_n_1 dup key oder
error updating the file, the file bucket might have orphaned chunks

deuten darauf hin, dass verwaiste File Chunks in den MongoDB Daten existieren. Die verwaisten Daten können mit folgendem mongo Shell Skript gelöscht werden:

Bereinigung eines Files Buckets durch Löschen verwaister File Chunks.

// Name of the file bucket to clean up (e.g., my-bucket.files)
var filesBucket = "{YOUR_FILE_BUCKET_NAME}";

var chunksCollection = filesBucket.substring(0, filesBucket.lastIndexOf(".")) + ".chunks";
db[chunksCollection].aggregate([
  // avoid accumulating binary data in memory
  { $unset: "data" },
  {
      $lookup: {
        from: filesBucket,
        localField: "files_id",
        foreignField: "_id",
        as: "fileMetadata",
      }
  },
  { $match: { fileMetadata: { $size: 0 } } }
]).forEach(function (c) {
  db[chunksCollection].deleteOne({ _id: c._id });
  print("Removed orphaned GridFS chunk with id " + c._id);
});

8. Hilfe

Der Technical Support der Crownpeak Technology GmbH 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.