Externen Cassandra-Datenspeicher verwenden

In diesem Thema wird beschrieben, wie Sie eine Apigee Hybrid-Laufzeit mit einem Cassandra-Datenspeicher in einem anderen Kubernetes-Cluster verbinden. In dieser Konfiguration hat der Laufzeitcluster keine Cassandra-Pods. Der Name dieser Konfiguration ist der Modus externer Datenspeicher.

Topologie mit zwei Clustern

Im externen Datastore-Modus werden zwei Kubernetes-Cluster verwendet:

  • Im Cassandra-Cluster wird der Cassandra-Ring ausgeführt. Die Hybrid-Laufzeitkomponenten werden nicht ausgeführt.
  • Im Laufzeitcluster werden die Hybrid-Laufzeitkomponenten ausgeführt, er enthält jedoch keine Cassandra-Pods. Die Laufzeitkomponenten stellen über das Netzwerk eine Verbindung zum Cassandra-Ring im Cassandra-Cluster her.

Der Apigee-Operator wird in beiden Clustern ausgeführt. Sie installieren Cert-Manager, die benutzerdefinierten Ressourcendefinitionen (CRDs) von Apigee und das apigee-operator-Diagramm in jedem Cluster. In der folgenden Tabelle sind die Komponenten in den einzelnen Clustern aufgeführt:

Komponente Cassandra-Cluster Laufzeitcluster
cert-manager Ja Ja
Apigee-CRDs und das apigee-operator-Diagramm Ja Ja
Diagramm „apigee-datastore“ Ja, mit den Cassandra-Pods Ja, mit replicaCount: 0 und ohne Cassandra-Pods
Alle anderen Hybrid-Diagramme, z. B. apigee-telemetry, apigee-redis, apigee-ingress-manager, apigee-org, apigee-env und apigee-virtualhost Nein Ja

Der Apigee-Operator hat in jedem Cluster eine andere Aufgabe:

  • Im Cassandra-Cluster erstellt der Operator die Cassandra-Pods. Außerdem wird der Cassandra-Lebenszyklus verwaltet, z. B. wenn Sie den Ring skalieren.
  • Im Laufzeitcluster erstellt der Operator keine Cassandra-Pods. Damit wird ein monitorloser Dienst und ein Endpunkte-Objekt erstellt, das auf den Cassandra-Ring im Cassandra-Cluster verweist. Wenn Sie die dynamische Endpunktsynchronisierung aktivieren, liest der Operator im Laufzeitcluster die Cassandra-Endpunkte auch aus dem Cassandra-Cluster.

Einrichtung: Übersicht

Führen Sie die folgenden Schritte in der angegebenen Reihenfolge aus. Die Reihenfolge ist wichtig. Die gemeinsame Zertifizierungsstelle (Certificate Authority, CA) muss sich im Laufzeitcluster befinden, bevor der Laufzeitcluster Zertifikate ausstellt. Weitere Informationen finden Sie unter Apigee-Zertifizierungsstelle vor der Installation des Operators freigeben.

  1. Installieren Sie im Cassandra-Cluster cert-manager, die Apigee-CRDs, das apigee-operator-Diagramm und das apigee-datastore-Diagramm.
  2. Prüfen Sie, ob die Cassandra-Pods im Cassandra-Cluster bereit sind.
  3. Installieren Sie cert-manager im Laufzeitcluster.
  4. Kopieren Sie das Secret apigee-ca aus dem Cassandra-Cluster in den Laufzeitcluster. Führen Sie diesen Schritt aus, bevor Sie das apigee-operator-Diagramm im Laufzeitcluster installieren.
  5. Installieren Sie die Hybrid-Laufzeitkomponenten im Laufzeitcluster. Verwenden Sie die Überschreibungen für externe Datenspeicher für das apigee-datastore-Diagramm. Verwenden Sie dieselben Cassandra-Anmeldedaten wie im Cassandra-Cluster.
  6. (Empfohlen) Dynamische Endpunktsynchronisierung aktivieren.
  7. Verbindung prüfen

