Usa el cliente de Go de Cassandra para conectarte a Spanner Omni

El cliente de Cassandra Go para Spanner conecta aplicaciones escritas para la base de datos de Apache Cassandra con Spanner. El cliente funciona con Spanner Omni de la misma manera que con Spanner. Debido a que Spanner admite de forma nativa el protocolo de transmisión de Cassandra v4, este cliente permite que las aplicaciones de Go que usan el controlador gocql o las aplicaciones y herramientas que no son de Go, como cqlsh, se conecten a una base de datos de Spanner.

Este cliente actúa como un proxy TCP local. Intercepta los bytes sin procesar del protocolo de Cassandra que envía un controlador o una herramienta cliente. Luego, une estos bytes y los metadatos necesarios en mensajes gRPC para comunicarse con Spanner Omni. El cliente traduce las respuestas de Spanner Omni al formato de transmisión de Cassandra y las envía de vuelta al controlador o la herramienta de origen.

En este documento, se muestra cómo integrar el cliente con Spanner Omni mediante uno de los siguientes métodos:

  • Dependencia en el proceso: Usa este método para las aplicaciones de Go que ya usan el controlador gocql. Este enfoque incorpora el cliente dentro del proceso de tu aplicación para realizar modificaciones mínimas en el código.

  • Proxy sidecar: Usa este método para aplicaciones que no son de Go o cuando usas herramientas externas de Cassandra, como cqlsh. Este enfoque ejecuta el cliente como un proceso independiente.

Para obtener más información sobre cómo funciona Apache Cassandra con Spanner, consulta Interfaz de Cassandra.

Cuándo usar el cliente de Cassandra Go de Spanner

Este cliente es útil en las siguientes situaciones:

  • Usa Spanner con una refactorización mínima. Quieres usar Spanner como backend para tu aplicación de Go, pero prefieres seguir usando la API de gocql familiar para el acceso a los datos.

  • Usa herramientas de Cassandra que no son de Go. Quieres conectarte a Spanner con herramientas estándar de Cassandra, como cqlsh, o aplicaciones escritas en otros lenguajes que usan controladores de Cassandra.

Usa el cliente como una dependencia en el proceso

Las aplicaciones de Go se conectan a Spanner Omni integrando el cliente de Cassandra Go de Spanner como una dependencia en el proceso. Este enfoque incorpora la lógica del proxy directamente en tu aplicación, lo que simplifica la arquitectura de implementación, ya que elimina la necesidad de un proceso independiente. Esta configuración también proporciona un rendimiento óptimo, ya que evita un salto de red adicional y una serialización y deserialización adicionales de los datos.

Para usar el cliente como una dependencia en el proceso, haz lo siguiente:

  • Importa el paquete de Spanner en tu aplicación de Go:

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

  • Modifica el código de creación del clúster. En lugar de usar gocql.NewCluster, usa spanner.NewCluster y proporciona las siguientes opciones específicas de Spanner Omni:

    Comunicación de texto simple

    En el siguiente ejemplo, se muestra cómo establecer una conexión de texto simple 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)
  // ...
}

    Conexión TLS

    En el siguiente ejemplo, se muestra cómo establecer una conexión 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)
  // ...
}

    Conexión mTLS

    En el siguiente ejemplo, se muestra cómo establecer una conexión 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)
  // ...
}

Implementa el cliente como un proxy de sidecar

Implementar el cliente de Cassandra Go de Spanner como un proxy de sidecar es una opción eficaz para que las aplicaciones y herramientas que no son de Go, como cqlsh, se conecten a Spanner Omni con controladores estándar de Cassandra. Este método ejecuta el cliente como un proxy TCP independiente que intercepta el tráfico del protocolo de transmisión de Cassandra y lo traduce a gRPC para la comunicación con Spanner Omni.

Esta configuración es útil cuando necesitas usar herramientas externas de Cassandra o cuando necesitas evitar realizar modificaciones directas en el código de tu aplicación.

Puedes ejecutar el proxy de sidecar de las siguientes maneras:

Ejecuta de forma local con el comando run de Go

Ejecutar el proxy de sidecar como un proceso local desde el código fuente es útil para los entornos de desarrollo y pruebas en los que deseas iterar rápidamente en la configuración de tu aplicación y proxy.

  1. Clona el repositorio:

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

  2. Cambia al directorio del repositorio:

    cd go-spanner-cassandra

  3. Ejecuta cassandra_launcher.go con la marca -db obligatoria y las siguientes marcas específicas de Spanner Omni. Reemplaza el valor de -db por el nombre de la base de datos de Spanner Omni:

  • Para la comunicación de texto simple, ejecuta lo siguiente:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -usePlainText
  • Para una conexión TLS, ejecuta lo siguiente:
go run cassandra_launcher.go -db DATABASE_ID -endpoint ENDPOINT -experimentalHost -caCertificate PATH_TO_CA_CRT
  • Para una conexión mTLS, ejecuta lo siguiente:
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

Ejecuta con una imagen de Docker compilada previamente

Recomendamos ejecutar el proxy de sidecar como una aplicación alojada en contenedores con una imagen de Docker compilada previamente para los entornos de producción, ya que proporciona un entorno de ejecución coherente y aislado.

  1. Extrae la imagen del repositorio oficial del registro:

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

  2. Ejecuta la imagen con las marcas obligatorias:

    Comunicación de texto simple

    Para la comunicación de texto simple, ejecuta el siguiente comando:

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

    Conexión TLS

    Para una conexión TLS, ejecuta el siguiente 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

    Conexión mTLS

    Para una conexión mTLS, ejecuta el siguiente 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