CaaS Platform

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.

Die Konfiguration des Repositories umfasst zwei Parameter:

openssl rand -base64 756

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

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.

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.

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.

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.

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.

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:

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

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.

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.

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:

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:

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:

Anfragen mit API Key müssen einen HTTP-Header mit Bearer Token enthalten: Authorization: Bearer <key>. 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.

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:

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

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

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.

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.

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:

https://REST-HOST:PORT/<database>/products?filter={fs_language:"EN"}

CaaS-Dokumente können andere CaaS-Dokumente referenzieren. Bei der Verarbeitung von Dokumenten werden die referenzierten Inhalte häufig direkt benötigt. Um sequentielle Abfragen in diesen Fällen zu verhindern, kann der Query Parameter resolveRef verwendet werden.

Die folgenden zwei JSON-Dokumente zeigen dies beispielhaft:

Im ersten Dokument steht im JSON unter formData.ps_audio.value.url eine absolute URL auf ein anderes Dokument im CaaS. Folgender Request zeigt beispielhaft, wie diese Referenz im gleichen Request aufgelöst wird, der das Dokument ausliest.

Der Wert des Query-Parameters muss dabei den Pfad im JSON zu der URL angeben. Die Antwort enthält dann ein zusätzliches Attribut _resolvedRefs:

Der Parameter resolveRef wird auch für Collection-Anfragen unterstützt. In diesem Fall werden die Referenzen in allen zurückgegebenen Dokumenten aufgelöst. Die Dokumente der aufgelösten Referenzen werden dabei in einem neuen, zusätzlichen Dokument gesammelt, welches wiederum zum Array der Antwort hinzugefügt wird.

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.

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.

Die Autorisierung eines API Keys wird auf Basis jeder Berechtigung ausgeführt, die Teil des API Keys sind. Die Berechtigungen werden im permissions Attribut des API Keys definiert.

Bei der Prüfung einer Berechtigung wird das url-Attribut herangezogen. Dessen Wert wird gegen den URL-Pfad eines eingehenden Requests geprüft. Die Art der Prüfung ist abhängig vom Modus der Berechtigung.

Es gibt drei verschiedene Modi:

Unterscheidung lokaler und globaler API Key

Die folgende Tabelle zeigt beispielhaft den Unterschied bei der Autorisierung von lokalen oder globalen API Keys mit der Verwendung des Berechtigungsmodus PREFIX oder REGEX.

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

Die Datenbank richtet sich nach dem Typ des API Keys.

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

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.

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.

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 https:/REST-HOST:PORT/<database>/<collection>/_indexes/ abgerufen werden.

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.

Um eine GraphQL-Applikation zu erstellen oder zu aktualisieren, wird eine PUT-Anfrage mit der App-Definition an die folgende URL gestellt:
https://REST-HOST:PORT/<tenant>/gql-apps/<tenant>___<name>

Eine GraphQL-Applikation kann die Daten mittels einer MongoDB Query oder Aggregation abfragen. Das Kapitel Object Mappings der RestHeart Dokumentation enthält genauere Informationen. Ein Beispiel einer GraphQL-Applikation, die eine Aggregation nutzt, ist im Anhang zu finden.

Durch das Erstellen der Definition wird ein Endpunkt unter folgender URL provisioniert:
https://REST-HOST:PORT/graphql/<tenant>___<name>

Weitere Informationen über die Ausführung von GraphQL-Abfragen befinden sich im Kapitel GraphQL-API.

Zur Erstellung einer GraphQL-Applikation bestehen zwei Möglichkeiten:

Verwendung des JSON Body ("application/json")

Die App-Definition mit den Bereichen descriptor, schema und mapping wird mit dem Request-Body (Content-Type application/json) übergeben. Der Parameter descriptor.uri muss mit dem letzten Pfadsegment der URL übereinstimmen (d.h. <tenant>___<name>) und ist im CaaS - abweichend von den Angaben in der RESTHeart Dokumentation - nicht optional.