Die Schritte zum Installieren der einzelnen Diagramme finden Sie unter Apigee Hybrid über Helm installieren.

Hinweis

Ihre Umgebung muss die folgenden Anforderungen erfüllen:

  • Netzwerkverbindung zu Cassandra: Der Laufzeitcluster muss über den TCP-Port 9042 eine Verbindung zu den Cassandra-Pods herstellen. Platzieren Sie die beiden Cluster in einer gemeinsam genutzten VPC oder in Netzwerken mit einer privaten Verbindung zwischen ihnen.
  • Eine Region. Platzieren Sie die beiden Cluster in derselben Region. Die Umlaufzeit zwischen den Clustern erhöht die Latenz jeder Laufzeitanfrage.
  • cert-manager in beiden Clustern In jedem Cluster stellt cert-manager die Zertifikate für die mTLS-Verbindung zwischen der Laufzeit und Cassandra aus. Installieren Sie cert-manager im Cassandra-Cluster und im Laufzeitcluster.
  • Eine Route zu jedem Cassandra-Pod. Der Cassandra-Client-Treiber stellt eine direkte Verbindung zu jedem Cassandra-Pod her. Der Laufzeitcluster muss eine Verbindung zur IP-Adresse jedes Cassandra-Pods herstellen, nicht nur zu einer Adresse. Ein Load Balancer oder eine einzelne virtuelle IP-Adresse vor dem Ring erfüllt diese Anforderung nicht.
  • Netzwerkverbindung zum Kubernetes API-Server Diese Anforderung gilt nur, wenn Sie die dynamische Endpunktsynchronisierung verwenden. Der Laufzeitcluster muss eine Verbindung zum Kubernetes API-Server des Cassandra-Clusters herstellen.

Apigee-CA freigeben, bevor Sie den Operator installieren

Installieren Sie cert-manager im Laufzeitcluster. Kopieren Sie dann das CA-Secret aus dem Cassandra-Cluster in den Laufzeitcluster: 

kubectl --context CASSANDRA_CLUSTER -n cert-manager get secret apigee-ca -o yaml \
  | grep -v -E '^\s+(resourceVersion|uid|creationTimestamp|selfLink):' \
  | kubectl --context RUNTIME_CLUSTER -n cert-manager apply -f -

Ersetzen Sie Folgendes:

  • CASSANDRA_CLUSTER: Der kubectl-Kontext des Cassandra-Clusters.
  • RUNTIME_CLUSTER: der kubectl-Kontext des Laufzeitclusters.

Mit dem Befehl grep werden die Metadatenfelder entfernt, die zum Cassandra-Cluster gehören. Der Kubernetes API-Server erstellt kein Objekt mit einem resourceVersion-Wert.

Bei multiregionalen Installationen wird dasselbe Prinzip der gemeinsamen Zertifizierungsstelle verwendet. Einen ähnlichen Kopierschritt finden Sie unter Root-CA-Zertifikat rotieren. Informationen zur Cassandra-mTLS-Konfiguration finden Sie unter Authentifizierung für Cassandra konfigurieren.

Verwenden Sie in beiden Clustern dieselben Cassandra-Anmeldedaten.

Verwenden Sie eine der folgenden Methoden in den Überschreibungsdateien der beiden Cluster:

  • Legen Sie dieselben Nutzernamen und Passwörter in cassandra.auth fest: default, admin, ddl, dml, jmx und jolokia.
  • Legen Sie dazu cassandra.auth.secret fest. Das Secret muss in jedem Cluster dieselben Nutzer und Passwörter enthalten. Weitere Informationen finden Sie unter Secret erstellen.
  • Legen Sie cassandra.auth.secretProviderClass auf eine SecretProviderClass fest, die denselben Secret-Speicher liest. Weitere Informationen finden Sie unter Cassandra-Secrets in Hashicorp Vault speichern.

Sie kopieren das Secret für Anmeldedaten nicht aus dem Cassandra-Cluster. Das Diagramm im Laufzeitcluster erstellt das Secret aus Ihren Überschreibungen. Informationen zum Beheben von Authentifizierungsfehlern finden Sie unter Verbindung prüfen.

