Pierwsze kroki z adapterem Spanner Cassandra

Pierwsze kroki z adapterem Spanner Cassandra

Informacje o tym ćwiczeniu (w Codelabs)

subjectOstatnia aktualizacja: maj 21, 2025
account_circleAutorzy: Mayur Kale, Vardhan Thigle

1. Wprowadzenie

Spanner to w pełni zarządzana, globalnie rozproszona usługa bazy danych, którą można skalować w poziomie. Świetnie sprawdza się w przypadku zarówno zadań relacyjnych, jak i nierelacyjnych.

Interfejs Cassandra usługi Spanner pozwala korzystać z w pełni zarządzanej, skalowalnej i wysokiej dostępności infrastruktury Spanner za pomocą znanych narzędzi i składniki Cassandra.

Czego się nauczysz

  • Jak skonfigurować instancję i bazę danych Spanner
  • Jak przekonwertować schemat i model danych Cassandra.
  • Jak wdrożyć i skonfigurować podwójne zapisywanie danych przychodzących.
  • Jak zbiorczo wyeksportować dane historyczne z Cassandra do Spanner.
  • Jak weryfikować dane, aby zapewnić ich integralność podczas migracji.
  • Jak wskazać w aplikacji usługę Spanner zamiast usługi Cassandra.

Czego potrzebujesz

  • projekt Google Cloud połączony z kontem rozliczeniowym.
  • Dostęp do maszyny z zainstalowanym i skonfigurowanym interfejsem wiersza poleceń gcloud lub skorzystaj z Google Cloud Shell.
  • przeglądarkę internetową, taką jak Chrome lub Firefox;

2. Konfiguracja i wymagania

Tworzenie projektu GCP

Zaloguj się w konsoli Google Cloud i utwórz nowy projekt lub użyj istniejącego. Jeśli nie masz jeszcze konta Gmail ani Google Workspace, musisz je utworzyć.

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • Nazwa projektu to wyświetlana nazwa uczestników tego projektu. Jest to ciąg znaków, którego nie używają interfejsy API Google. Zawsze możesz go zaktualizować.
  • Identyfikator projektu jest niepowtarzalny w ramach wszystkich projektów Google Cloud i nie można go zmienić (po ustawieniu). Konsola Cloud automatycznie generuje unikalny ciąg znaków. Zazwyczaj nie ma znaczenia, jaki to ciąg. W większości laboratoriów z kodem musisz podać identyfikator projektu (zazwyczaj oznaczany jako PROJECT_ID). Jeśli nie podoba Ci się wygenerowany identyfikator, możesz wygenerować inny losowy. Możesz też spróbować użyć własnego adresu e-mail, aby sprawdzić, czy jest on dostępny. Po wykonaniu tego kroku nie można go zmienić. Pozostanie on na stałe w ramach projektu.
  • Informacyjnie: istnieje jeszcze 3 wartość, numer projektu, której używają niektóre interfejsy API. Więcej informacji o wszystkich 3 wartościach znajdziesz w dokumentacji.

Konfiguracja płatności

Następnie postępuj zgodnie z instrukcjami dla użytkownika dotyczącymi zarządzania płatnościami i włącz płatności w Cloud Console. Nowi użytkownicy Google Cloud mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD. Aby uniknąć obciążenia po zakończeniu samouczka, możesz zamknąć instancję Spanner na końcu tego samouczka, wykonując instrukcje podane w sekcji „Krok 9. Czyszczenie”.

Uruchamianie Cloud Shell

Google Cloud można obsługiwać zdalnie z laptopa, ale w tym przypadku będziesz korzystać z Google Cloud Shell, czyli środowiska wiersza poleceń działającego w chmurze.

W konsoli Google Cloud kliknij ikonę Cloud Shell na pasku narzędzi w prawym górnym rogu:

55efc1aaa7a4d3ad.png

