Cassandra Go-Client zum Herstellen einer Verbindung zu Spanner Omni verwenden

Der Cassandra Go-Client für Spanner verbindet Anwendungen, die für die Apache Cassandra-Datenbank geschrieben wurden, mit Spanner. Der Client funktioniert mit Spanner Omni genauso wie mit Spanner. Da Spanner das Cassandra v4-Wire-Protokoll nativ unterstützt, können Go-Anwendungen, die den gocql-Treiber verwenden, oder Nicht-Go-Anwendungen und -Tools wie cqlsh mit diesem Client eine Verbindung zu einer Spanner-Datenbank herstellen.

Dieser Client fungiert als lokaler TCP-Proxy. Es fängt die Rohbytes des Cassandra-Protokolls ab, die von einem Treiber oder Client-Tool gesendet werden. Anschließend werden diese Bytes und die erforderlichen Metadaten in gRPC-Nachrichten verpackt, um mit Spanner Omni zu kommunizieren. Der Client übersetzt Antworten von Spanner Omni zurück in das Cassandra-Wire-Format und sendet sie zurück an den ursprünglichen Treiber oder das ursprüngliche Tool.

In diesem Dokument wird beschrieben, wie Sie den Client mit Spanner Omni integrieren. Dazu haben Sie folgende Möglichkeiten:

  • In-Process-Abhängigkeit: Verwenden Sie diese Methode für Go-Anwendungen, die bereits den gocql-Treiber verwenden. Bei diesem Ansatz wird der Client in den Anwendungsprozess eingebettet, sodass nur minimale Codeänderungen erforderlich sind.

  • Sidecar-Proxy: Verwenden Sie diese Methode für Anwendungen, die nicht in Go geschrieben sind, oder wenn Sie externe Cassandra-Tools wie cqlsh verwenden. Bei diesem Ansatz wird der Client als eigenständiger Prozess ausgeführt.

Weitere Informationen zur Funktionsweise von Apache Cassandra mit Spanner finden Sie unter Cassandra-Schnittstelle.

Wann sollte der Spanner Cassandra Go-Client verwendet werden?

Dieser Client ist in den folgenden Szenarien nützlich:

  • Spanner mit minimalem Refactoring verwenden Sie möchten Spanner als Backend für Ihre Go-Anwendung verwenden, aber lieber die vertraute gocql API für den Datenzugriff nutzen.

  • Cassandra-Tools verwenden, die nicht in Go geschrieben sind: Sie möchten mit Standard-Cassandra-Tools wie cqlsh oder mit Anwendungen, die in anderen Sprachen geschrieben wurden und Cassandra-Treiber verwenden, eine Verbindung zu Spanner herstellen.

Client als In-Process-Abhängigkeit verwenden

Go-Anwendungen stellen eine Verbindung zu Spanner Omni her, indem sie den Spanner Cassandra Go-Client als In-Process-Abhängigkeit einbinden. Bei diesem Ansatz wird die Proxy-Logik direkt in Ihre Anwendung eingebettet. Dadurch wird die Bereitstellungsarchitektur vereinfacht, da kein separater Prozess erforderlich ist. Diese Konfiguration bietet auch eine optimale Leistung, da ein zusätzlicher Netzwerk-Hop und eine zusätzliche Serialisierung und Deserialisierung der Daten vermieden werden.

