Tentang codelab ini
1. Pengantar
Spanner adalah layanan database skalabel dan terkelola sepenuhnya secara global yang sangat cocok untuk workload relasional dan non-relasional.
Antarmuka Cassandra Spanner memungkinkan Anda memanfaatkan infrastruktur Spanner yang terkelola sepenuhnya, skalabel, dan sangat tersedia menggunakan alat dan sintaksis Cassandra yang sudah dikenal.
Yang akan Anda pelajari
- Cara menyiapkan instance dan database Spanner.
- Cara mengonversi skema dan model data Cassandra.
- Cara men-deploy dan mengonfigurasi penulisan ganda untuk data yang masuk.
- Cara mengekspor data historis Anda secara massal dari Cassandra ke Spanner.
- Cara memvalidasi data untuk memastikan integritas data selama proses migrasi.
- Cara mengarahkan aplikasi ke Spanner, bukan Cassandra.
Yang Anda butuhkan
- Project Google Cloud yang terhubung ke akun penagihan.
- Akses ke komputer dengan CLI
gcloudyang diinstal dan dikonfigurasi, atau gunakan Google Cloud Shell. - Browser web, seperti Chrome atau Firefox.
2. Penyiapan dan persyaratan
Membuat project GCP
Login ke Google Cloud Console dan buat project baru atau gunakan kembali project yang sudah ada. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.
- Project name adalah nama tampilan untuk peserta project ini. String ini adalah string karakter yang tidak digunakan oleh Google API. Anda dapat memperbaruinya kapan saja.
- Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Cloud Console otomatis membuat string unik; biasanya Anda tidak mementingkan kata-katanya. Di sebagian besar codelab, Anda harus merujuk Project ID-nya (umumnya diidentifikasi sebagai
PROJECT_ID). Jika tidak suka dengan ID yang dibuat, Anda dapat membuat ID acak lainnya. Atau, Anda dapat mencobanya sendiri, dan lihat apakah ID tersebut tersedia. ID tidak dapat diubah setelah langkah ini dan tersedia selama durasi project. - Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.
Konfigurasi penagihan
Selanjutnya, Anda harus mengikuti panduan pengguna pengelolaan penagihan dan mengaktifkan penagihan di Cloud Console. Pengguna baru Google Cloud memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD. Agar tidak dikenai biaya setelah mengikuti tutorial ini, Anda dapat menonaktifkan instance Spanner di akhir codelab dengan mengikuti "Langkah 9 Pembersihan".
Mulai Cloud Shell
Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.
Dari Google Cloud Console, klik ikon Cloud Shell di toolbar kanan atas:
Hanya perlu waktu beberapa saat untuk penyediaan dan terhubung ke lingkungan. Jika sudah selesai, Anda akan melihat tampilan seperti ini:
Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.
Berikutnya
Selanjutnya, Anda akan men-deploy cluster Cassandra.
3. Men-deploy cluster Cassandra (Asal)
Untuk codelab ini, kita akan menyiapkan cluster Cassandra satu node di Compute Engine.
1. Membuat VM GCE untuk Cassandra
Untuk membuat instance, gunakan perintah 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. Menginstal 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. Membuat ruang kunci dan tabel
Kita akan menggunakan contoh tabel pengguna dan membuat ruang kunci yang disebut "analytics".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
Di dalam 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;
Biarkan sesi SSH tetap terbuka atau catat alamat IP VM ini (nama host -I).
Berikutnya
Selanjutnya, Anda akan menyiapkan Instance dan Database Cloud Spanner.
4. Membuat instance dan database Spanner (Target)
Di Spanner, instance adalah cluster resource komputasi dan penyimpanan yang menghosting satu atau beberapa database Spanner. Anda memerlukan minimal 1 instance untuk menghosting database Spanner untuk codelab ini.
Memeriksa versi gcloud SDK
Sebelum membuat instance, pastikan gcloud SDK di Google Cloud Shell telah diupdate ke versi yang diperlukan - gcloud SDK 493.0.0. Anda dapat menemukan versi gcloud SDK dengan mengikuti perintah di bawah.
$ gcloud version | grep Google
Berikut adalah contoh output:
Google Cloud SDK 489.0.0
Jika versi yang Anda gunakan lebih lama dari versi 493.0.0 yang diperlukan (489.0.0 dalam contoh sebelumnya), Anda harus mengupgrade Google Cloud SDK dengan menjalankan perintah berikut:
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
Mengaktifkan Spanner API
Di dalam Cloud Shell, pastikan project ID Anda sudah disiapkan. Gunakan perintah pertama di bawah untuk menemukan project ID yang saat ini dikonfigurasi. Jika hasilnya tidak diharapkan, perintah kedua di bawah akan menetapkan hasil yang benar.
gcloud config get-value project
gcloud config set project [YOUR-DESIRED-PROJECT-ID]
Konfigurasikan region default Anda ke us-central1. Anda dapat mengubahnya ke wilayah lain yang didukung oleh konfigurasi regional Spanner.
gcloud config set compute/region us-central1
Aktifkan Spanner API:
gcloud services enable spanner.googleapis.com
Membuat instance Spanner
Di bagian ini, Anda akan membuat instance uji coba gratis atau instance yang disediakan. Di seluruh codelab ini, ID Instance Adaptor Cassandra Spanner yang digunakan adalah cassandra-adapter-demo, yang ditetapkan sebagai variabel SPANNER_INSTANCE_ID menggunakan command line export. Secara opsional, Anda dapat memilih nama ID instance Anda sendiri.
Membuat instance Spanner uji coba gratis
Instance uji coba gratis Spanner selama 90 hari tersedia bagi siapa saja yang memiliki Akun Google dan telah mengaktifkan Penagihan Cloud di project mereka. Anda tidak akan ditagih kecuali jika memilih untuk mengupgrade instance uji coba gratis ke instance berbayar. Spanner Cassandra Adapter didukung di instance uji coba gratis. Jika memenuhi syarat, buat instance uji coba gratis dengan membuka Cloud Shell dan menjalankan perintah ini:
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 perintah:
$ gcloud spanner instances create $SPANNER_INSTANCE_ID \ --config=$SPANNER_REGION \ --instance-type=free-instance \ --description="Spanner Cassandra Adapter demo" Creating instance...done.
Membuat database
Setelah instance berjalan, Anda dapat membuat database. Database adalah tempat Anda menentukan skema. Anda juga dapat mengontrol siapa yang memiliki akses ke database, menyiapkan enkripsi kustom, mengonfigurasi pengoptimal, dan menetapkan periode retensi.
Database akan dibuat di instance dengan ID SPANNER_INSTANCE_ID.
Untuk membuat database, gunakan alat command line gcloud:
export SPANNER_DATABASE=analytics
gcloud spanner databases create $SPANNER_DATABASE \
--instance=$SPANNER_INSTANCE_ID
Output perintah:
$ gcloud spanner databases create $SPANNER_DATABASE \ --instance=$SPANNER_INSTANCE_ID Creating database...done.
5. Memigrasikan Skema Cassandra dan model data ke Spanner
Fase awal dan penting dalam mentransisikan data dari database Cassandra ke Spanner melibatkan transformasi skema Cassandra yang ada agar selaras dengan persyaratan struktural dan jenis data Spanner.
Untuk menyederhanakan proses migrasi skema yang kompleks ini, Spanner menyediakan alat open source yang berharga yang dikenal sebagai alat skema Spanner Cassandra.
Alat skema Cassandra Spanner
Alat skema Cassandra Spanner adalah alat open source mandiri untuk evaluasi Spanner dan migrasi skema. Fungsi utamanya adalah membuat skema Spanner secara otomatis berdasarkan definisi yang ditemukan dalam skema Cassandra yang ada. Dengan menganalisis struktur tabel, jenis data, dan konfigurasi kunci utama Cassandra, alat ini menghasilkan definisi tabel Spanner yang setara, sehingga secara signifikan mengurangi upaya manual yang biasanya terlibat dalam terjemahan skema.
Mengekspor skema Cassandra
Sebelum menggunakan alat skema Cassandra Spanner, langkah konkret pertama adalah mengekstrak skema dari cluster Cassandra Anda saat ini. Hal ini dapat dilakukan dengan menghubungkan ke cluster Cassandra yang ada melalui cqlsh, dan mengekspor skema dari Cassandra:
cqlsh [IP] "-e DESC SCHEMA" > orig_schema.cql
Dalam perintah ini, [IP] harus diganti dengan alamat IP atau nama host salah satu node di cluster Cassandra Anda. Bagian -e DESC SCHEMA dari perintah ini menginstruksikan cqlsh untuk mendeskripsikan seluruh skema cluster Cassandra. Output perintah ini, yang berisi pernyataan CREATE KEYSPACE dan CREATE TABLE, kemudian dialihkan ke file bernama orig_schema.cql.
Konten file orig_schema.cql ini pada dasarnya akan mewakili blueprint tekstual skema Cassandra Anda. Konten file orig_schema.cql akan terlihat seperti ini:
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';
Membuat Clone Repositori
Untuk menggunakan alat skema Spanner Cassandra, langkah berikutnya adalah mendapatkan kode sumber alat. Hal ini dilakukan dengan meng-clone repositori yang dihosting di GitHub. Clone alat skema Spanner Cassandra dari GitHub dengan mengetik perintah berikut di Cloud Shell:
git clone https://github.com/cloudspannerecosystem/spanner-cassandra-schema-tool.git
Kemudian, ubah direktori ke direktori "spanner-cassandra-schema-tool" tempat Anda akan menjalankan perintah.
cd spanner-cassandra-schema-tool
Menginstal Dependensi
Alat skema Spanner Cassandra ditulis dalam bahasa pemrograman Go. Untuk memastikan alat berfungsi dengan benar, alat ini mengandalkan modul Go (library) eksternal tertentu. Dependensi ini perlu didownload dan dikelola sebelum Anda dapat menjalankan alat. Dalam direktori spanner-cassandra-schema-tool, jalankan perintah berikut:
go mod download
Menyiapkan Kredensial Google Cloud
Alat ini menggunakan Kredensial Default Aplikasi (ADC) sebagai sumber kredensial untuk terhubung ke database Spanner. Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file kunci akun layanan Anda.
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
Ganti /path/to/your/service-account-file.json dengan jalur sebenarnya ke file kunci akun layanan yang Anda download. Menetapkan variabel lingkungan ini memastikan bahwa alat skema Spanner Cassandra dapat melakukan autentikasi dengan aman ke project Google Cloud dan instance Spanner Anda.
Penggunaan
Setelah dependensi diinstal dan kredensial Google Cloud dikonfigurasi, Anda siap menjalankan alat skema Spanner Cassandra untuk membuat skema Spanner dari file skema Cassandra yang diekspor. Buka direktori spanner-cassandra-schema-tool di terminal atau Cloud Shell Anda, lalu jalankan perintah go run berikut:
go run schema_converter.go \
--project $PROJECT_ID \
--instance $SPANNER_INSTANCE_ID \
--database $SPANNER_DATABASE \
--cql orig_schema.cql \
--dry-run
Menjalankan dengan opsi --dry-run hanya akan membuat skema. Tinjau dan tingkatkan pemetaan jenis data dan kolom kunci utama yang dihasilkan oleh alat. Pastikan jenis data Spanner secara akurat merepresentasikan rentang, presisi, dan semantik jenis database Cassandra yang sesuai.
Alat ini memetakan jenis Cassandra ke jenis Spanner seperti yang didokumentasikan dalam Jenis data Cassandra yang didukung.
Output perintah akan terlihat seperti ini:
.....
[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!
Jika Anda juga ingin skema penerapan diterapkan secara otomatis ke Spanner, Anda harus menjalankan CLI tanpa opsi --dry-run.
Verifikasi di Konsol Google Cloud bahwa tabel dan tabel metadata ada di database Cloud Spanner.
8. Memvalidasi data Anda
[TODO]
9. Mengarahkan aplikasi ke Spanner (Migrasi Sistem)
Setelah memvalidasi akurasi dan integritas data Anda dengan cermat setelah fase migrasi, langkah penting yang harus dilakukan adalah mentransisikan fokus operasional aplikasi Anda dari sistem Cassandra lama ke database Google Cloud Spanner yang baru diisi. Periode transisi penting ini biasanya disebut sebagai "cutover".
Fase peralihan menandai momen saat traffic aplikasi aktif dialihkan dari cluster Cassandra asli dan terhubung langsung ke infrastruktur Spanner yang andal dan skalabel. Transisi ini menunjukkan kemudahan aplikasi dalam memanfaatkan kecanggihan Spanner, terutama saat menggunakan antarmuka Spanner Cassandra.
Dengan antarmuka Spanner Cassandra, proses peralihan akan disederhanakan. Hal ini terutama melibatkan konfigurasi aplikasi klien Anda untuk menggunakan Klien Cassandra Spanner native untuk semua interaksi data. Aplikasi Anda akan mulai membaca dan menulis data secara langsung ke Spanner (target) tanpa berkomunikasi dengan database Cassandra (asal). Perubahan fundamental dalam konektivitas ini biasanya dicapai melalui penggunaan SpannerCqlSessionBuilder, komponen utama library Klien Cassandra Spanner yang memfasilitasi pembuatan koneksi ke instance Spanner Anda. Tindakan ini secara efektif mengalihkan seluruh alur traffic data aplikasi Anda ke Spanner.
Untuk aplikasi Java yang sudah menggunakan library cassandra-java-driver, mengintegrasikan Klien Java Spanner Cassandra hanya memerlukan perubahan kecil pada inisialisasi CqlSession.
Mendapatkan dependensi google-cloud-spanner-cassandra
Untuk mulai menggunakan Spanner Cassandra Client, Anda harus menggabungkan dependensinya ke dalam project terlebih dahulu. Artefak google-cloud-spanner-cassandra dipublikasikan di Maven Central, dengan ID grup com.google.cloud. Tambahkan dependensi baru berikut di bagian <dependencies> yang ada di project Java Anda. Berikut adalah contoh sederhana tentang cara menyertakan dependensi 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>
Mengubah konfigurasi koneksi untuk terhubung ke Spanner
Setelah menambahkan dependensi yang diperlukan, langkah berikutnya adalah mengubah konfigurasi koneksi untuk terhubung ke database Spanner.
Aplikasi standar yang berinteraksi dengan cluster Cassandra sering kali menggunakan kode yang mirip dengan kode berikut untuk membuat koneksi:
CqlSession session = CqlSession.builder()
.addContactPoint(new InetSocketAddress("127.0.0.1", 9042))
.withLocalDatacenter("datacenter1")
.withAuthCredentials("username", "password")
.build();
Untuk mengalihkan koneksi ini ke Spanner, Anda perlu mengubah logika pembuatan CqlSession. Daripada menggunakan CqlSessionBuilder standar dari cassandra-java-driver secara langsung, Anda akan menggunakan SpannerCqlSession.builder() yang disediakan oleh Klien Cassandra Spanner. Berikut adalah contoh ilustrasi cara mengubah kode koneksi Anda:
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();
Dengan membuat instance CqlSession menggunakan SpannerCqlSession.builder() dan memberikan databaseUri yang benar, aplikasi Anda kini akan membuat koneksi melalui Klien Cassandra Spanner ke database Spanner target Anda. Perubahan penting ini memastikan bahwa semua operasi baca dan tulis berikutnya yang dilakukan oleh aplikasi Anda akan diarahkan ke dan ditayangkan oleh Spanner, sehingga menyelesaikan peralihan awal secara efektif. Pada tahap ini, aplikasi Anda akan terus berfungsi seperti yang diharapkan, yang kini didukung oleh skalabilitas dan keandalan Spanner.
Di Balik Layar: Cara Kerja Klien Cassandra Spanner
Klien Spanner Cassandra bertindak sebagai proxy tcp lokal, yang mencegat byte protokol Cassandra mentah yang dikirim oleh driver atau alat klien. Kemudian, byte ini digabungkan bersama metadata yang diperlukan ke dalam pesan gRPC untuk komunikasi dengan Spanner. Respons dari Spanner diterjemahkan kembali ke dalam format wire Cassandra dan dikirim kembali ke driver atau alat asal.
Setelah yakin bahwa Spanner menayangkan semua traffic dengan benar, Anda pada akhirnya dapat:
- Menghentikan penulisan ganda.
- Nonaktifkan cluster Cassandra asli.
10. Pembersihan (opsional)
Untuk membersihkan, cukup buka bagian Spanner di Cloud Console dan hapus instance cassandra-adapter-demo yang kita buat di codelab.
Menghapus database Cassandra (jika diinstal secara lokal atau dipertahankan)
Jika Anda menginstal Cassandra di luar VM Compute Engine yang dibuat di sini, ikuti langkah-langkah yang sesuai untuk menghapus data atau meng-uninstal Cassandra.
11. Selamat!
Apa langkah selanjutnya?
- Pelajari Cloud Spanner lebih lanjut.
- Pelajari Antarmuka Cassandra lebih lanjut.