Uzyskanie dostępu do środowiska i połączenie się z nim powinno zająć tylko kilka chwil. Po jego zakończeniu powinno wyświetlić się coś takiego:

7ffe5cbb04455448.png

Ta maszyna wirtualna zawiera wszystkie potrzebne narzędzia dla programistów. Zawiera stały katalog domowy o pojemności 5 GB i działa w Google Cloud, co znacznie poprawia wydajność sieci i uwierzytelnianie. Wszystkie zadania w tym CodeLab możesz wykonać w przeglądarce. Nie musisz niczego instalować.

Następny krok

Następnie wdrożysz klaster Cassandra.

3. Wdrażanie klastra Cassandra (Origin)

W tym laboratorium konfigurujemy w Compute Engine klaster Cassandra z jednym węzłem.

1. Tworzenie maszyny wirtualnej GCE dla Cassandra

Aby utworzyć instancję, użyj polecenia 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. Instalowanie systemu 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. Tworzenie przestrzeni kluczy i tabeli

Użyjemy przykładowej tabeli users i utworzymy przestrzeń kluczy o nazwie „analytics”.

cd ~/apache-cassandra
bin/cqlsh <your-localhost-ip? 9042  #starts the cql shell

Więcej informacji o 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;

Pozostaw sesję SSH otwartą lub zapisz adres IP tej maszyny wirtualnej (pole nazwa hosta -I).

Następny krok

Następnie skonfigurujesz instancję i bazę danych Cloud Spanner.

4. Tworzenie instancji i bazy danych usługi Spanner (docelowej)

W Spanner instansja to klaster zasobów obliczeniowych i pamięci masowej, który hostuje co najmniej 1 bazę danych Spanner. W tym ćwiczeniu będziesz potrzebować co najmniej 1 instancji do hostowania bazy danych Spanner.

Sprawdzanie wersji pakietu gcloud SDK

Przed utworzeniem instancji sprawdź, czy pakiet SDK gcloud w Google Cloud Shell został zaktualizowany do wymaganej wersji (pakiet SDK gcloud w wersji 493.0.0). Aby sprawdzić wersję pakietu gcloud SDK, uruchom to polecenie.

$ gcloud version | grep Google

Oto przykładowy wynik:

Google Cloud SDK 489.0.0

Jeśli używasz wersji starszej niż wymagana wersja 493.0.0 (489.0.0 w poprzednim przykładzie), musisz uaktualnić pakiet Google Cloud SDK, wykonując ten polecenie:

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

Włączanie interfejsu Spanner API

W Cloud Shell sprawdź, czy identyfikator projektu jest skonfigurowany. Aby znaleźć aktualnie skonfigurowany identyfikator projektu, użyj pierwszego polecenia poniżej. Jeśli nie uzyskasz oczekiwanego wyniku, drugie polecenie poniżej ustawi właściwy.

gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]

Skonfiguruj region domyślny na us-central1. Możesz zmienić ten region na inny obsługiwany przez konfiguracje regionalne Spanner.

gcloud config set compute/region us-central1

Włącz interfejs Spanner API:

gcloud services enable spanner.googleapis.com

Tworzenie instancji usługi Spanner

W tej sekcji utworzysz instancję w wersji próbnej lub zarezerwowaną instancję. W tym laboratorium kodowania używany jest identyfikator instancji adaptera Cassandra Spanner cassandra-adapter-demo, który jest ustawiany jako zmienna SPANNER_INSTANCE_ID za pomocą wiersza poleceń export. Opcjonalnie możesz wybrać własny identyfikator instancji.

Tworzenie instancji usługi Spanner w wersji próbnej

90-dniowy bezpłatny okres próbny Spanner jest dostępny dla każdego, kto ma konto Google i ma włączone Rozliczenia usługi Google Cloud w swoim projekcie. Nie pobierzemy żadnych opłat, dopóki nie przejdziesz z bezpłatnej wersji próbnej na płatną. Adapter Spanner Cassandra jest obsługiwany w przypadku instancji bezpłatnego okresu próbnego. Jeśli to możliwe, utwórz instancję w ramach bezpłatnego okresu próbnego, otwierając Cloud Shell i uruchamiając to polecenie:

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"