So verwenden Sie den Client als In-Process-Abhängigkeit:

  • Importieren Sie das Spanner-Paket in Ihre Go-Anwendung:

    import spanner "github.com/googleapis/go-spanner-cassandra/cassandra/gocql"

  • Ändern Sie den Code zum Erstellen des Clusters. Verwenden Sie anstelle von gocql.NewCluster spanner.NewCluster und geben Sie die folgenden Spanner Omni-spezifischen Optionen an:

    Nur-Text

    Das folgende Beispiel zeigt, wie eine Nur-Text-Verbindung zu Spanner Omni hergestellt wird:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.UsePlainText = true

  cluster := spanner.NewCluster(opts)
  // ...
}

    TLS

    Das folgende Beispiel zeigt, wie eine TLS-Verbindung zu Spanner Omni hergestellt wird:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"

  cluster := spanner.NewCluster(opts)
  // ...
}

    mTLS

    Das folgende Beispiel zeigt, wie eine mTLS-Verbindung zu Spanner Omni hergestellt wird:

    func main() {
  opts := &spanner.Options{
      // Required: Specify the Spanner database URI
      DatabaseUri: "DATABASE_ID",
  }
  // Optional: Configure Spanner Omni cluster settings as needed
  opts.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"
  opts.ClientCertificate = "PATH_TO_CLIENT_CERT"
  opts.ClientKey = "PATH_TO_CLIENT_KEY"

  cluster := spanner.NewCluster(opts)
  // ...
}

    Ersetzen Sie Folgendes:

    • DATABASE_ID: die ID Ihrer Spanner Omni-Datenbank, z. B. test-db.

    • ENDPOINT: Der Endpunkt Ihrer Spanner Omni-Instanz, z. B. localhost:15000.

    • PATH_TO_CA_CRT: Pfad zur CA-Zertifikatsdatei.

    • PATH_TO_CLIENT_CERT: der Pfad zu Ihrer Clientzertifikatsdatei.

    • PATH_TO_CLIENT_KEY: der Pfad zu Ihrer Clientschlüsseldatei.

Client als Sidecar-Proxy bereitstellen

Die Bereitstellung des Spanner Cassandra Go-Clients als Sidecar-Proxy ist eine effektive Option für Nicht-Go-Anwendungen und -Tools wie cqlsh, um mit Standard-Cassandra-Treibern eine Verbindung zu Spanner Omni herzustellen. Bei dieser Methode wird der Client als eigenständiger TCP-Proxy ausgeführt, der den Cassandra-Wire-Protokoll-Traffic abfängt und für die Kommunikation mit Spanner Omni in gRPC übersetzt.

Diese Konfiguration ist nützlich, wenn Sie externe Cassandra-Tools verwenden müssen oder direkte Änderungen am Code Ihrer Anwendung vermeiden möchten.

Sie können den Sidecar-Proxy auf folgende Arten ausführen:

Lokal mit dem Go-Befehl run ausführen

Die Ausführung des Sidecar-Proxys als lokaler Prozess aus dem Quellcode ist nützlich für Entwicklungs- und Testumgebungen, in denen Sie schnell Iterationen an Ihrer Anwendung und Proxykonfiguration vornehmen möchten.

  1. Klonen Sie das Repository:

    git clone https://github.com/googleapis/go-spanner-cassandra.git

  2. Wechseln Sie in das Repository-Verzeichnis:

    cd go-spanner-cassandra

  3. Führen Sie cassandra_launcher.go mit dem erforderlichen Flag -db und den folgenden Spanner Omni-spezifischen Flags aus:

    Nur-Text

    Führen Sie den folgenden Befehl aus, um die Kommunikation im Nur-Text-Modus zu verwenden:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -usePlainText

    TLS

    Führen Sie den folgenden Befehl aus, um eine TLS-Verbindung zu verwenden:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    Führen Sie den folgenden Befehl aus, um eine mTLS-Verbindung zu verwenden:

    go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

Mit einem vorgefertigten Docker-Image ausführen

Wir empfehlen, den Sidecar-Proxy als Containeranwendung mit einem vordefinierten Docker-Image für Produktionsumgebungen auszuführen, da dies eine konsistente und isolierte Laufzeitumgebung bietet.

  1. Laden Sie das Image aus dem offiziellen Registry-Repository herunter:

    docker pull gcr.io/cloud-spanner-adapter/cassandra-adapter

  2. Führen Sie das Image mit den erforderlichen Flags aus:

    Nur-Text

    Führen Sie den folgenden Befehl aus, um die Kommunikation im Nur-Text-Modus zu verwenden:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -usePlainText

    TLS

    Führen Sie den folgenden Befehl aus, um eine TLS-Verbindung zu verwenden:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    Führen Sie den folgenden Befehl aus, um eine mTLS-Verbindung zu verwenden:

    docker run -d -p 9042:9042 gcr.io/cloud-spanner-adapter/cassandra-adapter -db DATABASE_ID -endpoint ENDPOINT -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY