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 eine Verbindung zu einer Spanner-Datenbank herstellen.

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

In diesem Dokument wird beschrieben, wie Sie den Client mit einer der folgenden Methoden in Spanner Omni einbinden:

Weitere Informationen zur Verwendung 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 weiterhin die vertraute gocql-API für den Datenzugriff nutzen.

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

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, was die Bereitstellungsarchitektur vereinfacht, da kein separater Prozess erforderlich ist. Diese Konfiguration bietet auch eine optimale Leistung, da ein zusätzlicher Netzwerkhop 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 zur Clustererstellung. Verwenden Sie anstelle von gocql.NewCluster die Funktion spanner.NewCluster und geben Sie die folgenden spezifischen Optionen für Spanner Omni an:

    Kommunikation im Klartext

    Das folgende Beispiel zeigt, wie Sie eine Klartextverbindung zu Spanner Omni herstellen:

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

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

    TLS-Verbindung

    Das folgende Beispiel zeigt, wie Sie eine TLS-Verbindung zu Spanner Omni herstellen:

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

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

    mTLS-Verbindung

    Das folgende Beispiel zeigt, wie Sie eine mTLS-Verbindung zu Spanner Omni herstellen:

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

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

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 Traffic des Cassandra-Wire-Protokolls abfängt und ihn für die Kommunikation mit Spanner Omni in gRPC übersetzt.

Diese Konfiguration ist nützlich, wenn Sie externe Cassandra-Tools verwenden 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 Proxy-Konfiguration 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 spezifischen Flags für Spanner Omni aus. Ersetzen Sie den Wert von -db durch den Namen Ihrer Spanner Omni-Datenbank:

  • Führen Sie für die Kommunikation im Klartext Folgendes aus:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • Führen Sie für eine TLS-Verbindung Folgendes aus:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • Führen Sie für eine mTLS-Verbindung Folgendes aus:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY

Mit einem vordefinierten Docker-Image ausführen

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

  1. Rufen Sie das Image aus dem offiziellen Registry-Repository ab:

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

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

    Kommunikation im Klartext

    Führen Sie für die Kommunikation im Klartext den folgenden Befehl aus:

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

    TLS-Verbindung

    Führen Sie für eine TLS-Verbindung den folgenden Befehl aus:

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

    mTLS-Verbindung

    Führen Sie für eine mTLS-Verbindung den folgenden Befehl aus:

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