Wynik polecenia:

$ gcloud spanner instances create $SPANNER_INSTANCE_ID \
  --config=$SPANNER_REGION \
  --instance-type=free-instance \
  --description="Spanner Cassandra Adapter demo"
Creating instance...done.

Tworzenie bazy danych

Po uruchomieniu instancji możesz utworzyć bazę danych. W bazie danych definiujesz schemat. Możesz też kontrolować, kto ma dostęp do bazy danych, skonfigurować szyfrowanie niestandardowe, skonfigurować optymalizator i ustawić okres przechowywania.

Baza danych zostanie utworzona w instancji o identyfikatorze SPANNER_INSTANCE_ID.

Aby utworzyć bazę danych, użyj narzędzia wiersza poleceń gcloud:

export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID

Dane wyjściowe polecenia:

$ gcloud spanner databases create $SPANNER_DATABASE \
 --instance=$SPANNER_INSTANCE_ID
Creating database...done.

5. Migracja schematu i modelu danych Cassandra do usługi Spanner

Początkowa i kluczowa faza przenoszenia danych z bazy danych Cassandra do Spannera polega na przekształceniu dotychczasowego schematu Cassandra tak, aby był zgodny z wymaganiami strukturalnymi i typów danych Spannera.

Aby uprościć ten złożony proces migracji schematu, usługa Spanner udostępnia przydatne narzędzie open source o nazwie narzędzie do obsługi schematu usługi Spanner Cassandra.

Narzędzie do obsługi schematów Cassandra w Spanner

Narzędzia schematu usługi Spanner Cassandra to samodzielne narzędzie open source do oceny i migracji schematu usługi Spanner. Jego podstawową funkcją jest automatyczne tworzenie schematu Spanner na podstawie definicji znalezionych w istniejącym schemacie Cassandra. Analizując struktury tabel Cassandra, typy danych i konfiguracje kluczy podstawowych, narzędzie generuje równoważne definicje tabeli Spanner, znacznie ograniczając ręczne działania związane z tłumaczeniem schematu.

Eksportowanie schematu Cassandra

Zanim użyjesz narzędzia do obsługi schematów Cassandra w Spanner, musisz wyodrębnić schemat z bieżącego klastra Cassandra. Aby to zrobić, połącz się z istniejącym klastrem Cassandra za pomocą cqlsh i wyeksportuj schemat z Cassandra:

cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql

W tym poleceniu zastąpić [IP] adresem IP lub nazwą hosta jednego z węzłów w klastrze Cassandra. Część -e DESC SCHEMA polecenia instruuje cqlsh, aby opisał cały schemat klastra Cassandra. Dane wyjściowe tego polecenia, które zawierają instrukcje CREATE KEYSPACE i CREATE TABLE, są następnie przekierowywane do pliku o nazwie orig_schema.cql.

Treść tego pliku orig_schema.cql będzie stanowić tekstowy plan schematu Cassandra. Treść pliku orig_schema.cql powinna wyglądać tak:

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';

Klonowanie repozytorium

Aby korzystać z narzędzia do schematów Cassandra w Spanner, musisz najpierw pobrać jego kod źródłowy. Aby to zrobić, klonuj repozytorium hostowane na GitHub. Aby skopiować narzędzie do obsługi schematu Cassandra w Spanner z GitHuba, wpisz w Cloud Shell to polecenie:

git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git

Następnie przejdź do katalogu „spanner-cassandra-schema-tool”, w którym uruchomisz polecenie.

cd spanner-cassandra-schema-tool

Instalowanie zależności

Narzędzie do schematów Cassandra w Spanner jest napisane w języku programowania Go. Aby narzędzie działało prawidłowo, korzysta z pewnych zewnętrznych modułów Go (bibliotek). Zanim uruchomisz narzędzie, musisz pobrać te zależności i nimi zarządzać. W katalogu spanner-cassandra-schema-tool uruchom to polecenie:

go mod download

Konfigurowanie danych uwierzytelniających Google Cloud

To narzędzie używa domyślnych danych logowania aplikacji (ADC) jako źródła danych logowania do łączenia się z bazami danych Spanner. Ustaw zmienną środowiskową GOOGLE_APPLICATION_CREDENTIALS na ścieżkę do pliku klucza konta usługi.

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

Zastąp /path/to/your/service-account-file.json rzeczywistą ścieżką do pobranego pliku klucza konta usługi. Ustawienie tej zmiennej środowiskowej zapewnia, że narzędzie do obsługi schematu Spanner Cassandra może bezpiecznie uwierzytelniać się w Twoim projekcie Google Cloud i instancji Spanner.

Wykorzystanie

Po zainstalowaniu zależności i skonfigurowaniu danych logowania do Google Cloud możesz uruchomić narzędzie do schematu Spanner Cassandra, aby wygenerować schemat Spanner na podstawie wyeksportowanego pliku schematu Cassandra. Przejdź do katalogu spanner-cassandra-schema-tool w terminalu lub Cloud Shell i wykonaj to polecenie go run:

go run schema_converter.go \
    --project $PROJECT_ID \
    --instance $SPANNER_INSTANCE_ID \
    --database $SPANNER_DATABASE \
    --cql orig_schema.cql \
    --dry-run

Uruchomienie z opcją --dry-run powoduje tylko wygenerowanie schematu. Sprawdź i udoskonal mapowanie typów danych oraz kolumny klucza głównego wygenerowane przez narzędzie. Upewnij się, że typy danych Spanner dokładnie odzwierciedlają zakres, precyzję i semantykę odpowiednich typów baz danych Cassandra.

To narzędzie mapuje typy Cassandra na typy Spanner zgodnie z dokumentacją Obsługiwane typy danych Cassandra.

Dane wyjściowe polecenia będą wyglądać mniej więcej tak:

.....

[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!

Jeśli chcesz, aby schemat został automatycznie zastosowany do Spanner, uruchom interfejs wiersza poleceń bez opcji --dry-run.

7B2FCQSrtHfveuc.png

W konsoli Google Cloud sprawdź, czy tabele i tabela metadanych są dostępne w bazie danych Cloud Spanner.

9. Wskazanie aplikacji do usługi Spanner (przejście)

Po dokładnym sprawdzeniu dokładności i zgodności danych po zakończeniu migracji kluczowym krokiem jest przeniesienie punktu ciężkości działania aplikacji z dotychczasowego systemu Cassandra do nowo wypełnionej bazy danych Google Cloud Spanner. Ten kluczowy okres przejściowy jest powszechnie nazywany przejściem.

Faza przejścia to moment, w którym ruch w produkcyjnej aplikacji jest przekierowywany z pierwotnego klastra Cassandra do niezawodnej i skalowalnej infrastruktury Spanner. Ten proces pokazuje, jak łatwo aplikacje mogą korzystać z możliwości usługi Spanner, zwłaszcza przy użyciu interfejsu Spanner Cassandra.

Dzięki interfejsowi Spanner Cassandra proces przełączania jest uproszczony. Polega to przede wszystkim na skonfigurowaniu aplikacji klienckich tak, aby korzystały z natywnego klienta Cassandra usługi Spanner do wszystkich interakcji z danymi. Zamiast komunikować się z bazą danych Cassandra (źródłową), aplikacje zaczną bezproblemowo odczytywać i zapisywać dane bezpośrednio w bazie danych Spanner (docelowej). Ten fundamentalny krok w zakresie łączności jest zwykle osiągany dzięki użyciu SpannerCqlSessionBuilder, kluczowego komponentu biblioteki klienta Cassandra w Spanner, który ułatwia nawiązywanie połączeń z instancją Spanner. Dzięki temu cały ruch danych aplikacji zostanie przekierowany do usługi Spanner.

W przypadku aplikacji w języku Java, które korzystają już z biblioteki cassandra-java-driver, integracja klienta Spanner Cassandra w języku Java wymaga tylko niewielkich zmian w inicjalizacji CqlSession.

Uzyskiwanie zależności google-cloud-spanner-cassandra

Aby zacząć korzystać z klienta Cassandra Spanner, musisz najpierw uwzględnić jego zależność w projekcie. Elementy google-cloud-spanner-cassandra są publikowane w Maven Central pod identyfikatorem grupy com.google.cloud. Dodaj nową zależność w sekcji <dependencies> w projekcie Java. Oto uproszczony przykład uwzględniania zależności 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>

Zmień konfigurację połączenia, aby połączyć się z usługą Spanner

Po dodaniu niezbędnych zależności musisz zmienić konfigurację połączenia, aby połączyć się z bazą danych Spanner.

Typowa aplikacja, która wchodzi w interakcję z klastrze Cassandra, często używa kodu podobnego do tego, aby nawiązać połączenie:

CqlSession session = CqlSession.builder()
       
.addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
       
.withLocalDatacenter("datacenter1")
       
.withAuthCredentials("username", "password")
       
.build();

Aby przekierować to połączenie do Spanner, musisz zmodyfikować logikę tworzenia CqlSession. Zamiast bezpośrednio używać standardowej funkcji CqlSessionBuilder z poziomu usługi cassandra-java-driver, będziesz używać funkcji SpannerCqlSession.builder() udostępnianej przez klienta Cassandra w Spanner. Oto przykładowy przykład modyfikowania kodu połączenia:

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();

Po uruchomieniu obiektu CqlSession za pomocą funkcji SpannerCqlSession.builder() i podaniu prawidłowej wartości databaseUri Twoja aplikacja nawiąże połączenie za pomocą klienta Cassandra Spanner z docelową bazą danych Spanner. Ta kluczowa zmiana zapewnia, że wszystkie kolejne operacje odczytu i zapisu wykonywane przez aplikację będą kierowane do usługi Spanner i przez nią obsługiwane, co pozwoli na skuteczne zakończenie początkowego przejścia. W tym momencie Twoja aplikacja powinna działać zgodnie z oczekiwaniami, korzystając z funkcji skalowalności i niezawodności usługi Spanner.

Pod maską: jak działa klient Cassandra w Spanner

Klient Cassandra w Spanner działa jako lokalny serwer pośredniczący TCP, przechwytując bajty nieprzetworzone protokołu Cassandra wysyłane przez sterownik lub narzędzie klienta. Następnie owija te bajty wraz z niezbędnymi metadanymi w wiadomościach gRPC do komunikacji z usługą Spanner. Odpowiedzi z Spanner są przekształcane z powrotem do formatu przesyłania danych w usłudze Cassandra i wysyłane z powrotem do pierwotnego interfejsu sterującego lub narzędzia.

26D34akkBHcMFFe.png

Gdy będziesz mieć pewność, że usługa Spanner wyświetla cały ruch, możesz:

  • Zatrzymaj podwójny zapis.
  • wycofać pierwotny klaster Cassandra.

10. Czyszczenie (opcjonalne)

Aby to zrobić, otwórz sekcję Spanner w konsoli Cloud i usuń instancję cassandra-adapter-demo utworzoną w ramach tego ćwiczenia.

76D34akkJRcMFMr.png

usunąć bazę danych Cassandra (jeśli jest zainstalowana lokalnie lub utrwalona);

Jeśli zainstalowałeś/zainstalowałaś Cassandra poza maszyną wirtualną Compute Engine utworzoną tutaj, wykonaj odpowiednie czynności, aby usunąć dane lub odinstalować Cassandra.

11. Gratulacje!

Co dalej?