Utiliser le client Cassandra Go pour se connecter à Spanner Omni

Le client Go Cassandra pour Spanner connecte les applications écrites pour la base de données Apache Cassandra à Spanner. Le client fonctionne avec Spanner Omni de la même manière qu'avec Spanner. Étant donné que Spanner est compatible de manière native avec le protocole filaire Cassandra v4, ce client permet aux applications Go qui utilisent le pilote gocql, ou aux applications et outils non Go tels que cqlsh, de se connecter à une base de données Spanner.

Ce client fait office de proxy TCP local. Il intercepte les octets bruts du protocole Cassandra qu'un pilote ou un outil client envoie. Il encapsule ensuite ces octets et les métadonnées nécessaires dans des messages gRPC pour communiquer avec Spanner Omni. Le client traduit les réponses de Spanner Omni au format filaire Cassandra et les renvoie au pilote ou à l'outil d'origine.

Ce document explique comment intégrer le client à Spanner Omni à l'aide de l'une des méthodes suivantes :

Pour en savoir plus sur le fonctionnement d'Apache Cassandra avec Spanner, consultez Interface Cassandra.

Quand utiliser le client Go Spanner Cassandra

Ce client est utile dans les scénarios suivants :

  • Utiliser Spanner avec un minimum de refactoring Vous souhaitez utiliser Spanner comme backend pour votre application Go, mais vous préférez continuer à utiliser l'API gocql que vous connaissez pour accéder aux données.

  • Utiliser des outils Cassandra non Go Vous souhaitez vous connecter à Spanner à l'aide d'outils Cassandra standards tels que cqlsh ou d'applications écrites dans d'autres langages qui utilisent des pilotes Cassandra.

Utiliser le client comme dépendance dans le processus

Les applications Go se connectent à Spanner Omni en intégrant le client Go Spanner Cassandra en tant que dépendance dans le processus. Cette approche intègre la logique du proxy directement dans votre application, ce qui simplifie votre architecture de déploiement en supprimant le besoin d'un processus distinct. Cette configuration offre également des performances optimales en évitant un saut de réseau supplémentaire, ainsi qu'une sérialisation et une désérialisation supplémentaires des données.

Pour utiliser le client comme dépendance dans le processus, procédez comme suit :

  • Importez le package Spanner dans votre application Go :

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

  • Modifiez le code de création de votre cluster. Au lieu d'utiliser gocql.NewCluster, utilisez spanner.NewCluster et fournissez les options spécifiques à Spanner Omni suivantes :

    Communication en texte brut

    L'exemple suivant montre comment établir une connexion en texte brut à 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)
  // ...
}

    Connexion TLS

    L'exemple suivant montre comment établir une connexion TLS à 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)
  // ...
}

    Connexion mTLS

    L'exemple suivant montre comment établir une connexion mTLS à 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)
  // ...
}

Déployer le client en tant que proxy side-car

Le déploiement du client Go Spanner Cassandra en tant que proxy side-car est une option efficace pour que les applications et outils non Go, tels que cqlsh, se connectent à Spanner Omni à l'aide de pilotes Cassandra standards. Cette méthode exécute le client en tant que proxy TCP autonome qui intercepte le trafic du protocole filaire Cassandra et le traduit en gRPC pour communiquer avec Spanner Omni.

Cette configuration est utile lorsque vous devez utiliser des outils Cassandra externes ou lorsque vous devez éviter d'apporter des modifications directes au code de votre application.

Vous pouvez exécuter le proxy side-car de différentes manières :

Exécuter localement avec la commande Go run

L'exécution du proxy side-car en tant que processus local à partir du code source est utile pour les environnements de développement et de test dans lesquels vous souhaitez itérer rapidement sur la configuration de votre application et de votre proxy.

  1. Clonez le dépôt :

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

  2. Accédez au répertoire du dépôt :

    cd go-spanner-cassandra

  3. Exécutez cassandra_launcher.go avec l'option -db requise et les options spécifiques à Spanner Omni suivantes. Remplacez la valeur de -db par le nom de votre base de données Spanner Omni :

  • Pour la communication en texte brut, exécutez la commande suivante :
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • Pour une connexion TLS, exécutez la commande suivante :
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • Pour une connexion mTLS, exécutez la commande suivante :
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

Exécuter avec une image Docker préconfigurée

Nous vous recommandons d'exécuter le proxy side-car en tant qu'application conteneurisée à l'aide d'une image Docker préconfigurée pour les environnements de production, car il fournit un environnement d'exécution cohérent et isolé.

  1. Extrayez l'image du dépôt de registre officiel :

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

  2. Exécutez l'image avec les options requises :

    Communication en texte brut

    Pour la communication en texte brut, exécutez la commande suivante :

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

    Connexion TLS

    Pour une connexion TLS, exécutez la commande suivante :

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

    Connexion mTLS

    Pour une connexion mTLS, exécutez la commande suivante :

    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