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 en mode natif avec le protocole de communication 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 :

  • Dépendance dans le processus : utilisez cette méthode pour les applications Go qui utilisent déjà le pilote gocql. Cette approche intègre le client dans le processus de votre application pour un minimum de modifications du code.

  • Proxy side-car : utilisez cette méthode pour les applications non-Go ou lorsque vous utilisez des outils Cassandra externes, tels que cqlsh. Cette approche exécute le client en tant que processus autonome.

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 :

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

  • Utilisez des outils Cassandra autres que 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 Spanner Cassandra Go en tant que dépendance dans le processus. Cette approche intègre la logique de proxy directement dans votre application, ce qui simplifie votre architecture de déploiement en supprimant la nécessité 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 intégrée, 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 :

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

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

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

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

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

    Remplacez les éléments suivants :

    • DATABASE_ID : ID de votre base de données Spanner Omni (par exemple, test-db).

    • ENDPOINT : point de terminaison de votre instance Spanner Omni, par exemple localhost:15000.

    • PATH_TO_CA_CRT : chemin d'accès à votre fichier de certificat CA.

    • PATH_TO_CLIENT_CERT : chemin d'accès à votre fichier de certificat client.

    • PATH_TO_CLIENT_KEY : chemin d'accès à votre fichier de clé client.

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 les applications et outils non Go, tels que cqlsh, afin de se connecter à 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 de communication Cassandra et le traduit en gRPC pour la communication avec Spanner Omni.

Cette configuration est utile lorsque vous devez utiliser des outils Cassandra externes ou lorsque vous devez éviter de modifier directement le code de votre application.

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

Exécuter en local 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 Spanner Omni spécifiques suivantes :

    Texte brut

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

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

    TLS

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

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

    mTLS

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

    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

Exécuter avec une image Docker prédéfinie

Nous vous recommandons d'exécuter le proxy side-car en tant qu'application conteneurisée à l'aide d'une image Docker prédéfinie 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 indicateurs requis :

    Texte brut

    Pour exécuter 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 -instanceType OMNI -usePlainText

    TLS

    Pour exécuter 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 -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

    Pour exécuter avec 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 -instanceType OMNI -caCertificate PATH_TO_CA_CRT -clientCertificate PATH_TO_CLIENT_CERT -clientKey PATH_TO_CLIENT_KEY