Utilizzare il client Go di Cassandra per connettersi a Spanner Omni

Il client Cassandra Go per Spanner connette le applicazioni scritte per il database Apache Cassandra a Spanner. Il client funziona con Spanner Omni nello stesso modo in cui funziona con Spanner. Poiché Spanner supporta in modo nativo il protocollo di trasferimento 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 che un driver o uno strumento client invia. Quindi, esegue il wrapping di questi byte e dei metadati necessari nei messaggi gRPC per comunicare con Spanner Omni. Il client traduce le risposte da Spanner Omni nel formato di trasferimento 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:

  • Dipendenza in-process: utilizza questo metodo per le applicazioni Go che utilizzano già il driver gocql. Questo approccio incorpora il client nel processo di applicazione per modifiche minime al codice.

  • Proxy sidecar: utilizza questo metodo per applicazioni non Go o quando utilizzi strumenti Cassandra esterni, come cqlsh. Questo approccio esegue il client come processo autonomo.

Per saperne di più su come Apache Cassandra funziona con Spanner, consulta Interfaccia Cassandra.

Quando utilizzare il client Go di Spanner Cassandra

Questo client è utile nei seguenti scenari:

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

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

Utilizzare il client come dipendenza in-process

Le applicazioni Go si connettono a Spanner Omni integrando il client Go Spanner Cassandra come dipendenza in-processo. Questo approccio incorpora la logica del proxy direttamente all'interno dell'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 la 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 per Spanner Omni:

    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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.UsePlainText = true

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

    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.SpannerEndpoint = "ENDPOINT"
  opts.InstanceType = spanner.Omni
  opts.CaCertificate = "PATH_TO_CA_CRT"

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

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

    Sostituisci quanto segue:

    • DATABASE_ID: l'ID del tuo database Spanner Omni, ad esempio test-db.

    • ENDPOINT: l'endpoint dell'istanza Spanner Omni, ad esempio localhost:15000.

    • PATH_TO_CA_CRT: il percorso del file del certificato CA.

    • PATH_TO_CLIENT_CERT: il percorso del file del certificato client.

    • PATH_TO_CLIENT_KEY: il percorso del file della chiave client.

Esegui il deployment del client come proxy sidecar

Il deployment del client Go Spanner Cassandra come proxy sidecar è un'opzione efficace per applicazioni e 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 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:

Esegui in locale con il comando Go run

L'esecuzione del proxy sidecar come processo locale dal codice sorgente è utile per ambienti di sviluppo e test in cui vuoi iterare rapidamente la 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:

    Testo normale

    Per l'esecuzione con comunicazione in testo normale, esegui questo comando:

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

    TLS

    Per l'esecuzione con una connessione TLS, esegui questo comando:

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

    mTLS

    Per eseguire con una connessione mTLS, esegui questo comando:

    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

Esegui con un'immagine Docker predefinita

Ti consigliamo di eseguire il proxy sidecar come applicazione containerizzata utilizzando un'immagine Docker predefinita 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 richiesti:

    Testo normale

    Per l'esecuzione con comunicazione in testo normale, esegui questo comando:

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

    TLS

    Per l'esecuzione con una connessione TLS, esegui questo comando:

    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

    Per eseguire con una connessione mTLS, esegui questo comando:

    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