Acerca de este codelab
1. Introducción
Bigtable es un servicio de base de datos NoSQL completamente administrado y de alto rendimiento diseñado para cargas de trabajo analíticas y operativas de gran tamaño. Migrar desde bases de datos existentes, como Apache Cassandra, a Bigtable suele requerir una planificación cuidadosa para minimizar el tiempo de inactividad y el impacto en las aplicaciones.
En este codelab, se muestra una estrategia de migración de Cassandra a Bigtable con una combinación de herramientas de proxy:
- Proxy de Cassandra-Bigtable: Permite que los clientes y las herramientas de Cassandra (como
cqlsho los controladores) interactúen con Bigtable mediante el protocolo del lenguaje de consulta de Cassandra (CQL) mediante la traducción de consultas. - Proxy de migración sin tiempo de inactividad (ZDM) de Datastax: Es un proxy de código abierto que se encuentra entre tu aplicación y tus servicios de base de datos (Cassandra de origen y Bigtable de destino a través del proxy de Cassandra-Bigtable). Organiza las operaciones de escritura doble y administra el enrutamiento del tráfico, lo que permite la migración con cambios mínimos en la aplicación y tiempo de inactividad.
- Cassandra Data Migrator (CDM): Es una herramienta de código abierto que se usa para migrar datos históricos de forma masiva desde el clúster de Cassandra de origen a la instancia de Bigtable de destino.
Qué aprenderás
- Cómo configurar un clúster básico de Cassandra en Compute Engine
- Cómo crear una instancia de Bigtable
- Cómo implementar y configurar el proxy de Cassandra-Bigtable para asignar un esquema de Cassandra a Bigtable
- Cómo implementar y configurar el proxy de ZDM de Datastax para las operaciones de escritura doble
- Cómo usar la herramienta Cassandra Data Migrator para migrar de forma masiva los datos existentes
- Flujo de trabajo general para una migración de Cassandra a Bigtable basada en proxy
Requisitos
- Un proyecto de Google Cloud con facturación habilitada. Los usuarios nuevos pueden obtener una prueba gratuita.
- Conocimiento básico de los conceptos de Google Cloud, como proyectos, Compute Engine, redes de VPC y reglas de firewall Familiaridad básica con las herramientas de línea de comandos de Linux
- Accede a una máquina con la CLI de
gcloudinstalada y configurada, o usa Google Cloud Shell.
En este codelab, usaremos principalmente máquinas virtuales (VM) en Compute Engine dentro de la misma red y región de VPC para simplificar las redes. Se recomienda usar direcciones IP internas.
2. Configura tu entorno
1. Selecciona o crea un proyecto de Google Cloud
Navega a la consola de Google Cloud y selecciona un proyecto existente o crea uno nuevo. Anota el ID de proyecto.
2. Habilita las API obligatorias
Asegúrate de que la API de Compute Engine y la API de Bigtable estén habilitadas para tu proyecto.
gcloud services enable compute.googleapis.com bigtable.googleapis.com bigtableadmin.googleapis.com --project=<your-project-id>
Reemplaza por el ID de tu proyecto real.
3. Elige una región y una zona
Selecciona una región y una zona para tus recursos. Usaremos us-central1 y us-central1-c como ejemplos. Define estas como variables de entorno para mayor comodidad:
export PROJECT_ID="<your-project-id>" export REGION="us-central1" export ZONE="us-central1-c" gcloud config set project $PROJECT_ID gcloud config set compute/region $REGION gcloud config set compute/zone $ZONE
4. Configura reglas de firewall
Debemos permitir la comunicación entre nuestras VMs dentro de la red de VPC predeterminada en varios puertos:
- Puerto CQL de Cassandra/proxies: 9042
- Puerto de verificación de estado del proxy de ZDM: 14001
- SSH: 22
Crea una regla de firewall para permitir el tráfico interno en estos puertos. Usaremos una etiqueta cassandra-migration para aplicar fácilmente esta regla a las VMs relevantes.
gcloud compute firewall-rules create allow-migration-internal \ --network=default \ --action=ALLOW \ --rules=tcp:22,tcp:9042,tcp:14001 \ --source-ranges=10.128.0.0/9 # Adjust if using a custom VPC/IP range \ --target-tags=cassandra-migration
3. Implementa un clúster de Cassandra (origen)
En este codelab, configuraremos un clúster de Cassandra simple de un solo nodo en Compute Engine. En una situación real, te conectarías a tu clúster existente.
1. Crea una VM de GCE para Cassandra
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 empleados y crearemos un espacio de claves llamado "zdmbigtable".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
Dentro de cqlsh:
-- Create keyspace (adjust replication for production)
CREATE KEYSPACE zdmbigtable WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};
-- Use the keyspace
USE zdmbigtable;
-- Create the employee table
CREATE TABLE employee (
name text PRIMARY KEY,
age bigint,
code int,
credited double,
balance float,
is_active boolean,
birth_date timestamp
);
-- Exit cqlsh
EXIT;
Deja la sesión de SSH abierta o anota la dirección IP de esta VM (nombre de host -I).
4. Configura Bigtable (objetivo)
Duración: 0:01
Crear una instancia de Bigtable. Usaremos zdmbigtable como el ID de la instancia.
gcloud bigtable instances create zdmbigtable \ --display-name="ZDM Bigtable Target" \ --cluster=bigtable-c1 \ --cluster-zone=$ZONE \ --cluster-num-nodes=1 # Use 1 node for dev/testing; scale as needed
La propia tabla de Bigtable la creará más adelante la secuencia de comandos de configuración del proxy de Cassandra-Bigtable.
5. Configura el proxy de Cassandra-Bigtable
1. Crea una VM de Compute Engine para el proxy de Cassandra-Bigtable
gcloud compute instances create bigtable-proxy-vm \ --machine-type=e2-medium \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --tags=cassandra-migration \ --boot-disk-size=20GB
Establece una conexión SSH a bigtable-proxy-vm:
gcloud compute ssh bigtable-proxy-vm
Dentro de la VM:
# Install Git and Go sudo apt-get update sudo apt-get install -y git golang-go # Clone the proxy repository # Replace with the actual repository URL if different git clone https://github.com/GoogleCloudPlatform/cloud-bigtable-ecosystem.git cd cassandra-to-bigtable-proxy/ # Set Go environment variables export GOPATH=$HOME/go export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin
2. Configura el proxy
nano config.yaml
Actualiza las siguientes variables. Para obtener una configuración más avanzada, usa este ejemplo que se proporciona en GitHub.
#!/bin/bash
cassandraToBigtableConfigs:
# Global default GCP Project ID
projectId: <your-project-id>
listeners:
- name: cluster1
port: 9042
bigtable:
#If you want to use multiple instances then pass the instance names by comma seperated
#Instance name should not contain any special characters except underscore(_)
instanceIds: zdmbigtable
# Number of grpc channels to be used for Bigtable session.
Session:
grpcChannels: 4
otel:
# Set enabled to true or false for OTEL metrics/traces/logs.
enabled: False
# Name of the collector service to be setup as a sidecar
serviceName: cassandra-to-bigtable-otel-service
healthcheck:
# Enable the health check in this proxy application config only if the
# "health_check" extension is added to the OTEL collector service configuration.
#
# Recommendation:
# Enable the OTEL health check if you need to verify the collector's availability
# at the start of the application. For development or testing environments, it can
# be safely disabled to reduce complexity.
# Enable/Disable Health Check for OTEL, Default 'False'.
enabled: False
# Health check endpoint for the OTEL collector service
endpoint: localhost:13133
metrics:
# Collector service endpoint
endpoint: localhost:4317
traces:
# Collector service endpoint
endpoint: localhost:4317
#Sampling ratio should be between 0 and 1. Here 0.05 means 5/100 Sampling ratio.
samplingRatio: 1
loggerConfig:
# Specifies the type of output, here it is set to 'file' indicating logs will be written to a file.
# Value of `outputType` should be `file` for file type or `stdout` for standard output.
# Default value is `stdout`.
outputType: stdout
# Set this only if the outputType is set to `file`.
# The path and name of the log file where logs will be stored. For example, output.log, Required Key.
# Default `/var/log/cassandra-to-spanner-proxy/output.log`.
fileName: output/output.log
# Set this only if the outputType is set to `file`.
# The maximum size of the log file in megabytes before it is rotated. For example, 500 for 500 MB.
maxSize: 10
# Set this only if the outputType is set to `file`.
# The maximum number of backup log files to keep. Once this limit is reached, the oldest log file will be deleted.
maxBackups: 2
# Set this only if the outputType is set to `file`.
# The maximum age in days for a log file to be retained. Logs older than this will be deleted. Required Key.
# Default 3 days
maxAge: 1
# Set this only if the outputType is set to `file`.
# Default value is set to 'False'. Change the value to 'True', if log files are required to be compressed.
compress: True
Guarda y cierra el archivo (Ctrl + X, Y y, luego, Intro en nano).
3. Inicia el proxy de Cassandra-Bigtable
Inicia el servidor proxy.
# At the root of the cassandra-to-bigtable-proxy directory go run proxy.go
El proxy se iniciará y escuchará en el puerto 9042 para las conexiones de CQL entrantes. Mantén esta sesión de la terminal en ejecución. Anota la dirección IP de esta VM (nombre de host -I).
4. Crea una tabla con CQL
Conecta cqlsh a la dirección IP de la VM de proxy de Cassandra-Bigtable.
En cqlsh, ejecuta el siguiente comando:
-- Create the employee table
CREATE TABLE zdmbigtable.employee (
name text PRIMARY KEY,
age bigint,
code int,
credited double,
balance float,
is_active boolean,
birth_date timestamp
);
Verifica en la consola de Google Cloud que la tabla de empleados y la tabla de metadatos existan en tu instancia de Bigtable.
6. Configura el proxy de ZDM
El proxy de ZDM requiere al menos dos máquinas: uno o más nodos de proxy que controlen el tráfico y un "jumphost" que se use para la implementación y la orquestación a través de Ansible.
1. Crea VMs de Compute Engine para el proxy de ZDM
Necesitamos dos VMs: zdm-proxy-jumphost y zdm-proxy-node-1.
# Jumphost VM gcloud compute instances create zdm-jumphost \ --machine-type=e2-medium \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --tags=cassandra-migration \ --boot-disk-size=20GB # Proxy Node VM gcloud compute instances create zdm-proxy-node-1 \ --machine-type=e2-standard-8 \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --tags=cassandra-migration \ --boot-disk-size=20GB
Anota las direcciones IP de ambas VMs.
2. Prepara el host de salto
Establece una conexión SSH a zdm-jumphost
gcloud compute ssh zdm-jumphost
# Install Git and Ansible
sudo apt-get update
sudo apt-get install -y git ansible
Dentro del host de salto
git clone https:\/\/github.com/datastax/zdm-proxy-automation.git
cd zdm-proxy-automation/ansible/
Edita el archivo de configuración principal vars/zdm_proxy_cluster_config.yml:
Actualiza origin_contact_points y target_contact_points con las direcciones IP internas de tu VM de Cassandra y de la VM de proxy de Cassandra-Bigtable, respectivamente. Deja la autenticación comentada, ya que no la configuramos.
##############################
#### ORIGIN CONFIGURATION ####
##############################
## Origin credentials (leave commented if no auth)
# origin_username: ...
# origin_password: ...
## Set the following two parameters only if Origin is a self-managed, non-Astra cluster
origin_contact_points: <Your-Cassandra-VM-Internal-IP> # Replace!
origin_port: 9042
##############################
#### TARGET CONFIGURATION ####
##############################
## Target credentials (leave commented if no auth)
# target_username: ...
# target_password: ...
## Set the following two parameters only if Target is a self-managed, non-Astra cluster
target_contact_points: <Your-Bigtable-Proxy-VM-Internal-IP> # Replace!
target_port: 9042
# --- Other ZDM Proxy settings can be configured below ---
# ... (keep defaults for this codelab)
Guarda y cierra este archivo.
3. Implementa el proxy de ZDM con Ansible
Ejecuta la guía de Ansible desde el directorio ansible en el host de salto:
ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory
Este comando instalará el software necesario (como Docker) en el nodo de proxy (zdm-proxy-node-1), extraerá la imagen de Docker del proxy de ZDM y, luego, iniciará el contenedor de proxy con la configuración que proporcionaste.
4. Verifica el estado del proxy de ZDM
Verifica el extremo de preparación del proxy de ZDM que se ejecuta en zdm-proxy-node-1 (puerto 14001) desde el host de salto:
# Replace <zdm-proxy-node-1-internal-ip> with the actual internal IP.
curl -G http://<zdm-proxy-node-1-internal-ip>:14001/health/readiness
Deberías ver un resultado similar a este, que indica que el origen (Cassandra) y el destino (proxy de Cassandra-Bigtable) están ACTIVADOS:
{
"OriginStatus": {
"Addr": "<Your-Cassandra-VM-Internal-IP>:9042",
"CurrentFailureCount": 0,
"FailureCountThreshold": 1,
"Status": "UP"
},
"TargetStatus": {
"Addr": "<Your-Bigtable-Proxy-VM-Internal-IP>:9042",
"CurrentFailureCount": 0,
"FailureCountThreshold": 1,
"Status": "UP"
},
"Status": "UP"
}
7. Configura la aplicación y comienza las operaciones de escritura doble
Duración: 0:05
En esta etapa de una migración real, reconfigurarías tus aplicaciones para que apunten a la dirección IP del nodo de proxy de ZDM (p.ej., :9042) en lugar de conectarse directamente a Cassandra.
Una vez que la aplicación se conecta al proxy de ZDM, las operaciones de lectura se entregan desde el origen (Cassandra) de forma predeterminada. Las operaciones de escritura se envían al origen (Cassandra) y al destino (Bigtable, a través del proxy de Cassandra-Bigtable). Esto permite que tu aplicación siga funcionando con normalidad y, al mismo tiempo, garantiza que los datos nuevos se escriban en ambas bases de datos de forma simultánea. Puedes probar la conexión con cqlsh apuntando al proxy de ZDM desde el host de salto o desde otra VM de la red:
Cqlsh <zdm-proxy-node-1-ip-address> 9042
Intenta insertar algunos datos:
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Alice', 30, true);
SELECT * FROM employee WHERE name = 'Alice';
Estos datos se deben escribir en Cassandra y Bigtable. Para confirmarlo en Bigtable, ve a la consola de Google Cloud y abre el editor de consultas de Bigtable de tu instancia. Ejecuta una consulta "SELECT * FROM employee" y los datos insertados recientemente deberían ser visibles.
8. Migra datos históricos con Cassandra Data Migrator
Ahora que las operaciones de escritura doble están activas para los datos nuevos, usa la herramienta Cassandra Data Migrator (CDM) para copiar los datos históricos existentes de Cassandra a Bigtable.
1. Crea una VM de Compute Engine para CDM
Esta VM necesita suficiente memoria para Spark.
gcloud compute instances create cdm-migrator-vm \ --machine-type=e2-medium \ --image-family=ubuntu-2004-lts \ --image-project=ubuntu-os-cloud \ --tags=cassandra-migration \ --boot-disk-size=40GB
2. Instala los requisitos previos (Java 11 y Spark)
Establece una conexión SSH a cdm-migrator-vm:
gcloud compute ssh cdm-migrator-vm
Dentro de la VM:
# Install Java 11
sudo apt-get update
sudo apt-get install -y openjdk-11-jdk
# Verify Java installation
java -version
# Download and Extract Spark (Using version 3.5.3 as requested)
# Check the Apache Spark archives for the correct URL if needed
wget [https://archive.apache.org/dist/spark/spark-3.5.3/spark-3.5.3-bin-hadoop3-scala2.13.tgz](https://archive.apache.org/dist/spark/spark-3.5.3/spark-3.5.3-bin-hadoop3-scala2.13.tgz) tar -xvzf spark-3.5.3-bin-hadoop3-scala2.13.tgz
export SPARK_HOME=$PWD/spark-3.5.3-bin-hadoop3-scala2.13
export PATH=$PATH:$SPARK_HOME/bin
3. Descarga Cassandra Data Migrator
Descarga el archivo jar de la herramienta CDM. Consulta la página de lanzamientos de GitHub de Cassandra Data Migrator para obtener la URL correcta de la versión deseada.
# Example using version 5.2.2 - replace URL if needed
wget https://github.com/datastax/cassandra-data-migrator/releases/download/v5.2.2/cassandra-data-migrator-5.2.2.jar)
4. Configura CDM
Crea un archivo de propiedades llamado cdm.properties.
Nano cdm.properties
Pega la siguiente configuración, reemplaza las direcciones IP y, luego, inhabilita las funciones de TTL o Writetime, ya que Bigtable no las admite directamente de la misma manera. Deja la autenticación como comentario.
# Origin Cassandra Connection
spark.cdm.connect.origin.host <Your-Cassandra-VM-IP-Address> # Replace!
spark.cdm.connect.origin.port 9042
spark.cdm.connect.origin.username cassandra # Leave default, or set if auth is enabled #
spark.cdm.connect.origin.password cassandra # Leave default, or set if auth is enabled #
# Target Bigtable (via Cassandra-Bigtable Proxy)
Connection spark.cdm.connect.target.host <Your-Bigtable-Proxy-VM-IP-Address> # Replace!
spark.cdm.connect.target.port 9042
spark.cdm.connect.target.username cassandra # Leave default, or set if auth is enabled #
spark.cdm.connect.target.password cassandra # Leave default, or set if auth is enabled #
# Disable TTL/Writetime features (Important for Bigtable compatibility via Proxy)
spark.cdm.feature.origin.ttl.automatic false
spark.cdm.feature.origin.writetime.automatic false
spark.cdm.feature.target.ttl.automatic false
spark.cdm.feature.target.writetime.automatic false
Guarda el archivo y ciérralo.
5. Ejecuta el trabajo de migración
Ejecuta la migración con spark-submit. Este comando le indica a Spark que ejecute el archivo jar de CDM con tu archivo de propiedades y especifique el espacio de claves y la tabla que se migrará. Ajusta la configuración de memoria (–driver-memory, –executor-memory) según el tamaño de la VM y el volumen de datos.
Asegúrate de estar en el directorio que contiene el archivo jar y de propiedades de CDM. Reemplaza "cassandra-data-migrator-5.2.2.jar" si descargaste una versión diferente.
./spark-3.5.3-bin-hadoop3-scala2.13/bin/spark-submit \ --properties-file cdm.properties \ --master "local[*]" \ --driver-memory 4G \ --executor-memory 4G \ --class com.datastax.cdm.job.Migrate \ cassandra-data-migrator-5.2.2.jar &> cdm_migration_$(date +%Y%m%d_%H%M).log
La migración se ejecutará en segundo plano, y los registros se escribirán en cdm_migration_…. .log. Supervisa el archivo de registro para ver el progreso y los errores:
tail -f cdm_migration_*.log
6. Verifica la migración de datos
Una vez que se complete correctamente el trabajo de CDM, verifica que los datos históricos existan en Bigtable. Dado que el proxy de Cassandra-Bigtable permite lecturas de CQL, puedes volver a usar cqlsh conectado al proxy de ZDM (que enruta las lecturas al destino después de la migración o se puede configurar para hacerlo) o directamente al proxy de Cassandra-Bigtable para consultar los datos. Conéctate a través del proxy de ZDM:
cqlsh <zdm-proxy-node-1-ip-address> 9042
Dentro de cqlsh:
SELECT COUNT(*) FROM zdmbigtable.employee; -- Check row count matches origin SELECT * FROM employee LIMIT 10; -- Check some sample data
Como alternativa, usa la herramienta cbt (si está instalada en la VM de CDM o Cloud Shell) para buscar datos directamente en Bigtable:
# First, install cbt if needed
# gcloud components update
# gcloud components install cbt
# Then lookup a specific row (replace 'some_employee_name' with an actual primary key)
cbt -project $PROJECT_ID -instance zdmbigtable lookup employee some_employee_name
9. Migración de sistemas (conceptual)
Después de verificar en detalle la coherencia de los datos entre Cassandra y Bigtable, puedes continuar con la migración de sistemas final.
Con el proxy de ZDM, la migración implica volver a configurarlo para que lea principalmente desde el destino (Bigtable) en lugar del origen (Cassandra). Por lo general, esto se hace a través de la configuración del proxy de ZDM, lo que traslada de manera eficaz el tráfico de lectura de tu aplicación a Bigtable.
Una vez que tengas la seguridad de que Bigtable entrega todo el tráfico correctamente, podrás hacer lo siguiente:
- Para detener las operaciones de escritura doble, vuelve a configurar el proxy de ZDM.
- Inhabilita el clúster de Cassandra original.
- Quita el proxy de ZDM y haz que la aplicación se conecte directamente al proxy de Cassandra-Bigtable o usa el cliente nativo de CQL de Bigtable para Java.
Los detalles de la reconfiguración del proxy de ZDM para la migración superan el alcance de este codelab básico, pero se detallan en la documentación de ZDM de Datastax.
10. Limpia
Para evitar que se apliquen cargos, borra los recursos que creaste durante este codelab.
1. Borra VMs de Compute Engine
gcloud compute instances delete cassandra-origin-vm zdm-proxy-jumphost zdm-proxy-node-1 bigtable-proxy-vm cdm-migrator-vm --zone=$ZONE --quiet
2. Borra una instancia de Bigtable
gcloud bigtable instances delete zdmbigtable
3. Borra reglas de firewall
gcloud compute firewall-rules delete allow-migration-internal
4. 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!
Completaste correctamente el proceso de configuración de una ruta de migración basada en proxy de Apache Cassandra a Bigtable.
Aprendiste a hacer lo siguiente:
Implementa Cassandra y Bigtable.
- Configura el proxy de Cassandra-Bigtable para la compatibilidad con CQL.
- Implementa el proxy de ZDM de Datastax para administrar el tráfico y las operaciones de escritura dobles.
- Usa el Migración de datos de Cassandra para mover datos históricos.
Este enfoque permite realizar migraciones con un tiempo de inactividad mínimo y sin cambios en el código aprovechando la capa de proxy.
Próximos pasos
- Explora la documentación de Bigtable
- Consulta la documentación del proxy de ZDM de Datastax para conocer las configuraciones avanzadas y los procedimientos de migración.
- Revisa el repositorio de proxy de Cassandra-Bigtable para obtener más detalles.
- Consulta el repositorio de Cassandra Data Migrator para ver el uso avanzado.
- Prueba otros codelabs de Google Cloud