Externen Datenspeicher konfigurieren

Im Laufzeitcluster dürfen durch das apigee-datastore-Diagramm keine Cassandra-Pods erstellt werden. Er muss auf den Cassandra-Ring im Cassandra-Cluster verweisen. Fügen Sie der Überschreibungsdatei des Laufzeitclusters die folgenden cassandra-Einstellungen hinzu: 

cassandra:
  # No Cassandra pods in the runtime cluster.
  replicaCount: 0
  properties:
    # A comma-separated list of the Cassandra pod IP addresses.
    externalHost: "CASSANDRA_IP_ADDRESSES"
  storage:
    # Required, even with replicaCount: 0.
    storageSize: "10Gi"

Wobei:

  • CASSANDRA_IP_ADDRESSES ist eine durch Kommas getrennte Liste der IP-Adressen der Cassandra-Pods im Cassandra-Cluster. Beispiel: 10.0.0.1:9042,10.0.0.2:9042,10.0.0.3:9042. Das Suffix :9042 ist optional. Führen Sie den folgenden Befehl aus, um die Liste abzurufen: 
    kubectl --context CASSANDRA_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra \
  -o jsonpath='{.items[*].status.podIP}' | tr ' ' ','
  • APIGEE_NAMESPACE ist Ihr Apigee-Namespace. Der Standardwert ist apigee.
  • replicaCount: 0 weist den Operator an, keine Cassandra-Pods im Laufzeitcluster zu erstellen. Der Operator erstellt einen monitorlosen Dienst und ein Endpunkte-Objekt, die auf die externalHost-Adressen verweisen.
  • cassandra.properties.externalHost ist eine durch Kommas getrennte Liste von Cassandra-IP-Adressen. Jede Adresse kann das Suffix :port haben, der Operator ignoriert jedoch den Port und verwendet immer Port 9042. Der Operator akzeptiert nur IP-Adressen. Hostnamen und DNS-Namen werden ignoriert und für jeden ignorierten Eintrag wird eine Warnung in das Log geschrieben.
  • cassandra.storage.storageSize ist erforderlich, aber im Laufzeitcluster werden keine PersistentVolumes für Cassandra erstellt. Der ApigeeDatastore-Validierungs-Webhook prüft immer storageSize. Verwenden Sie eine gültige Menge, z. B. 10Gi.

Die IP-Adresse eines Pods ändert sich, wenn Sie den Ring skalieren und wenn Kubernetes einen Pod neu plant. Dann ist die Liste in externalHost nicht mehr korrekt. Wir empfehlen daher die dynamische Endpunktsynchronisierung. Durch die dynamische Endpunktsynchronisierung wird die Liste der Cassandra-Pod-IP-Adressen automatisch auf dem neuesten Stand gehalten. Verwenden Sie externalHost nur für eine einfache Installation oder für die Ersteinrichtung.

Endpunkte mit der dynamischen Endpunktsynchronisierung auf dem neuesten Stand halten

Bei externalHost müssen Sie Ihre Überschreibungen jedes Mal bearbeiten, wenn sich der Cassandra-Ring ändert. Mit der dynamischen Endpunktsynchronisierung entfällt dieser manuelle Schritt. Der Operator im Laufzeitcluster liest die bereiten Cassandra-Endpunkte in regelmäßigen Abständen aus dem Cassandra-Cluster. Anschließend werden diese Endpunkte in das Endpoints-Objekt im Laufzeitcluster kopiert.

Wir empfehlen die dynamische Endpunktsynchronisierung. Pod-IP-Adressen ändern sich jedes Mal, wenn Sie den Ring skalieren oder Kubernetes einen Pod neu plant. Beim dynamischen Endpunktsynchronisieren werden die IP-Adressen der bereiten Pods des monitorlosen Cassandra-Dienstes gelesen. Daher enthält das Endpoints-Objekt im Laufzeitcluster immer die aktuellen Cassandra-Pod-IP-Adressen.

Bei der dynamischen Endpunktsynchronisierung ist externalHost weiterhin erforderlich. Der Operator verwendet sie unter diesen beiden Bedingungen:

  • Vor dem ersten erfolgreichen Lesen aus dem Cassandra-Cluster.
  • Wenn ein Lesevorgang aus dem Cassandra-Cluster fehlschlägt und keine Endpunkte aus einem vorherigen erfolgreichen Lesevorgang vorhanden sind.

Wenn ein Lesevorgang fehlschlägt und Endpunkte aus einem vorherigen erfolgreichen Lesevorgang vorhanden sind, behält der Operator diese Endpunkte bei. Die Laufzeit behält die Verbindung zu Cassandra bei.

Wenn Sie die dynamische Endpunktsynchronisierung aktivieren möchten, fügen Sie den Block externalEndpointsSync in die Überschreibungsdatei des Laufzeitclusters ein: 

cassandra:
  replicaCount: 0
  properties:
    # The first endpoints, and the fallback if a read fails.
    externalHost: "CASSANDRA_IP_ADDRESSES"
    externalEndpointsSync:
      # A secret in the runtime cluster. Its "kubeconfig" key holds the
      # kubeconfig for the Cassandra cluster.
      secretRef: apigee-remote-cass-kubeconfig
      # The namespace of the Cassandra headless Service in the Cassandra cluster.
      namespace: apigee
      # The Cassandra headless Service in the Cassandra cluster.
      serviceName: apigee-cassandra-default
      # The interval between reads, in seconds. The default is 30.
      intervalSeconds: 30
  storage:
    storageSize: "10Gi"

Schreibgeschütztes Dienstkonto im Cassandra-Cluster erstellen

Der Operator im Laufzeitcluster verwendet eine kubeconfig-Datei, um eine Verbindung zum Cassandra-Cluster herzustellen. Für diese kubeconfig muss ein schreibgeschütztes Dienstkonto mit der geringsten Berechtigung verwendet werden. Dieses ServiceAccount kann nur die Cassandra-Endpunkte lesen. Es kann keine Ressourcen im Cassandra-Cluster ändern.

Erstellen Sie im Cassandra-Cluster die folgenden Ressourcen:

  • Ein Dienstkonto, z. B. apigee-endpoint-reader.
  • Eine Rolle und eine Rollenbindung im Cassandra-Namespace. Die Rolle gewährt nur die Verben get, list und watch für den Kern endpoints. Geben Sie keine anderen Verben an, z. B. create, update, patch oder delete. Keinen Zugriff auf andere Ressourcen gewähren.
  • Ein Secret mit einem langlebigen Token für das Dienstkonto.

Erstellen Sie dann eine kubeconfig-Datei für den Kubernetes API-Server des Cassandra-Clusters. Für diese kubeconfig muss das Token des Dienstkontos verwendet werden. Erstellen Sie im Laufzeitcluster ein Secret mit dem Namen, den Sie in externalEndpointsSync.secretRef festgelegt haben. Fügen Sie die kubeconfig in den Schlüssel kubeconfig ein: 

kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE create secret generic \
  apigee-remote-cass-kubeconfig --from-file=kubeconfig=READER_KUBECONFIG_FILE

Ersetzen Sie READER_KUBECONFIG_FILE durch den Pfad zur kubeconfig-Datei für das schreibgeschützte Dienstkonto.

Die kubeconfig-Datei enthält ein Langzeit-Token. Bewahren Sie dieses Secret so sicher auf wie Ihre anderen Anmeldedaten.

Synchronisierung dynamischer Endpunkte überwachen

Wenn ein Lesevorgang aus dem Cassandra-Cluster fehlschlägt, behält die Laufzeit die Verbindung bei. Die Endpunkte im Laufzeitcluster ändern sich jedoch erst, wenn ein Lesevorgang wieder erfolgreich ist. Behalten Sie die Synchronisierung im Blick, damit Sie einen dauerhaften Fehler erkennen, bevor sich der Cassandra-Ring ändert.