Verwendung des Datei-Uploads ("multipart/form-data")

Die App-Definition und das Schema können auch mit einem Multipart-Upload (Content-Type multipart/form-data) erstellt/aktualisiert werden. Dies ermöglicht die Speicherung der App-Definition und des Schemas als separate Dateien und, was noch wichtiger ist, das Schema muss bei der Erstellung/Aktualisierung der Applikation nicht in JSON kodiert werden.

Um die App-Definition und das Schema hochzuladen, müssen beide als einzelne Teile im Request enthalten sein:

Um eine GraphQL-Applikationen zu löschen, wird eine DELETE-Anfrage an die folgende URL gestellt:
https://REST-HOST:PORT/<tenant>/gql-apps/<tenant>___<name>

Unter bestimmten Bedingungen, wie zum Beispiel nach der Wiederherstellung einzelner Collections aus einem Backup, kann es vorkommen, dass die zuvor erstellten GraphQL-Applikationen nicht mehr synchronisiert sind. In so einem Fall müssen alle Tenant-spezifischen GraphQL-Applikationen neu synchronisiert werden.

Um alle vorhandenen GraphQL-Applikationen aller Tenants neu zu synchronisieren, ist eine POST-Anfrage gegen den HTTP-Endpunkt /_logic/sync-gql-apps auszuführen.

In diesem Kapitel wird ein Anwendungsfall für eine GraphQL-Applikation exemplarisch beschrieben. Dazu werden die einzelnen Schritte skizziert, die zum Anlegen einer GraphQL-Applikation und der späteren Nutzung gehören.

Anlegen der GraphQL-App-Definition

In dem Beispielszenario wird eine GraphQL-Applikation angelegt, mit der man im CaaS liegende Datensätze abfragen kann. Als Datensätze werden hier die Produkte aus dem Beispielprojekt der fiktiven Firma “Smart Living” verwendet. In den Datensätzen befindliche Bildreferenzen und Produktkategorien werden dabei direkt aufgelöst.

Der gesamte Aufruf zur Erstellung der GraphQL-App-Definition für dieses Beispielszenario sieht wie folgt aus.

Schema der GraphQL-App-Definition
Das Schema, welches für das Beispiel verwendet wird, enthält folgende Definitionen.

In den Zeilen 1, 9 und 14 des Schemas beginnen die Typdefinitionen der Objekte, die in der GraphQL-Applikation verwendet werden. Zudem enthält jedes GraphQL-Schema einen Query Type (Zeile 22), in dem definiert wird, welche Daten von einer GraphQL-Applikation abgefragt werden können. Mehr Details zu Schemas in GraphQL können der GraphQL-Dokumentation entnommen werden.

In diesem Beispiel werden wir Produktdatensätze abfragen. Das wird in Zeile 23 des Schemas durch den Typen [Product] ermöglicht. Bei den Abfragen sollen die Sprachen angegeben werden können, für die wir Produkte erhalten wollen. Die Angabe der Sprache soll in diesem Beispiel optional sein. Diese Anforderung wird durch die Angabe einer Variablen mit dem Namen _language ermöglicht, die mit dem Standardwert ["DE", "EN"] vorbelegt ist.

Mapping der GraphQL-App-Definition
Das Mapping der GraphQL-App-Definition stellt die Verbindung zwischen dem Schema und den Daten in der Datenbank dar. Jeder Type, welcher im Schema beschrieben ist, benötigt im Allgemeinen einen expliziten Eintrag, daher ist dieser Teil einer GraphQL-App-Definition meist der längste. Es kann Situation geben, in denen die Felder im Type exakt so heißen sollen, wie die Schlüssel der Daten. In diesem Spezialfall ist kein expliziter Eintrag im Mapping notwendig. Details zu dem Mapping in GraphQL-App-Definition finden Sie in dem entsprechenden Kapitel in der RESTHeart-Dokumentation.
Das folgende Beispiel ist ein Auszug aus dem Anlegen einer GraphQL-App-Definition und klärt einige Anwendungsfälle auf.

