Acerca de este codelab
1. Introducción
Spanner es un servicio de base de datos distribuido de forma global, escalable de forma horizontal y completamente administrado que es ideal para cargas de trabajo relacionales y no relacionales.
La interfaz de Cassandra de Spanner te permite aprovechar la infraestructura completamente administrada, escalable y de alta disponibilidad de Spanner con herramientas y sintaxis de Cassandra conocidas.
Qué aprenderás
- Cómo configurar una instancia y una base de datos de Spanner
- Cómo convertir tu esquema y modelo de datos de Cassandra
- Cómo implementar y configurar las operaciones de escritura doble para los datos entrantes
- Cómo exportar masivamente tus datos históricos de Cassandra a Spanner
- Cómo validar los datos para garantizar su integridad durante el proceso de migración
- Cómo dirigir tu aplicación a Spanner en lugar de Cassandra
Requisitos
- Un proyecto de Google Cloud conectado a una cuenta de facturación
- Accede a una máquina con la CLI de
gcloudinstalada y configurada, o usa Google Cloud Shell. - Un navegador, como Chrome o Firefox.
2. Configuración y requisitos
Crea un proyecto de GCP
Accede a Google Cloud Console y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.
- El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
- El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como
PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto. - Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.
Configuración de facturación
A continuación, deberás seguir la guía del usuario para administrar la facturación y habilitarla en la consola de Cloud. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de USD 300. Para evitar que se te facture más allá de este instructivo, puedes cerrar la instancia de Spanner al final del codelab. Para ello, sigue las instrucciones de “Paso 9: Limpieza”.
Inicie Cloud Shell
Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.
En Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:
El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:
Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.
Cuál es el próximo paso
A continuación, implementarás el clúster de Cassandra.
3. Implementa un clúster de Cassandra (origen)
En este codelab, configuraremos un clúster de Cassandra de un solo nodo en Compute Engine.
1. Crea una VM de GCE para Cassandra
Para crear una instancia, usa el comando gcloud compute instances create.
gcloud compute instances create cassandra-origin \ --machine-type=e2-medium \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --tags=cassandra-migration \ --boot-disk-size=20GB
2. Instala Cassandra
# Install Java (Cassandra dependency) sudo apt-get update sudo apt-get install -y openjdk-11-jre-headless # Add Cassandra repository echo "deb [https://debian.cassandra.apache.org](https://debian.cassandra.apache.org) 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list curl [https://downloads.apache.org/cassandra/KEYS](https://downloads.apache.org/cassandra/KEYS) | sudo apt-key add - # Install Cassandra sudo apt-get update sudo apt-get install -y cassandra
3. Crea un espacio de claves y una tabla
Usaremos un ejemplo de tabla de usuarios y crearemos un espacio de claves llamado "analytics".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
Dentro de cqlsh:
-- Create keyspace (adjust replication for production)
CREATE KEYSPACE analytics WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};
-- Use the keyspace
USE analytics;
-- Create the users table
CREATE TABLE users (
id int PRIMARY KEY,
active boolean,
username text,
);
-- Exit cqlsh
EXIT;
Deja la sesión de SSH abierta o anota la dirección IP de esta VM (nombre de host -I).
Cuál es el próximo paso
A continuación, configurarás una instancia y una base de datos de Cloud Spanner.
4. Crea una instancia y una base de datos de Spanner (destino)
En Spanner, una instancia es un clúster de recursos de procesamiento y almacenamiento que aloja una o más bases de datos de Spanner. Necesitarás al menos 1 instancia para alojar una base de datos de Spanner para este codelab.
Cómo verificar la versión del SDK de gcloud
Antes de crear una instancia, asegúrate de que el SDK de gcloud en Google Cloud Shell se haya actualizado a la versión requerida: SDK de gcloud 493.0.0. Para encontrar la versión del SDK de gcloud, sigue el siguiente comando.
$ gcloud version | grep Google
Este es un resultado de ejemplo:
Google Cloud SDK 489.0.0
Si la versión que usas es anterior a la versión requerida 493.0.0 (489.0.0 en el ejemplo anterior), debes actualizar el SDK de Google Cloud. Para ello, ejecuta el siguiente comando:
sudo apt-get update \
&& sudo apt-get --only-upgrade install google-cloud-cli-anthoscli google-cloud-cli-cloud-run-proxy kubectl google-cloud-cli-skaffold google-cloud-cli-cbt google-cloud-cli-docker-credential-gcr google-cloud-cli-spanner-migration-tool google-cloud-cli-cloud-build-local google-cloud-cli-pubsub-emulator google-cloud-cli-app-engine-python google-cloud-cli-kpt google-cloud-cli-bigtable-emulator google-cloud-cli-datastore-emulator google-cloud-cli-spanner-emulator google-cloud-cli-app-engine-go google-cloud-cli-app-engine-python-extras google-cloud-cli-config-connector google-cloud-cli-package-go-module google-cloud-cli-istioctl google-cloud-cli-anthos-auth google-cloud-cli-gke-gcloud-auth-plugin google-cloud-cli-app-engine-grpc google-cloud-cli-kubectl-oidc google-cloud-cli-terraform-tools google-cloud-cli-nomos google-cloud-cli-local-extract google-cloud-cli-firestore-emulator google-cloud-cli-harbourbridge google-cloud-cli-log-streaming google-cloud-cli-minikube google-cloud-cli-app-engine-java google-cloud-cli-enterprise-certificate-proxy google-cloud-cli
Habilita la API de Spanner
En Cloud Shell, asegúrate de que el ID de tu proyecto esté configurado. Usa el primer comando que aparece a continuación para encontrar el ID del proyecto configurado actualmente. Si el resultado no es el esperado, el segundo comando que se indica a continuación establece el correcto.
gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]
Configura la región predeterminada como us-central1. No dudes en cambiarla a una región diferente compatible con las configuraciones regionales de Spanner.
gcloud config set compute/region us-central1
Habilita la API de Spanner:
gcloud services enable spanner.googleapis.com
Crea la instancia de Spanner
En esta sección, crearás una instancia de prueba gratuita o una instancia aprovisionada. A lo largo de este codelab, el ID de instancia del adaptador de Cassandra de Spanner que se usa es cassandra-adapter-demo, establecido como variable SPANNER_INSTANCE_ID con la línea de comandos export. De manera opcional, puedes elegir tu propio nombre de ID de instancia.
Crea una instancia de Spanner de prueba gratuita
Una instancia de prueba gratuita de Spanner de 90 días está disponible para cualquier persona que tenga una Cuenta de Google y que haya habilitado la Facturación de Cloud en su proyecto. No se te cobrará a menos que elijas actualizar tu instancia de prueba gratuita a una instancia pagada. El adaptador de Cassandra de Spanner es compatible con la instancia de prueba gratuita. Si cumples con los requisitos, abre Cloud Shell y ejecuta este comando para crear una instancia de prueba gratuita:
export SPANNER_INSTANCE_ID=cassandra-adapter-demo
export SPANNER_REGION=regional-us-central1
gcloud spanner instances create $SPANNER_INSTANCE_ID \
--config=$SPANNER_REGION \
--instance-type=free-instance \
--description="Spanner Cassandra Adapter demo"
Resultado del comando:
$ gcloud spanner instances create $SPANNER_INSTANCE_ID \ --config=$SPANNER_REGION \ --instance-type=free-instance \ --description="Spanner Cassandra Adapter demo" Creating instance...done.
Crea la base de datos
Una vez que la instancia esté en ejecución, podrás crear la base de datos. En la base de datos, defines tu esquema. También puedes controlar quién tiene acceso a la base de datos, configurar la encriptación personalizada, configurar el optimizador y establecer el período de retención.
La base de datos se creará en la instancia con el ID SPANNER_INSTANCE_ID.
Para crear una base de datos, usa la herramienta de línea de comandos de gcloud:
export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
--instance=$SPANNER_INSTANCE_ID
Resultado del comando:
$ gcloud spanner databases create $SPANNER_DATABASE \ --instance=$SPANNER_INSTANCE_ID Creating database...done.
5. Migra el esquema y el modelo de datos de Cassandra a Spanner
La fase inicial y crucial de la transición de datos de una base de datos de Cassandra a Spanner implica transformar el esquema de Cassandra existente para alinearlo con los requisitos estructurales y de tipos de datos de Spanner.
Para optimizar este complejo proceso de migración de esquemas, Spanner proporciona una valiosa herramienta de código abierto conocida como herramienta de esquema de Cassandra de Spanner.
Herramienta de esquema de Cassandra de Spanner
La herramienta de esquema de Cassandra de Spanner es una herramienta de código abierto independiente para la evaluación de Spanner y la migración de esquemas. Su función principal es construir automáticamente un esquema de Spanner basado en las definiciones que se encuentran en un esquema de Cassandra existente. A través del análisis de las estructuras de tablas, los tipos de datos y las configuraciones de claves primarias de Cassandra, la herramienta genera definiciones de tablas de Spanner equivalentes, lo que reduce significativamente el esfuerzo manual que suele implicar la traducción de esquemas.
Exporta el esquema de Cassandra
Antes de usar la herramienta de esquema de Cassandra de Spanner, el primer paso concreto es extraer el esquema de tu clúster de Cassandra actual. Para ello, conéctate a tu clúster de Cassandra existente a través de cqlsh y exporta el esquema de Cassandra:
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
En este comando, [IP] se debe reemplazar por la dirección IP o el nombre de host de uno de los nodos de tu clúster de Cassandra. La parte -e DESC SCHEMA del comando le indica a cqlsh que describa todo el esquema del clúster de Cassandra. El resultado de este comando, que contiene las instrucciones CREATE KEYSPACE y CREATE TABLE, se redirecciona a un archivo llamado orig_schema.cql.
El contenido de este archivo orig_schema.cql representará, en esencia, un modelo textual de tu esquema de Cassandra. El contenido del archivo orig_schema.cql debería verse de la siguiente manera:
CREATE KEYSPACE analytics WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'} AND durable_writes = true;
CREATE TABLE analytics.users (
id int PRIMARY KEY,
active boolean,
username text
) WITH additional_write_policy = '99p'
AND allow_auto_snapshot = true
AND bloom_filter_fp_chance = 0.01
AND caching = {'keys': 'ALL', 'rows_per_partition': 'NONE'}
AND cdc = false
AND comment = ''
AND compaction = {'class': 'org.apache.cassandra.db.compaction.SizeTieredCompactionStrategy', 'max_threshold': '32', 'min_threshold': '4'}
AND compression = {'chunk_length_in_kb': '16', 'class': 'org.apache.cassandra.io.compress.LZ4Compressor'}
AND memtable = 'default'
AND crc_check_chance = 1.0
AND default_time_to_live = 0
AND extensions = {}
AND gc_grace_seconds = 864000
AND incremental_backups = true
AND max_index_interval = 2048
AND memtable_flush_period_in_ms = 0
AND min_index_interval = 128
AND read_repair = 'BLOCKING'
AND speculative_retry = '99p';
Clona el repositorio
Para usar la herramienta de esquema de Cassandra de Spanner, el siguiente paso consiste en obtener el código fuente de la herramienta. Para ello, se clona el repositorio alojado en GitHub. Para clonar la herramienta de esquema de Cassandra de Spanner desde GitHub, escribe el siguiente comando en Cloud Shell:
git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git
Luego, cambia al directorio “spanner-cassandra-schema-tool” en el que ejecutarás el comando.
cd spanner-cassandra-schema-tool
Instala las dependencias
La herramienta de esquema de Cassandra de Spanner está escrita en el lenguaje de programación Go. Para garantizar que la herramienta funcione correctamente, se basa en ciertos módulos externos de Go (bibliotecas). Estas dependencias deben descargarse y administrarse antes de que puedas ejecutar la herramienta. En el directorio spanner-cassandra-schema-tool, ejecuta el siguiente comando:
go mod download
Configura las credenciales de Google Cloud
Esta herramienta usa las credenciales predeterminadas de la aplicación (ADC) como fuente de credenciales para conectarse a las bases de datos de Spanner. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso del archivo de claves de tu cuenta de servicio.
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
Reemplaza /path/to/your/service-account-file.json por la ruta de acceso real al archivo de claves de la cuenta de servicio que descargaste. Configurar esta variable de entorno garantiza que la herramienta de esquema de Cassandra de Spanner pueda autenticarse de forma segura con tu proyecto de Google Cloud y tu instancia de Spanner.
Uso
Una vez que se instalen las dependencias y se configuren las credenciales de Google Cloud, estará todo listo para ejecutar la herramienta de esquema de Cassandra de Spanner y generar el esquema de Spanner a partir del archivo de esquema de Cassandra exportado. Navega al directorio spanner-cassandra-schema-tool en la terminal o Cloud Shell y ejecuta el siguiente comando go run:
go run schema_converter.go \
--project $PROJECT_ID \
--instance $SPANNER_INSTANCE_ID \
--database $SPANNER_DATABASE \
--cql orig_schema.cql \
--dry-run
Ejecutar con la opción --dry-run solo genera el esquema. Revisa y define mejor la asignación de tipos de datos y las columnas de clave primaria que genera la herramienta. Asegúrate de que los tipos de datos de Spanner representen con precisión el rango, la precisión y la semántica de los tipos de bases de datos de Cassandra correspondientes.
Esta herramienta asigna tipos de Cassandra a tipos de Spanner, como se documenta en Tipos de datos de Cassandra admitidos.
El resultado del comando se verá de la siguiente manera:
.....
[Converted Spanner statement]
CREATE TABLE users (
id INT64 NOT NULL OPTIONS (cassandra_type = 'int'),
active BOOL OPTIONS (cassandra_type = 'boolean'),
username STRING(MAX) OPTIONS (cassandra_type = 'text'),
) PRIMARY KEY (id)
----------------------------------------------
Writing converted Spanner schema to: schema.txt
Dry run enabled. Skipping schema execution.
Schema conversion completed!
En caso de que también quieras que el esquema de aplicación se aplique automáticamente a Spanner, debes ejecutar la CLI sin la opción --dry-run.
Verifica en la consola de Google Cloud que las tablas y la tabla de metadatos existan en la base de datos de Cloud Spanner.
8. Valida los datos
[TODO]
9. Dirige tu aplicación a Spanner (cambio)
Después de validar minuciosamente la precisión y la integridad de tus datos después de la fase de migración, el paso fundamental es migrar el enfoque operativo de tu aplicación de tu sistema heredado de Cassandra a la base de datos de Google Cloud Spanner recién propagada. Por lo general, este período de transición fundamental se conoce como "cambio".
La fase de migración marca el momento en que el tráfico de la aplicación en vivo se redirecciona desde el clúster de Cassandra original y se conecta directamente a la infraestructura de Spanner sólida y escalable. Esta transición demuestra la facilidad con la que las aplicaciones pueden aprovechar la potencia de Spanner, especialmente cuando se usa la interfaz de Spanner Cassandra.
Con la interfaz de Cassandra de Spanner, el proceso de cambio se optimiza. En primer lugar, implica configurar tus aplicaciones cliente para que usen el cliente nativo de Cassandra de Spanner para toda la interacción de datos. En lugar de comunicarse con tu base de datos de Cassandra (origen), tus aplicaciones comenzarán a leer y escribir datos directamente en Spanner (destino) sin problemas. Por lo general, este cambio fundamental en la conectividad se logra mediante el uso de SpannerCqlSessionBuilder, un componente clave de la biblioteca cliente de Spanner Cassandra que facilita el establecimiento de conexiones con tu instancia de Spanner. Esto redirecciona de forma eficaz todo el flujo de tráfico de datos de tu aplicación a Spanner.
En el caso de las aplicaciones de Java que ya usan la biblioteca cassandra-java-driver, la integración del cliente de Java de Cassandra de Spanner solo requiere cambios menores en la inicialización de CqlSession.
Cómo obtener la dependencia google-cloud-spanner-cassandra
Para comenzar a usar el cliente de Cassandra de Spanner, primero debes incorporar su dependencia en tu proyecto. Los artefactos de google-cloud-spanner-cassandra se publican en Maven Central, con el ID de grupo com.google.cloud. Agrega la siguiente dependencia nueva en la sección <dependencies> existente de tu proyecto de Java. Este es un ejemplo simplificado de cómo incluirías la dependencia google-cloud-spanner-cassandra:
<!-- native Spanner Cassandra Client -->
<dependencies>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner-cassandra</artifactId>
<version>0.2.0</version>
</dependency>
</dependencies>
Cambia la configuración de la conexión para conectarte a Spanner
Una vez que hayas agregado la dependencia necesaria, el siguiente paso es cambiar la configuración de la conexión para conectarte a la base de datos de Spanner.
Una aplicación típica que interactúa con un clúster de Cassandra suele emplear un código similar al siguiente para establecer una conexión:
CqlSession session = CqlSession.builder()
.addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
.withLocalDatacenter("datacenter1")
.withAuthCredentials("username", "password")
.build();
Para redireccionar esta conexión a Spanner, debes modificar tu lógica de creación de CqlSession. En lugar de usar directamente la CqlSessionBuilder estándar de cassandra-java-driver, usarás la SpannerCqlSession.builder() que proporciona el cliente de Cassandra de Spanner. A continuación, se muestra un ejemplo ilustrativo de cómo modificar tu código de conexión:
String databaseUri = "projects/<your-gcp-project>/instances/<your-spanner-instance>/databases/<your-spanner-database>";
CqlSession session = SpannerCqlSession.builder()
.setDatabaseUri(databaseUri)
.addContactPoint(new InetSocketAddress("localhost", 9042))
.withLocalDatacenter("datacenter1")
.build();
Si creas una instancia de CqlSession con SpannerCqlSession.builder() y proporcionas el databaseUri correcto, tu aplicación ahora establecerá una conexión a través del cliente de Cassandra de Spanner con tu base de datos de Spanner de destino. Este cambio fundamental garantiza que todas las operaciones de lectura y escritura posteriores que realice tu aplicación se dirijan a Spanner y se entreguen a través de él, lo que completará de manera eficaz la migración inicial. En este punto, tu aplicación debería seguir funcionando como se espera, ahora con la escalabilidad y la confiabilidad de Spanner.
Bajo la superficie: Cómo funciona el cliente de Cassandra de Spanner
El cliente de Cassandra de Spanner actúa como un proxy TCP local que intercepta los bytes de protocolo de Cassandra sin procesar que envía un controlador o una herramienta de cliente. Luego, une estos bytes junto con los metadatos necesarios en mensajes gRPC para la comunicación con Spanner. Las respuestas de Spanner se vuelven a traducir al formato de cable de Cassandra y se envían al controlador o la herramienta de origen.
Una vez que tengas la seguridad de que Spanner entrega todo el tráfico correctamente, podrás hacer lo siguiente:
- Detén las operaciones de escritura dual.
- Inhabilita el clúster de Cassandra original.
10. Limpieza (opcional)
Para limpiar, ve a la sección de Spanner de la consola de Cloud y borra la instancia de cassandra-adapter-demo que creamos en el codelab.
Borra la base de datos de Cassandra (si está instalada de forma local o persistente).
Si instalaste Cassandra fuera de una VM de Compute Engine creada aquí, sigue los pasos adecuados para quitar los datos o desinstalar Cassandra.
11. ¡Felicitaciones!
Próximos pasos
- Obtén más información sobre Cloud Spanner.
- Obtén más información sobre la interfaz de Cassandra.