Utilizzare il client Go di Cassandra per connettersi a Spanner Omni

Il client Go di Cassandra per Spanner connette le applicazioni scritte per il database Apache Cassandra con Spanner. Il client funziona con Spanner Omni nello stesso modo in cui funziona con Spanner. Poiché Spanner supporta in modo nativo il protocollo di rete Cassandra v4, questo client consente alle applicazioni Go che utilizzano il driver gocql o alle applicazioni e agli strumenti non Go, come cqlsh, di connettersi a un database Spanner.

Questo client funge da proxy TCP locale. Intercetta i byte del protocollo Cassandra non elaborati inviati da un driver o da uno strumento client. Quindi, racchiude questi byte e i metadati necessari nei messaggi gRPC per comunicare con Spanner Omni. Il client traduce le risposte di Spanner Omni nel formato di rete Cassandra e le invia al driver o allo strumento di origine.

Questo documento mostra come integrare il client con Spanner Omni utilizzando uno dei seguenti metodi:

Per ulteriori informazioni su come Apache Cassandra funziona con Spanner, consulta Interfaccia Cassandra.

Quando utilizzare il client Go di Cassandra per Spanner

Questo client è utile nei seguenti scenari:

  • Utilizzare Spanner con un refactoring minimo. Vuoi utilizzare Spanner come backend per la tua applicazione Go, ma preferisci continuare a utilizzare l'API gocql che conosci per l'accesso ai dati.

  • Utilizzare strumenti Cassandra non Go. Vuoi connetterti a Spanner utilizzando strumenti Cassandra standard come cqlsh o applicazioni scritte in altre lingue che utilizzano i driver Cassandra.

Utilizzare il client come dipendenza in-process

Le applicazioni Go si connettono a Spanner Omni integrando il client Go di Cassandra per Spanner come dipendenza in-process. Questo approccio incorpora la logica del proxy direttamente nell'applicazione, il che semplifica l'architettura di deployment eliminando la necessità di un processo separato. Questa configurazione offre anche prestazioni ottimali evitando un hop di rete aggiuntivo e una serializzazione e deserializzazione aggiuntive dei dati.

Per utilizzare il client come dipendenza in-process:

  • Importa il pacchetto Spanner nella tua applicazione Go:

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

  • Modifica il codice di creazione del cluster. Anziché utilizzare gocql.NewCluster, utilizza spanner.NewCluster e fornisci le seguenti opzioni specifiche di Spanner Omni:

    Comunicazione in testo normale

    L'esempio seguente mostra come stabilire una connessione in testo normale a Spanner Omni:

    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)
  // ...
}

    Connessione TLS

    L'esempio seguente mostra come stabilire una connessione TLS a Spanner Omni:

    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)
  // ...
}

    Connessione mTLS

    L'esempio seguente mostra come stabilire una connessione mTLS a Spanner Omni:

    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)
  // ...
}

Eseguire il deployment del client come proxy sidecar

Il deployment del client Go di Cassandra per Spanner come proxy sidecar è un'opzione efficace per le applicazioni e gli strumenti non Go, come cqlsh, per connettersi a Spanner Omni utilizzando i driver Cassandra standard. Questo metodo esegue il client come proxy TCP autonomo che intercetta il traffico del protocollo di rete Cassandra e lo traduce in gRPC per la comunicazione con Spanner Omni.

Questa configurazione è utile quando devi utilizzare strumenti Cassandra esterni o quando devi evitare di apportare modifiche dirette al codice dell'applicazione.

Puoi eseguire il proxy sidecar nei seguenti modi:

Eseguire localmente con il comando run di Go

L'esecuzione del proxy sidecar come processo locale dal codice sorgente è utile per gli ambienti di sviluppo e test in cui vuoi eseguire rapidamente l'iterazione della configurazione dell'applicazione e del proxy.

  1. Clona il repository:

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

  2. Cambia la directory del repository:

    cd go-spanner-cassandra

  3. Esegui cassandra_launcher.go con il flag -db obbligatorio e i seguenti flag specifici di Spanner Omni. Sostituisci il valore di -db con il nome del database Spanner Omni:

  • Per la comunicazione in testo normale, esegui quanto segue:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • Per una connessione TLS, esegui quanto segue:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • Per una connessione mTLS, esegui quanto segue:
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

Eseguire con un'immagine Docker precompilata

Ti consigliamo di eseguire il proxy sidecar come applicazione containerizzata utilizzando un'immagine Docker precompilata per gli ambienti di produzione, in quanto fornisce un ambiente di runtime coerente e isolato.

  1. Esegui il pull dell'immagine dal repository del registro ufficiale:

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

  2. Esegui l'immagine con i flag obbligatori:

    Comunicazione in testo normale

    Per la comunicazione in testo normale, esegui il seguente comando:

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

    Connessione TLS

    Per una connessione TLS, esegui il seguente comando:

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

    Connessione mTLS

    Per una connessione mTLS, esegui il seguente comando:

    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