Der erste Anwendungsfall, der betrachtet wird, ist das sogenannte “Field to Field mapping”. Bei dieser Art Mapping wird einem Feld im Type ein entsprechendes Attribut der Daten zugewiesen. Ein Beispiel dafür ist in Zeile 3 zu sehen, bei dem das Feld Category.name aus dem Schema auf Attribut displayName aus den Daten verweist.

Der zweite Anwendungsfall ist das “Field to Query mapping”. Hierbei wird einem Feld im Type das Ergebnis einer Datenabfrage zugewiesen. Ein Beispiel für ein solches Mapping ist in Zeile 45ff. zu finden: das Feld Query.products wird abgebildet durch die Daten, die in der REST-Schnittstelle unter /mycorp-dev/d8db6f24-0bf8-4f48-be47-5e41d8d427fd.preview.content zu finden sind und den Filtern entityType": "product" und "locale.identifier": { "$in": { "$arg": "_language" } } entsprechen. Das bedeutet, dass genau die Produkte abgefragt werden, welche in der definierten Quelle liegen, eine Entität von “product” darstellen und eines der Sprachkürzel verwenden, die im Argument “_language” übergeben werden.

Ein weiteres Beispiel für ein “Field to Query mapping” ist ab Zeile 29 zu finden. In dieser Abbildungsdefinition werden die Produktkategorien, welche in separaten Datensätzen gepflegt sind, über eine Fremdschlüsselbeziehung identifiziert. Der komplette Eintrag von Zeile 29-42 sagt aus, dass in dem Feld Product.categories alle Produktkategorien aufgeführt werden, die unter /mycorp-dev/d8db6f24-0bf8-4f48-be47-5e41d8d427fd.preview.content liegen, deren identifier im Feld formData.tt_categories.value.identifier hinterlegt sind und deren locale.identifier exakt dem entspricht, was im Produktdatensatz als locale.identifier vorhanden ist. Da ein Produkt mehrere Kategorien im Datensatz unter formData.tt_categories.value.identifier referenzieren kann, wird hier mit dem Schlüssel $in gearbeitet.

Verwenden der GraphQL-Applikation

Abfragen können nun an die GraphQL-Applikation gesendet werden.

Dieses Beispiel zeigt die Abfrage der GraphQL-Applikation mit curl. Die Applikation steht immer unter dem Pfad /graphql/<descriptor.uri> zur Verfügung. Durch diese Query werden Produktdaten abhängig von der Variable $lang abgefragt. Die Variable wird dem im Schema definierten Argument _language als Wert übergeben. Da in der GraphQL-App-Definition ein sinnvoller Standardwert für _language im Schema enthalten ist, ist die Verwendung von Variablen in diesem Szenario optional. Weitere Details zu Argumenten und Variablen können der GraphQL-Dokumentation entnommen werden.

Durch Aggregationen können komplexere Abfragen an den CaaS gestellt werden. So können z.B. dynamisch Attribute zu den Dokumenten der Antwort hinzugefügt werden. Es können aber noch deutlich komplexere Aggregationen erstellt werden. Eine Liste der zur Verfügung stehenden Aggregation Stages und Operators ist hier zu finden.

Diese Anleitung beinhaltet das Anlegen und Benutzen von GraphQL-Applikationen. Um die Anleitung abzuschließen, ist ein Grundverständnis der REST-Schnittstelle in Bezug auf Authentifizierung und der Abfrage von Dokumenten notwendig.

GraphQL-Applikationen ermöglichen das Abfragen von CaaS-Dokumenten über eigene GraphQL API-Endpunkte. Dabei stellen die Endpunkte die Dokumentendaten in einem selbst-definierten Format/Schema bereit.

In den folgenden Schritten werden wir beispielhaft eine GraphQL-Applikation erzeugen und benutzen, um Dokumentendaten abzufragen. Zum Senden der HTTP Anfragen wird curl benutzt.

Die Fehlermeldungen

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: