Informazioni su questo codelab
1. Introduzione
Spanner è un servizio di database completamente gestito, scalabile orizzontalmente e distribuito a livello globale, ideale per carichi di lavoro sia relazionali che non relazionali.
L'interfaccia Cassandra di Spanner ti consente di sfruttare l'infrastruttura completamente gestita, scalabile e ad alta disponibilità di Spanner utilizzando la sintassi e gli strumenti di Cassandra a te familiari.
Obiettivi didattici
- Come configurare un'istanza e un database Spanner.
- Come convertire lo schema e il modello di dati di Cassandra.
- Come implementare e configurare le doppie scritture per i dati in entrata.
- Come esportare collettivamente i dati storici da Cassandra a Spanner.
- Come convalidare i dati per garantire l'integrità dei dati durante la procedura di migrazione.
- Come indirizzare l'applicazione a Spanner anziché a Cassandra.
Che cosa ti serve
- Un progetto Google Cloud collegato a un account di fatturazione.
- Accedi a una macchina con l'interfaccia a riga di comando
gcloudinstallata e configurata oppure utilizza Google Cloud Shell. - Un browser web, ad esempio Chrome o Firefox.
2. Configurazione e requisiti
Crea un progetto Google Cloud
Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.
- Il nome del progetto è il nome visualizzato per i partecipanti al progetto. Si tratta di una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
- L'ID progetto è univoco per tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo essere stato impostato). La console Cloud genera automaticamente una stringa univoca; di solito non ti interessa quale sia. Nella maggior parte dei codelab, dovrai fare riferimento al tuo ID progetto (in genere identificato come
PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare il tuo e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane invariato per tutta la durata del progetto. - Per tua informazione, esiste un terzo valore, un Numero progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.
Configurazione di fatturazione
Successivamente, dovrai seguire la guida dell'utente per la gestione della fatturazione e attivare la fatturazione nella console Cloud. I nuovi utenti di Google Cloud sono idonei al programma Prova senza costi di 300$. Per evitare addebiti al termine di questo tutorial, puoi arrestare l'istanza Spanner alla fine del codelab seguendo la sezione "Passaggio 9 Pulizia".
Avvia Cloud Shell
Sebbene Google Cloud possa essere utilizzato da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.
Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:
Dovrebbe richiedere solo pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere qualcosa di simile a questo:
Questa macchina virtuale contiene tutti gli strumenti di sviluppo di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione di rete. Tutto il lavoro in questo codelab può essere svolto in un browser. Non devi installare nulla.
A seguire
Ora eseguirai il deployment del cluster Cassandra.
3. Esegui il deployment del cluster Cassandra (Origin)
Per questo codelab, configureremo un cluster Cassandra a un nodo su Compute Engine.
1. Crea una VM GCE per Cassandra
Per creare un'istanza, utilizza il 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. Installa 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 uno spazio chiavi e una tabella
Utilizzeremo un esempio di tabella utenti e creeremo uno spazio chiavi denominato "analytics".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
In 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;
Lascia aperta la sessione SSH o prendi nota dell'indirizzo IP di questa VM (nome host -I).
A seguire
Successivamente, configurerai un'istanza e un database Cloud Spanner.
4. Crea un'istanza e un database Spanner (target)
In Spanner, un'istanza è un cluster di risorse di calcolo e archiviazione che ospita uno o più database Spanner. Per questo codelab, avrai bisogno di almeno un'istanza per ospitare un database Spanner.
Controllare la versione dell'SDK gcloud
Prima di creare un'istanza, assicurati che l'SDK gcloud in Google Cloud Shell sia stato aggiornato alla versione richiesta, ovvero SDK gcloud 493.0.0. Per trovare la versione del tuo SDK gcloud, segui il comando riportato di seguito.
$ gcloud version | grep Google
Ecco un esempio di output:
Google Cloud SDK 489.0.0
Se la versione in uso è precedente alla versione 493.0.0 richiesta (489.0.0 nell'esempio precedente), devi eseguire l'upgrade di Google Cloud SDK eseguendo il seguente 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
Abilita l'API Spanner
In Cloud Shell, assicurati che l'ID progetto sia configurato. Utilizza il primo comando riportato di seguito per trovare l'ID progetto attualmente configurato. Se il risultato non è quello previsto, il secondo comando riportato di seguito imposta quello corretto.
gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]
Configura la regione predefinita su us-central1. Puoi scegliere una regione diversa supportata dalle configurazioni regionali di Spanner.
gcloud config set compute/region us-central1
Abilita l'API Spanner:
gcloud services enable spanner.googleapis.com
Crea l'istanza Spanner
In questa sezione, creerai un'istanza di prova senza costi o un'istanza di cui è stato eseguito il provisioning. In questo codelab, l'ID istanza dell'adattatore Cassandra Spanner utilizzato è cassandra-adapter-demo, impostato come variabile SPANNER_INSTANCE_ID utilizzando la riga di comando export. Se vuoi, puoi scegliere il nome dell'ID istanza.
Creare un'istanza Spanner di prova senza costi
Un'istanza di prova senza costi di Spanner di 90 giorni è disponibile per chiunque abbia un Account Google e abbia attivato la fatturazione Cloud nel proprio progetto. Non ti verrà addebitato alcun importo a meno che tu non scelga di eseguire l'upgrade dell'istanza di prova senza costi a un'istanza a pagamento. L'adattatore Spanner Cassandra è supportato nell'istanza di prova senza costi. Se idoneo, crea un'istanza di prova senza costi aprendo Cloud Shell ed eseguendo questo comando:
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"
Output 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 il database
Una volta avviata l'istanza, puoi creare il database. Il database è il luogo in cui definisci lo schema. Puoi anche controllare chi ha accesso al database, configurare la crittografia personalizzata, configurare l'ottimizzatore e impostare il periodo di conservazione.
Il database verrà creato nell'istanza con ID SPANNER_INSTANCE_ID.
Per creare un database, utilizza lo strumento a riga di comando gcloud:
export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
--instance=$SPANNER_INSTANCE_ID
Output comando:
$ gcloud spanner databases create $SPANNER_DATABASE \ --instance=$SPANNER_INSTANCE_ID Creating database...done.
5. Esegui la migrazione dello schema e del modello di dati di Cassandra a Spanner
La fase iniziale e cruciale del passaggio dei dati da un database Cassandra a Spanner prevede la trasformazione dello schema Cassandra esistente in modo che sia in linea con i requisiti di tipo strutturale e di dati di Spanner.
Per semplificare questo complesso processo di migrazione dello schema, Spanner fornisce uno strumento open source molto utile chiamato Spanner Cassandra schema tool.
Strumento dello schema Cassandra di Spanner
Lo strumento dello schema di Spanner Cassandra è uno strumento open source autonomo per la valutazione e la migrazione dello schema di Spanner. La sua funzione principale è costruire automaticamente uno schema Spanner in base alle definizioni trovate in uno schema Cassandra esistente. Analizzando le strutture delle tabelle Cassandra, i tipi di dati e le configurazioni delle chiavi primarie, lo strumento genera definizioni di tabelle Spanner equivalenti, riducendo notevolmente lo sforzo manuale normalmente necessario per la traduzione dello schema.
Esporta schema Cassandra
Prima di utilizzare lo strumento dello schema Cassandra di Spanner, il primo passaggio concreto consiste nell'estrarre lo schema dall'attuale cluster Cassandra. Per farlo, connettiti al cluster Cassandra esistente tramite cqlsh ed esporta lo schema da Cassandra:
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
In questo comando, [IP] deve essere sostituito con l'indirizzo IP o il nome host di uno dei nodi del cluster Cassandra. La parte -e DESC SCHEMA del comando indica a cqlsh di descrivere l'intero schema del cluster Cassandra. L'output di questo comando, che contiene le istruzioni CREATE KEYSPACE e CREATE TABLE, viene reindirizzato a un file denominato orig_schema.cql.
I contenuti di questo file orig_schema.cql rappresenteranno essenzialmente un progetto di testo dello schema Cassandra. I contenuti del file orig_schema.cql dovrebbero avere il seguente aspetto:
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 il repository
Per utilizzare lo strumento dello schema Cassandra di Spanner, il passaggio successivo consiste nell'ottenere il codice sorgente dello strumento. Questo viene fatto clonando il repository ospitato su GitHub. Clona lo strumento dello schema Cassandra di Spanner da GitHub digitando il seguente comando in Cloud Shell:
git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git
Quindi, passa alla directory "spanner-cassandra-schema-tool" in cui eseguirai il comando.
cd spanner-cassandra-schema-tool
Installa le dipendenze
Lo strumento dello schema Cassandra di Spanner è scritto nel linguaggio di programmazione Go. Per garantire il corretto funzionamento dello strumento, si basa su determinati moduli (librerie) Go esterni. Queste dipendenze devono essere scaricate e gestite prima di poter eseguire lo strumento. Nella directory spanner-cassandra-schema-tool, esegui il seguente comando:
go mod download
Configurare le credenziali Google Cloud
Questo strumento utilizza le credenziali predefinite dell'applicazione (ADC) come origine delle credenziali per la connessione ai database Spanner. Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file della chiave dell'account di servizio.
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
Sostituisci /path/to/your/service-account-file.json con il percorso effettivo del file della chiave dell'account di servizio scaricato. L'impostazione di questa variabile di ambiente garantisce che lo strumento dello schema Cassandra di Spanner possa autenticarsi in modo sicuro con il progetto Google Cloud e l'istanza Spanner.
Utilizzo
Una volta installate le dipendenze e configurate le credenziali di Google Cloud, puoi eseguire lo strumento dello schema Cassandra Spanner per generare lo schema Spanner dal file dello schema Cassandra esportato. Vai alla directory spanner-cassandra-schema-tool nel terminale o in Cloud Shell ed esegui il seguente comando go run:
go run schema_converter.go \
--project $PROJECT_ID \
--instance $SPANNER_INSTANCE_ID \
--database $SPANNER_DATABASE \
--cql orig_schema.cql \
--dry-run
L'esecuzione con l'opzione --dry-run genera solo lo schema. Esamina e perfeziona la mappatura dei tipi di dati e le colonne della chiave primaria generate dallo strumento. Assicurati che i tipi di dati di Spanner rappresentino con precisione l'intervallo, la precisione e la semantica dei tipi di database Cassandra corrispondenti.
Questo strumento mappa i tipi Cassandra ai tipi Spanner come descritto in Tipi di dati Cassandra supportati.
L'output del comando sarà simile al seguente:
.....
[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!
Se vuoi che lo schema venga applicato automaticamente anche a Spanner, devi eseguire il cli senza l'opzione --dry-run.
Verifica nella console Google Cloud che le tabelle e la tabella dei metadati esistano nel database Cloud Spanner.
8. Convalida i dati
[DA FARE]
9. Indirizzare l'applicazione a Spanner (cutover)
Dopo aver convalidato meticolosamente l'accuratezza e l'integrità dei dati dopo la fase di migrazione, il passaggio fondamentale è passare l'attenzione operativa dell'applicazione dal sistema Cassandra precedente al database Google Cloud Spanner appena compilato. Questo periodo di transizione critico è comunemente indicato come "cutover".
La fase di passaggio segna il momento in cui il traffico delle applicazioni in tempo reale viene reindirizzato dal cluster Cassandra originale e collegato direttamente all'infrastruttura Spanner solida e scalabile. Questa transizione dimostra la facilità con cui le applicazioni possono sfruttare la potenza di Spanner, in particolare quando utilizzano l'interfaccia Spanner Cassandra.
Con l'interfaccia Spanner Cassandra, il processo di passaggio è semplificato. Richiede principalmente la configurazione delle applicazioni client per utilizzare il client Cassandra Spanner nativo per tutte le interazioni con i dati. Invece di comunicare con il database Cassandra (di origine), le applicazioni inizieranno a leggere e scrivere i dati direttamente in Spanner (di destinazione) senza problemi. Questo cambiamento fondamentale nella connettività viene in genere ottenuto tramite l'uso di SpannerCqlSessionBuilder, un componente chiave della libreria client Spanner Cassandra che facilita l'instaurazione di connessioni all'istanza Spanner. In questo modo, l'intero flusso di traffico dati dell'applicazione viene reindirizzato a Spanner.
Per le applicazioni Java che utilizzano già la libreria cassandra-java-driver, l'integrazione del client Java Cassandra di Spanner richiede solo piccole modifiche all'inizializzazione di CqlSession.
Ottenere la dipendenza google-cloud-spanner-cassandra
Per iniziare a utilizzare il client Cassandra di Spanner, devi prima incorporare la relativa dipendenza nel progetto. Gli elementi google-cloud-spanner-cassandra vengono pubblicati in Maven Central, con l'ID gruppo com.google.cloud. Aggiungi la seguente nuova dipendenza nella sezione <dependencies> esistente del progetto Java. Ecco un esempio semplificato di come includere la dipendenza 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>
Modificare la configurazione della connessione per connettersi a Spanner
Dopo aver aggiunto la dipendenza necessaria, il passaggio successivo consiste nel modificare la configurazione della connessione per collegarti al database Spanner.
Un'applicazione tipica che interagisce con un cluster Cassandra spesso utilizza codice simile al seguente per stabilire una connessione:
CqlSession session = CqlSession.builder()
.addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
.withLocalDatacenter("datacenter1")
.withAuthCredentials("username", "password")
.build();
Per reindirizzare questa connessione a Spanner, devi modificare la logica di creazione di CqlSession. Invece di utilizzare direttamente il CqlSessionBuilder standard del cassandra-java-driver, utilizzerai il SpannerCqlSession.builder() fornito dal client Cassandra di Spanner. Ecco un esempio pratico di come modificare il codice di connessione:
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();
Se esegui l'inizializzazione di CqlSession utilizzando SpannerCqlSession.builder() e fornisci il valore corretto di databaseUri, la tua applicazione stabilirà una connessione tramite il client Cassandra Spanner al database Spanner di destinazione. Questa modifica fondamentale garantisce che tutte le operazioni di lettura e scrittura successive eseguite dall'applicazione verranno indirizzate e pubblicate da Spanner, completando così il passaggio iniziale. A questo punto, la tua applicazione dovrebbe continuare a funzionare come previsto, ora grazie alla scalabilità e all'affidabilità di Spanner.
Dettagli: come funziona il client Cassandra di Spanner
Il client Cassandra di Spanner agisce come proxy TCP locale, intercettando i byte del protocollo Cassandra non elaborati inviati da un driver o uno strumento client. Quindi, racchiude questi byte insieme ai metadati necessari in messaggi gRPC per la comunicazione con Spanner. Le risposte di Spanner vengono tradotte di nuovo nel formato wire di Cassandra e inviate nuovamente al driver o allo strumento di origine.
Una volta che hai la certezza che Spanner gestisce correttamente tutto il traffico, puoi:
- Interrompi le doppie scritture.
- Esegui il ritiro del cluster Cassandra originale.
10. Pulizia (facoltativa)
Per eseguire le operazioni di pulizia, vai alla sezione Spanner della console Cloud ed elimina l'istanza cassandra-adapter-demo che abbiamo creato nel codelab.
Elimina il database Cassandra (se installato localmente o persistente)
Se hai installato Cassandra al di fuori di una VM Compute Engine creata qui, segui i passaggi appropriati per rimuovere i dati o disinstallare Cassandra.
11. Complimenti!
Passaggi successivi
- Scopri di più su Cloud Spanner.
- Scopri di più sull'interfaccia Cassandra.