À propos de cet atelier de programmation
1. Introduction
Spanner est un service de base de données entièrement géré, évolutif horizontalement et distribué à l'échelle mondiale, qui convient parfaitement aux charges de travail relationnelles et non relationnelles.
L'interface Cassandra de Spanner vous permet de profiter de l'infrastructure entièrement gérée, évolutive et hautement disponible de Spanner à l'aide d'outils et de syntaxes Cassandra familiers.
Points abordés
- Configurer une instance et une base de données Spanner
- Convertir votre schéma et votre modèle de données Cassandra
- Déployer et configurer les écritures en double pour les données entrantes
- Exporter vos données historiques de Cassandra vers Spanner de manière groupée
- Comment valider les données pour garantir leur intégrité tout au long du processus de migration ?
- Pointer votre application vers Spanner au lieu de Cassandra
Prérequis
- Un projet Google Cloud associé à un compte de facturation.
- Accès à une machine sur laquelle la CLI
gcloudest installée et configurée, ou utilisation de Google Cloud Shell. - Un navigateur (Chrome ou Firefox, par exemple).
2. Préparation
Créer un projet GCP
Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. Si vous n'avez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.
- Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pourrez toujours le modifier.
- L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par
PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet. - Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.
Configuration de facturation
Ensuite, suivez le guide de l'utilisateur pour gérer la facturation et activez la facturation dans la console Cloud. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300$. Pour éviter que des frais ne vous soient facturés après ce tutoriel, vous pouvez arrêter l'instance Spanner à la fin de l'atelier de programmation en suivant l'étape 9 "Effectuer un nettoyage".
Démarrer Cloud Shell
Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Google Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.
Dans la console Google Cloud, cliquez sur l'icône Cloud Shell dans la barre d'outils supérieure :
Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :
Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez effectuer toutes les tâches de cet atelier de programmation dans un navigateur. Vous n'avez rien à installer.
Étape suivante
Vous allez ensuite déployer un cluster Cassandra.
3. Déployer un cluster Cassandra (Origin)
Pour cet atelier de programmation, nous allons configurer un cluster Cassandra à nœud unique sur Compute Engine.
1. Créer une VM GCE pour Cassandra
Pour créer une instance, utilisez la commande 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. 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 "users" et créer un espace de clés appelé "analytics".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
Dans 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;
Laissez la session SSH ouverte ou notez l'adresse IP de cette VM (hostname -I).
Étape suivante
Vous allez maintenant configurer une instance et une base de données Cloud Spanner.
4. Créer une instance et une base de données Spanner (cible)
Dans Spanner, une instance est un cluster de ressources de calcul et de stockage qui héberge une ou plusieurs bases de données Spanner. Vous aurez besoin d'au moins une instance pour héberger une base de données Spanner pour cet atelier de programmation.
Vérifier la version du SDK gcloud
Avant de créer une instance, assurez-vous que le SDK gcloud dans Google Cloud Shell a été mis à jour vers la version requise (SDK gcloud 493.0.0). Pour connaître la version du SDK gcloud, exécutez la commande ci-dessous.
$ gcloud version | grep Google
Voici un exemple de résultat:
Google Cloud SDK 489.0.0
Si la version que vous utilisez est antérieure à la version 493.0.0 requise (489.0.0 dans l'exemple précédent), vous devez mettre à niveau votre SDK Google Cloud en exécutant la commande suivante:
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
Activer l'API Spanner
Dans Cloud Shell, assurez-vous que l'ID de votre projet est configuré. Utilisez la première commande ci-dessous pour trouver l'ID de projet actuellement configuré. Si le résultat n'est pas celui attendu, la deuxième commande ci-dessous définit le bon.
gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]
Configurez votre région par défaut sur us-central1. Vous pouvez remplacer cette région par une autre compatible avec les configurations régionales de Spanner.
gcloud config set compute/region us-central1
Activez l'API Spanner:
gcloud services enable spanner.googleapis.com
Créer l'instance Spanner
Dans cette section, vous allez créer une instance en essai sans frais ou une instance provisionnée. Tout au long de cet atelier de programmation, l'ID d'instance de l'adaptateur Cassandra Spanner utilisé est cassandra-adapter-demo, défini comme variable SPANNER_INSTANCE_ID à l'aide de la ligne de commande export. Vous pouvez éventuellement choisir votre propre nom d'ID d'instance.
Créer une instance Spanner en essai sans frais
Une instance d'essai sans frais de Spanner est disponible pendant 90 jours pour tous les utilisateurs disposant d'un compte Google et dont la facturation Cloud est activée dans leur projet. Des frais ne vous seront facturés que si vous choisissez de passer votre instance d'essai sans frais à une instance payante. L'adaptateur Cassandra Spanner est compatible avec l'instance d'essai sans frais. Si vous y êtes éligible, créez une instance d'essai sans frais en ouvrant Cloud Shell et en exécutant la commande suivante:
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"
Résultat de la commande :
$ gcloud spanner instances create $SPANNER_INSTANCE_ID \ --config=$SPANNER_REGION \ --instance-type=free-instance \ --description="Spanner Cassandra Adapter demo" Creating instance...done.
Créer la base de données
Une fois votre instance en cours d'exécution, vous pouvez créer la base de données. C'est dans la base de données que vous définissez votre schéma. Vous pouvez également contrôler qui a accès à la base de données, configurer le chiffrement personnalisé, configurer l'optimiseur et définir la période de conservation.
La base de données sera créée dans l'instance avec l'ID SPANNER_INSTANCE_ID.
Pour créer une base de données, utilisez l'outil de ligne de commande gcloud:
export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
--instance=$SPANNER_INSTANCE_ID
Résultat de la commande :
$ gcloud spanner databases create $SPANNER_DATABASE \ --instance=$SPANNER_INSTANCE_ID Creating database...done.
5. Migrer le schéma et le modèle de données Cassandra vers Spanner
La phase initiale et cruciale de la transition des données d'une base de données Cassandra vers Spanner implique de transformer le schéma Cassandra existant pour l'adapter aux exigences structurelles et de type de données de Spanner.
Pour simplifier ce processus de migration de schéma complexe, Spanner fournit un outil Open Source précieux appelé "outil de schéma Spanner Cassandra".
Outil de schéma Cassandra Spanner
L'outil de schéma Cassandra Spanner est un outil Open Source autonome pour l'évaluation et la migration de schémas Spanner. Sa fonction principale est de créer automatiquement un schéma Spanner en fonction des définitions trouvées dans un schéma Cassandra existant. En analysant les structures de table Cassandra, les types de données et les configurations de clés primaires, l'outil génère des définitions de table Spanner équivalentes, ce qui réduit considérablement l'effort manuel généralement impliqué dans la traduction de schéma.
Exporter le schéma Cassandra
Avant d'utiliser l'outil de schéma Cassandra Spanner, la première étape concrète consiste à extraire le schéma de votre cluster Cassandra actuel. Pour ce faire, connectez-vous à votre cluster Cassandra existant via cqlsh, puis exportez le schéma à partir de Cassandra:
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
Dans cette commande, [IP] doit être remplacé par l'adresse IP ou le nom d'hôte de l'un des nœuds de votre cluster Cassandra. La partie -e DESC SCHEMA de la commande demande à cqlsh de décrire l'ensemble du schéma du cluster Cassandra. La sortie de cette commande, qui contient les instructions CREATE KEYSPACE et CREATE TABLE, est ensuite redirigée vers un fichier nommé orig_schema.cql.
Le contenu de ce fichier orig_schema.cql représentera essentiellement un plan textuel de votre schéma Cassandra. Le contenu du fichier orig_schema.cql doit se présenter comme suit:
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';
Cloner le dépôt
Pour utiliser l'outil de schéma Cassandra Spanner, l'étape suivante consiste à obtenir le code source de l'outil. Pour ce faire, clonez le dépôt hébergé sur GitHub. Clonez l'outil de schéma Cassandra Spanner à partir de GitHub en saisissant la commande suivante dans Cloud Shell:
git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git
Accédez ensuite au répertoire "spanner-cassandra-schema-tool" dans lequel vous allez exécuter la commande.
cd spanner-cassandra-schema-tool
Installer des dépendances
L'outil de schéma Cassandra Spanner est écrit dans le langage de programmation Go. Pour que l'outil fonctionne correctement, il s'appuie sur certains modules (bibliothèques) Go externes. Vous devez télécharger et gérer ces dépendances avant de pouvoir exécuter l'outil. Dans le répertoire spanner-cassandra-schema-tool, exécutez la commande suivante:
go mod download
Configurer des identifiants Google Cloud
Cet outil utilise les identifiants par défaut de l'application (ADC) comme source d'identifiants pour se connecter aux bases de données Spanner. Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur le chemin d'accès au fichier de clé de votre compte de service.
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
Remplacez /path/to/your/service-account-file.json par le chemin d'accès réel au fichier de clé de compte de service que vous avez téléchargé. Définir cette variable d'environnement garantit que l'outil de schéma Cassandra Spanner peut s'authentifier de manière sécurisée avec votre projet Google Cloud et votre instance Spanner.
Utilisation
Une fois les dépendances installées et les identifiants Google Cloud configurés, vous pouvez exécuter l'outil de schéma Cassandra Spanner pour générer le schéma Spanner à partir du fichier de schéma Cassandra exporté. Accédez au répertoire spanner-cassandra-schema-tool dans votre terminal ou Cloud Shell, puis exécutez la commande go run suivante:
go run schema_converter.go \
--project $PROJECT_ID \
--instance $SPANNER_INSTANCE_ID \
--database $SPANNER_DATABASE \
--cql orig_schema.cql \
--dry-run
L'exécution avec l'option --dry-run ne génère que le schéma. Examinez et affinez le mappage des types de données et les colonnes de clé primaire générées par l'outil. Assurez-vous que les types de données Spanner représentent précisément la plage, la précision et la sémantique des types de bases de données Cassandra correspondants.
Cet outil met en correspondance les types Cassandra avec les types Spanner, comme indiqué dans la section Types de données Cassandra compatibles.
Le résultat de la commande ressemble à ceci:
.....
[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!
Si vous souhaitez également que le schéma soit appliqué automatiquement à Spanner, exécutez la ligne de commande sans l'option --dry-run.
Dans la console Google Cloud, vérifiez que les tables et la table de métadonnées existent dans la base de données Cloud Spanner.
8. Validez vos données
[TODO]
9. Faire pointer votre application vers Spanner (passage)
Une fois que vous avez minutieusement validé l'exactitude et l'intégrité de vos données après la phase de migration, l'étape clé consiste à faire passer l'accent opérationnel de votre application de l'ancien système Cassandra à la nouvelle base de données Google Cloud Spanner. Cette période de transition critique est communément appelée "passage".
La phase de transition marque le moment où le trafic d'application en direct est redirigé depuis le cluster Cassandra d'origine et directement connecté à l'infrastructure Spanner robuste et évolutive. Cette transition montre à quel point les applications peuvent facilement exploiter la puissance de Spanner, en particulier lorsqu'elles utilisent l'interface Spanner Cassandra.
L'interface Cassandra Spanner simplifie le processus de transition. Il s'agit principalement de configurer vos applications clientes pour qu'elles utilisent le client Cassandra Spanner natif pour toutes les interactions de données. Au lieu de communiquer avec votre base de données Cassandra (origine), vos applications commenceront à lire et à écrire des données directement dans Spanner (cible) sans aucune difficulté. Ce changement fondamental de connectivité est généralement obtenu à l'aide de SpannerCqlSessionBuilder, un composant clé de la bibliothèque cliente Spanner Cassandra qui facilite l'établissement de connexions à votre instance Spanner. Cela redirige efficacement l'ensemble du flux de trafic de données de votre application vers Spanner.
Pour les applications Java qui utilisent déjà la bibliothèque cassandra-java-driver, l'intégration du client Java Cassandra Spanner ne nécessite que de légères modifications de l'initialisation de CqlSession.
Obtenir la dépendance google-cloud-spanner-cassandra
Pour commencer à utiliser le client Cassandra Spanner, vous devez d'abord intégrer sa dépendance à votre projet. Les artefacts google-cloud-spanner-cassandra sont publiés dans Maven Central, sous l'ID de groupe com.google.cloud. Ajoutez la nouvelle dépendance suivante sous la section <dependencies> existante de votre projet Java. Voici un exemple simplifié montrant comment inclure la dépendance 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>
Modifier la configuration de la connexion pour se connecter à Spanner
Une fois que vous avez ajouté la dépendance nécessaire, l'étape suivante consiste à modifier la configuration de votre connexion pour vous connecter à la base de données Spanner.
Une application typique qui interagit avec un cluster Cassandra utilise souvent un code semblable à celui-ci pour établir une connexion:
CqlSession session = CqlSession.builder()
.addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
.withLocalDatacenter("datacenter1")
.withAuthCredentials("username", "password")
.build();
Pour rediriger cette connexion vers Spanner, vous devez modifier la logique de création de CqlSession. Au lieu d'utiliser directement la CqlSessionBuilder standard à partir de cassandra-java-driver, vous utiliserez la SpannerCqlSession.builder() fournie par le client Cassandra Spanner. Voici un exemple illustrant comment modifier votre code de connexion:
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();
En instanciant CqlSession à l'aide de SpannerCqlSession.builder() et en fournissant le databaseUri approprié, votre application établira désormais une connexion via le client Cassandra Spanner à votre base de données Spanner cible. Ce changement crucial garantit que toutes les opérations de lecture et d'écriture ultérieures effectuées par votre application seront dirigées vers Spanner et gérées par lui, ce qui permettra de finaliser la transition initiale. À ce stade, votre application devrait continuer à fonctionner comme prévu, désormais optimisée par l'évolutivité et la fiabilité de Spanner.
En coulisses: fonctionnement du client Cassandra Spanner
Le client Cassandra Spanner agit en tant que proxy TCP local, interceptant les octets de protocole Cassandra bruts envoyés par un pilote ou un outil client. Il encapsule ensuite ces octets avec les métadonnées nécessaires dans des messages gRPC pour communiquer avec Spanner. Les réponses de Spanner sont traduites dans le format de communication Cassandra et renvoyées au pilote ou à l'outil d'origine.
Une fois que vous êtes sûr que Spanner diffuse correctement tout le trafic, vous pouvez éventuellement:
- Arrêtez les doubles écritures.
- Mettez hors service le cluster Cassandra d'origine.
10. Nettoyer (facultatif)
Pour nettoyer, accédez simplement à la section Spanner de Cloud Console et supprimez l'instance cassandra-adapter-demo que nous avons créée dans l'atelier de programmation.
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 !
Étape suivante
- En savoir plus sur Cloud Spanner
- En savoir plus sur l'interface Cassandra