À propos de cet atelier de programmation
1. Introduction
Bigtable est un service de base de données NoSQL entièrement géré et hautes performances, conçu pour les charges de travail analytiques et opérationnelles importantes. La migration de bases de données existantes telles qu'Apache Cassandra vers Bigtable nécessite souvent une planification minutieuse pour minimiser les temps d'arrêt et l'impact sur les applications.
Cet atelier de programmation présente une stratégie de migration de Cassandra vers Bigtable à l'aide d'une combinaison d'outils de proxy:
- Proxy Cassandra-Bigtable:permet aux clients et outils Cassandra (comme
cqlsh
ou les pilotes) d'interagir avec Bigtable à l'aide du protocole Cassandra Query Language (CQL) en traduisant les requêtes. - Proxy de migration ZDM (Zero Downtime Migration) de Datastax:proxy Open Source situé entre votre application et vos services de base de données (Cassandra d'origine et Bigtable de destination via le proxy Cassandra-Bigtable). Il orchestre les écritures en double et gère le routage du trafic, ce qui permet de migrer avec un minimum de modifications et d'indisponibilité de l'application.
- Cassandra Data Migrator (CDM) : outil Open Source permettant de migrer de manière groupée les données historiques du cluster Cassandra source vers l'instance Bigtable cible.
Points abordés
- Configurer un cluster Cassandra de base sur Compute Engine
- Créer une instance Bigtable
- Déployer et configurer le proxy Cassandra-Bigtable pour mapper un schéma Cassandra sur Bigtable
- Déployer et configurer le proxy Datastax ZDM pour les écritures en double
- Utiliser l'outil Cassandra Data Migrator pour migrer des données existantes de manière groupée
- Workflow global d'une migration de Cassandra vers Bigtable basée sur un proxy.
Prérequis
- Un projet Google Cloud avec facturation activée. Les nouveaux utilisateurs peuvent bénéficier d'un essai sans frais.
- Connaissances de base des concepts Google Cloud tels que les projets, Compute Engine, les réseaux VPC et les règles de pare-feu Connaissances de base des outils de ligne de commande Linux
- Accès à une machine sur laquelle la CLI
gcloud
est installée et configurée, ou utilisation de Google Cloud Shell.
Pour cet atelier de programmation, nous allons principalement utiliser des machines virtuelles (VM) sur Compute Engine dans la même région et le même réseau VPC afin de simplifier la mise en réseau. Nous vous recommandons d'utiliser des adresses IP internes.
2. Configurer votre environnement
1. Sélectionner ou créer un projet Google Cloud
Accédez à la console Google Cloud, puis sélectionnez un projet existant ou créez-en un. Notez votre ID de projet.
2. Activer les API requises
Assurez-vous que l'API Compute Engine et l'API Bigtable sont activées pour votre projet.
gcloud services enable compute.googleapis.com bigtable.googleapis.com bigtableadmin.googleapis.com --project=<your-project-id>
Remplacez par l'ID de votre projet.
3. Choisir une région et une zone
Sélectionnez une région et une zone pour vos ressources. Nous utiliserons us-central1 et us-central1-c comme exemples. Définissez-les comme variables d'environnement pour plus de commodité:
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. Configurer des règles de pare-feu
Nous devons autoriser la communication entre nos VM sur le réseau VPC par défaut sur plusieurs ports:
- Port CQL Cassandra/Proxies: 9042
- Port de vérification de l'état du proxy ZDM: 14001
- SSH: 22
Créez une règle de pare-feu pour autoriser le trafic interne sur ces ports. Nous allons utiliser un tag cassandra-migration
pour appliquer facilement cette règle aux VM concernées.
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. Déployer un cluster Cassandra (Origin)
Pour cet atelier de programmation, nous allons configurer un cluster Cassandra à nœud unique simple sur Compute Engine. Dans un scénario réel, vous vous connecterez à votre cluster existant.
1. Créer une VM GCE pour 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. Installer 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. Créer un espace de clés et une table
Nous allons utiliser un exemple de table des employés et créer un espace de clés appelé "zdmbigtable".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
Dans 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;
Laissez la session SSH ouverte ou notez l'adresse IP de cette VM (hostname -I).
4. Configurer Bigtable (cible)
Durée : 0:01
Créer une instance Bigtable Nous utiliserons zdmbigtable comme ID d'instance.
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 table Bigtable elle-même sera créée ultérieurement par le script de configuration du proxy Cassandra-Bigtable.
5. Configurer le proxy Cassandra-Bigtable
1. Créer une VM Compute Engine pour le proxy 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
Connectez-vous en SSH à bigtable-proxy-vm:
gcloud compute ssh bigtable-proxy-vm
Dans 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. Configurer le proxy
nano config.yaml
Mettez à jour les variables suivantes. Pour une configuration plus avancée, utilisez cet exemple fourni sur 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
Enregistrez et fermez le fichier (Ctrl+X, puis Y, puis Entrée dans nano).
3. Démarrer le proxy Cassandra-Bigtable
Démarrez le serveur proxy.
# At the root of the cassandra-to-bigtable-proxy directory go run proxy.go
Le proxy démarre et écoute les connexions CQL entrantes sur le port 9042. Maintenez cette session de terminal en cours d'exécution. Notez l'adresse IP de cette VM (nom d'hôte -I).
4. Créer une table via CQL
Connectez cqlsh
à l'adresse IP de la VM de proxy Cassandra-Bigtable.
Dans cqlsh
, exécutez la commande suivante :
-- 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 );
Dans la console Google Cloud, vérifiez que la table des employés et la table des métadonnées existent dans votre instance Bigtable.
6. Configurer le proxy ZDM
Le proxy ZDM nécessite au moins deux machines: un ou plusieurs nœuds proxy qui gèrent le trafic et un "jumphost" utilisé pour le déploiement et l'orchestration via Ansible.
1. Créer des VM Compute Engine pour le proxy ZDM
Nous avons besoin de deux VM: zdm-proxy-jumphost et 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
Notez les adresses IP des deux VM.
2. Préparer le jumphost
Se connecter en SSH au zdm-jumphost
gcloud compute ssh zdm-jumphost
# Install Git and Ansible
sudo apt-get update
sudo apt-get install -y git ansible
À l'intérieur du jumphost
git clone https:\/\/github.com/datastax/zdm-proxy-automation.git
cd zdm-proxy-automation/ansible/
Modifiez le fichier de configuration principal vars/zdm_proxy_cluster_config.yml:
Remplacez les valeurs origin_contact_points et target_contact_points par les adresses IP internes de votre VM Cassandra et de votre VM de proxy Cassandra-Bigtable, respectivement. Laissez l'authentification en commentaire, car nous ne l'avons pas configurée.
##############################
#### 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)
Enregistrez et fermez ce fichier.
3. Déployer le proxy ZDM à l'aide d'Ansible
Exécutez le playbook Ansible à partir du répertoire ansible sur le jumphost:
ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory
Cette commande installe les logiciels nécessaires (comme Docker) sur le nœud proxy (zdm-proxy-node-1), extrait l'image Docker du proxy ZDM et démarre le conteneur proxy avec la configuration que vous avez fournie.
4. Vérifier l'état du proxy ZDM
Vérifiez le point de terminaison de disponibilité du proxy ZDM exécuté sur zdm-proxy-node-1 (port 14001) à partir du jumphost:
# Replace <zdm-proxy-node-1-internal-ip> with the actual internal IP.
curl -G http://<zdm-proxy-node-1-internal-ip>:14001/health/readiness
Un résultat semblable à celui-ci doit s'afficher, indiquant que l'origine (Cassandra) et la cible (proxy Cassandra-Bigtable) sont en État UP:
{
"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. Configurer l'application et démarrer les écritures en double
Durée : 0:05
À ce stade d'une migration réelle, vous devez reconfigurer vos applications pour qu'elles pointent vers l'adresse IP du nœud de proxy ZDM (par exemple, :9042) au lieu de se connecter directement à Cassandra.
Une fois que l'application se connecte au proxy ZDM: les lectures sont diffusées à partir de l'origine (Cassandra) par défaut. Les écritures sont envoyées à la fois à l'origine (Cassandra) et à la cible (Bigtable, via le proxy Cassandra-Bigtable). Cela permet à votre application de continuer à fonctionner normalement tout en veillant à ce que les nouvelles données soient écrites simultanément dans les deux bases de données. Vous pouvez tester la connexion à l'aide de cqlsh pointé vers le proxy ZDM depuis le jumphost ou une autre VM du réseau:
Cqlsh <zdm-proxy-node-1-ip-address> 9042
Essayez d'insérer des données:
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Alice', 30, true); SELECT * FROM employee WHERE name = 'Alice';
Ces données doivent être écrites à la fois dans Cassandra et Bigtable. Vous pouvez le vérifier dans Bigtable en accédant à la console Google Cloud et en ouvrant l'éditeur de requêtes Bigtable pour votre instance. Exécutez une requête "SELECT * FROM employee". Les données récemment insérées devraient être visibles.
8. Migrer des données historiques à l'aide de Cassandra Data Migrator
Maintenant que les écritures en double sont actives pour les nouvelles données, utilisez l'outil Cassandra Data Migrator (CDM) pour copier les données historiques existantes de Cassandra vers Bigtable.
1. Créer une VM Compute Engine pour CDM
Cette VM a besoin de suffisamment de mémoire pour 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. Installer les prérequis (Java 11, Spark)
Connectez-vous en SSH à cdm-migrator-vm:
gcloud compute ssh cdm-migrator-vm
Dans 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. Télécharger Cassandra Data Migrator
Téléchargez le fichier JAR de l'outil CDM. Consultez la page de version GitHub du Cassandra Data Migrator pour obtenir l'URL correcte de la version souhaitée.
# 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. Configurer le CDM
Créez un fichier de propriétés nommé cdm.properties.
Nano cdm.properties
Collez la configuration suivante, en remplaçant les adresses IP et en désactivant les fonctionnalités TTL/Writetime, car elles ne sont pas directement compatibles avec Bigtable de la même manière. Laissez l'authentification en commentaire.
# 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
Enregistrez et fermez le fichier.
5. Exécuter la tâche de migration
Exécutez la migration à l'aide de spark-submit. Cette commande indique à Spark d'exécuter le fichier JAR CDM à l'aide de votre fichier de propriétés et de spécifier l'espace de clés et la table à migrer. Ajustez les paramètres de mémoire (–driver-memory, –executor-memory) en fonction de la taille de votre VM et du volume de données.
Assurez-vous d'être dans le répertoire contenant le fichier JAR et le fichier de propriétés du CDM. Remplacez "cassandra-data-migrator-5.2.2.jar" si vous avez téléchargé une autre version.
./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 migration s'exécute en arrière-plan, et les journaux sont écrits dans cdm_migration_... .log. Surveillez la progression du fichier journal et recherchez d'éventuelles erreurs:
tail -f cdm_migration_*.log
6. Vérifier la migration des données
Une fois la tâche CDM terminée, vérifiez que les données historiques existent dans Bigtable. Étant donné que le proxy Cassandra-Bigtable autorise les lectures CQL, vous pouvez à nouveau utiliser cqlsh connecté au proxy ZDM (qui achemine les lectures vers la cible après la migration ou peut être configuré pour le faire) ou directement au proxy Cassandra-Bigtable pour interroger les données. Se connecter via le proxy ZDM:
cqlsh <zdm-proxy-node-1-ip-address> 9042
Dans cqlsh:
SELECT COUNT(*) FROM zdmbigtable.employee; -- Check row count matches origin SELECT * FROM employee LIMIT 10; -- Check some sample data
Vous pouvez également utiliser l'outil cbt (s'il est installé sur la VM CDM ou Cloud Shell) pour rechercher des données directement dans 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. Basculement (conceptuel)
Après avoir vérifié minutieusement la cohérence des données entre Cassandra et Bigtable, vous pouvez procéder au basculement final.
Avec le proxy ZDM, la transition consiste à le reconfigurer pour qu'il lise principalement à partir de la cible (Bigtable) plutôt que de l'origine (Cassandra). Cela se fait généralement via la configuration du proxy ZDM, qui transfère efficacement le trafic de lecture de votre application vers Bigtable.
Une fois que vous êtes sûr que Bigtable diffuse correctement tout le trafic, vous pouvez éventuellement:
- Arrêtez les doubles écritures en reconfigurant le proxy ZDM.
- Mettez hors service le cluster Cassandra d'origine.
- Supprimez le proxy ZDM et demandez à l'application de se connecter directement au proxy Cassandra-Bigtable ou d'utiliser le client CQL Bigtable natif pour Java.
Les détails de la reconfiguration du proxy ZDM pour la transition ne sont pas abordés dans cet atelier de programmation de base, mais sont détaillés dans la documentation Datastax ZDM.
10. Effectuer un nettoyage
Pour éviter que des frais ne vous soient facturés, supprimez les ressources créées lors de cet atelier de programmation.
1. Supprimer des VM 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. Supprimer une instance Bigtable
gcloud bigtable instances delete zdmbigtable
3. Supprimer des règles de pare-feu
gcloud compute firewall-rules delete allow-migration-internal
4. Supprimer la base de données Cassandra (si elle est installée localement ou persistante)
Si vous avez installé Cassandra en dehors d'une VM Compute Engine créée ici, suivez les étapes appropriées pour supprimer les données ou désinstaller Cassandra.
11. Félicitations !
Vous avez suivi la procédure de configuration d'un chemin de migration basé sur un proxy d'Apache Cassandra vers Bigtable.
Vous avez appris à:
Déployez Cassandra et Bigtable.
- Configurez le proxy Cassandra-Bigtable pour la compatibilité avec CQL.
- Déployez le proxy ZDM Datastax pour gérer les écritures et le trafic en double.
- Utilisez le migrateur de données Cassandra pour déplacer les données historiques.
Cette approche permet de migrer avec un temps d'arrêt minimal et sans modification de code en exploitant la couche proxy.
Étapes suivantes
- Consulter la documentation Bigtable
- Consultez la documentation du proxy Datastax ZDM pour en savoir plus sur les configurations avancées et les procédures de transition.
- Pour en savoir plus, consultez le dépôt Cassandra-Bigtable Proxy.
- Consultez le dépôt du migrateur de données Cassandra pour en savoir plus sur son utilisation avancée.
- Essayer d'autres ateliers de programmation Google Cloud