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

El cliente de Cassandra Go para Spanner conecta las aplicaciones escritas para la base de datos de Apache Cassandra con Spanner. El cliente trabaja con Spanner Omni de la misma manera en que lo hace con Spanner. Dado que Spanner admite de forma nativa el protocolo de conexió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, encapsula estos bytes y los metadatos necesarios en mensajes de gRPC para comunicarse con Spanner Omni. El cliente traduce las respuestas de Spanner Omni al formato de transferencia 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 con uno de los siguientes métodos:

  • Dependencia en el proceso: Usa este método para las aplicaciones en Go que ya usan el controlador gocql. Este enfoque incorpora el cliente en el proceso de solicitud 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 Apache Cassandra funciona con Spanner, consulta la interfaz de Cassandra.

Cuándo usar el cliente de Go de Spanner Cassandra

Este cliente es útil en las siguientes situaciones:

  • Usar Spanner con una refactorización mínima Quieres usar Spanner como backend para tu aplicación en Go, pero prefieres seguir usando la API de gocql que ya conoces para acceder a los datos.

  • Usa herramientas de Cassandra que no sean de Go. Quieres conectarte a Spanner con herramientas estándar de Cassandra, como cqlsh, o con 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 Spanner Cassandra Go 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:

    Texto sin formato

    En el siguiente ejemplo, se muestra cómo establecer una conexión de texto sin formato con 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

    En el siguiente ejemplo, se muestra cómo establecer una conexión TLS con 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

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

    Reemplaza lo siguiente:

    • DATABASE_ID: Es el ID de tu base de datos de Spanner Omni, por ejemplo, test-db.

    • ENDPOINT: Es el extremo de tu instancia de Spanner Omni, por ejemplo, localhost:15000.

    • PATH_TO_CA_CRT: Es la ruta de acceso a tu archivo de certificado de la AC.

    • PATH_TO_CLIENT_CERT: Es la ruta de acceso al archivo del certificado del cliente.

    • PATH_TO_CLIENT_KEY: Es la ruta de acceso al archivo de claves del cliente.

Implementa el cliente como un proxy de sidecar

Implementar el cliente de Go de Spanner Cassandra como un proxy de sidecar es una opción eficaz para las aplicaciones y herramientas que no son de Go, como cqlsh, para conectarse a Spanner Omni con controladores de Cassandra estándar. Este método ejecuta el cliente como un proxy TCP independiente que intercepta el tráfico del protocolo de conexió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 prueba 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:

    Texto sin formato

    Para ejecutar con comunicación de texto sin formato, ejecuta el siguiente comando:

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

    TLS

    Para ejecutar con una conexión TLS, ejecuta el siguiente comando:

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

    mTLS

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

Ejecuta con una imagen de Docker precompilada

Recomendamos ejecutar el proxy de sidecar como una aplicación alojada en contenedores con una imagen de Docker compilada previamente para 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 requeridas:

    Texto sin formato

    Para ejecutar con comunicación de texto sin formato, ejecuta el siguiente comando:

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

    TLS

    Para ejecutar con 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 -instanceType OMNI -caCertificate PATH_TO_CA_CRT

    mTLS

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