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 Clienttool gesendet werden. Anschließend werden diese Byte 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 Ihren 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 ist der Spanner Cassandra Go-Client zu verwenden?

Dieser Client ist in 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 sind 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 für die Clustererstellung. Verwenden Sie anstelle von gocql.NewCluster spanner.NewCluster und geben Sie die folgenden Spanner Omni-spezifischen Optionen an:

    Nur-Text-Kommunikation

    Das folgende Beispiel zeigt, wie Sie eine Nur-Text-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.UsePlainText = true

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

    TLS-Verbindung

    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.ExperimentalHost = true
  opts.CaCertificate = "PATH_TO_CA_CRT"

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

    mTLS-Verbindung

    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.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 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 Anwendungs- 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. Ersetzen Sie den Wert von -db durch den Namen Ihrer Spanner Omni-Datenbank:

  • Führen Sie für die Nur-Text-Kommunikation 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 er 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-Kommunikation

    Führen Sie für die Kommunikation im Nur-Text-Format 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