Der Operator im Laufzeitcluster gibt diese Signale aus:

  • Die Bedingung EndpointSyncDegraded im Status der Ressource ApigeeDatastore. Der Zustand ändert sich nach drei aufeinanderfolgenden fehlgeschlagenen Lesevorgängen zu True. Der Grund ist RemoteReadFailed oder NoReadyRemoteEndpoints. Nach einem erfolgreichen Lesevorgang ändert sich der Zustand in False mit dem Grund SyncSucceeded.
  • Der Messwert external_endpoint_sync_last_success_timestamp. Dieser Messwert gibt die Zeit des letzten erfolgreichen Lesevorgangs in Unix-Sekunden an.
  • Der Messwert external_endpoint_sync_failures_total. Mit diesem Messwert werden die fehlgeschlagenen Lesevorgänge gezählt.

Die beiden Messwerte haben die Labels namespace und name der Ressource ApigeeDatastore. Der Betreiber zeigt sie an seinem Messwerte-Endpunkt an.

Führen Sie den folgenden Befehl aus, um die Bedingung aufzurufen:

kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get apigeedatastore default \
  -o jsonpath='{.status.conditions}'

Wir empfehlen eine Benachrichtigung für die Bedingung EndpointSyncDegraded. Der Status ApigeeDatastore bleibt beim Neustart des Operators erhalten. Nur bei einem erfolgreichen Lesevorgang wird die Bedingung auf False gesetzt.

Wenn Sie auch eine Benachrichtigung für den Messwert verwenden, senden Sie eine Benachrichtigung, wenn einer der beiden Ausdrücke zutrifft:

  • time() - external_endpoint_sync_last_success_timestamp > 300
  • absent(external_endpoint_sync_last_success_timestamp)

Der Operator legt die Messwerte erst nach einem erfolgreichen Lesevorgang fest. Wenn der Operator neu gestartet wird, während die Lesevorgänge fehlschlagen, ist der Messwert nicht vorhanden. Dann stimmt der erste Ausdruck nicht überein und nur der zweite Ausdruck löst die Benachrichtigung aus.

Verbindung prüfen

Führen Sie nach der Installation der Laufzeitkomponenten die folgenden Prüfungen im Laufzeitcluster durch:

  1. Prüfen Sie, ob der Laufzeitcluster keine Cassandra-Pods hat:

    kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra

    Die Ausgabe lautet No resources found.

  2. Prüfen Sie, ob das Endpoints-Objekt auf den Cassandra-Ring verweist:

    kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get endpoints apigee-cassandra-default

    In der Spalte ENDPOINTS werden die Cassandra-IP-Adressen angezeigt. Wenn Sie die dynamische Endpunktsynchronisierung verwenden, sind dies die IP-Adressen der einsatzbereiten Cassandra-Pods im Cassandra-Cluster.

  3. Prüfen Sie, ob die Cassandra-Einrichtungsjobs abgeschlossen wurden:

    kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get jobs \
  | grep -E 'apigee-cassandra-(schema|user)-setup'

    In der Spalte COMPLETIONS wird 1/1 für jeden Job angezeigt. Wenn ein Job nicht abgeschlossen wird, prüfen Sie das Joblog auf Authentifizierungsfehler. Achten Sie dann darauf, dass die beiden Cluster dieselben Cassandra-Anmeldedaten verwenden.

Cassandra-Ring skalieren

Der Apigee-Operator im Cassandra-Cluster ist für den Cassandra-Lebenszyklus verantwortlich. Skalieren Sie Cassandra im Cassandra-Cluster. Sie können Cassandra nicht über den Laufzeitcluster skalieren.

Es gelten dieselben Regeln wie für einen Cassandra-Ring im Laufzeitcluster:

  • Skalieren Sie Cassandra in Vielfachen von drei. So wird der Ring auf drei Verfügbarkeitszonen verteilt.
  • Bevor Sie die Anzahl der Pods erhöhen, prüfen Sie, ob der Cassandra-Cluster über genügend Knotenkapazität verfügt.
  • Wenn Sie die dynamische Endpunktsynchronisierung nicht verwenden, müssen Sie externalHost nach jedem Skalierungsvorgang aktualisieren.

Weitere Informationen finden Sie unter Cassandra skalieren.

Nächste Schritte