Tentang codelab ini
1. Pengantar
Bigtable adalah layanan database NoSQL berperforma tinggi yang terkelola sepenuhnya dan dirancang untuk workload analisis dan operasional yang besar. Memigrasikan dari database yang ada seperti Apache Cassandra ke Bigtable sering kali memerlukan perencanaan yang cermat untuk meminimalkan periode nonaktif dan dampak aplikasi.
Codelab ini menunjukkan strategi migrasi dari Cassandra ke Bigtable menggunakan kombinasi alat proxy:
- Cassandra-Bigtable Proxy: Memungkinkan klien dan alat Cassandra (seperti
cqlshatau driver) berinteraksi dengan Bigtable menggunakan protokol Cassandra Query Language (CQL) dengan menerjemahkan kueri. - Proxy Migrasi Tanpa Periode Nonaktif (ZDM) Datastax: Proxy open source yang berada di antara aplikasi dan layanan database Anda (Cassandra asal dan Bigtable target melalui Proxy Cassandra-Bigtable). Layanan ini mengatur penulisan ganda dan mengelola pemilihan rute traffic, sehingga memungkinkan migrasi dengan perubahan aplikasi dan periode nonaktif minimal.
- Cassandra Data Migrator (CDM): Alat open source yang digunakan untuk memigrasikan data historis secara massal dari cluster Cassandra sumber ke instance Bigtable target.
Yang akan Anda pelajari
- Cara menyiapkan cluster Cassandra dasar di Compute Engine.
- Cara membuat instance Bigtable.
- Cara men-deploy dan mengonfigurasi Cassandra-Bigtable Proxy untuk memetakan skema Cassandra ke Bigtable.
- Cara men-deploy dan mengonfigurasi Proxy ZDM Datastax untuk penulisan ganda.
- Cara menggunakan alat Cassandra Data Migrator untuk memigrasikan data yang ada secara massal.
- Alur kerja keseluruhan untuk migrasi Cassandra ke Bigtable berbasis proxy.
Yang Anda butuhkan
- Project Google Cloud yang mengaktifkan penagihan. Pengguna baru memenuhi syarat untuk mendapatkan uji coba gratis.
- Pemahaman dasar tentang konsep Google Cloud seperti project, Compute Engine, jaringan VPC, dan aturan firewall. Pemahaman dasar tentang alat command line Linux.
- Akses ke komputer dengan CLI
gcloudyang diinstal dan dikonfigurasi, atau gunakan Google Cloud Shell.
Untuk codelab ini, kita akan menggunakan virtual machine (VM) di Compute Engine dalam jaringan dan region VPC yang sama untuk menyederhanakan jaringan. Sebaiknya gunakan alamat IP internal.
2. Menyiapkan lingkungan Anda
1. Memilih atau membuat Project Google Cloud
Buka Konsol Google Cloud dan pilih project yang sudah ada atau buat project baru. Catat Project ID Anda.
2. Mengaktifkan API yang diperlukan
Pastikan Compute Engine API dan Bigtable API diaktifkan untuk project Anda.
gcloud services enable compute.googleapis.com bigtable.googleapis.com bigtableadmin.googleapis.com --project=<your-project-id>
Ganti dengan project ID Anda yang sebenarnya.
3. Memilih region dan zona
Pilih region dan zona untuk resource Anda. Kita akan menggunakan us-central1 dan us-central1-c sebagai contoh. Tentukan ini sebagai variabel lingkungan untuk memudahkan:
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. Mengonfigurasi aturan firewall
Kita perlu mengizinkan komunikasi antar-VM dalam jaringan VPC default di beberapa port:
- Port CQL Cassandra/Proxy: 9042
- Port Health Check Proxy ZDM: 14001
- SSH: 22
Buat aturan firewall untuk mengizinkan traffic internal di port ini. Kita akan menggunakan tag cassandra-migration untuk menerapkan aturan ini dengan mudah ke VM yang relevan.
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. Men-deploy cluster Cassandra (Asal)
Untuk codelab ini, kita akan menyiapkan cluster Cassandra satu node sederhana di Compute Engine. Dalam skenario dunia nyata, Anda akan terhubung ke cluster yang ada.
1. Membuat VM GCE untuk 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. 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 karyawan dan membuat ruang kunci yang disebut "zdmbigtable".
cd ~/apache-cassandra bin/cqlsh <your-localhost-ip? 9042 #starts the cql shell
Di dalam 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;
Biarkan sesi SSH tetap terbuka atau catat alamat IP VM ini (hostname -I).
4. Menyiapkan Bigtable (Target)
Durasi 0:01
Buat instance Bigtable. Kita akan menggunakan zdmbigtable sebagai ID 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
Tabel Bigtable itu sendiri akan dibuat nanti oleh skrip penyiapan Proxy Cassandra-Bigtable.
5. Menyiapkan Proxy Cassandra-Bigtable
1. Membuat VM Compute Engine untuk 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
Gunakan SSH untuk terhubung ke bigtable-proxy-vm:
gcloud compute ssh bigtable-proxy-vm
Di dalam 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. Mengonfigurasi proxy
nano config.yaml
Perbarui variabel berikut. Untuk konfigurasi lanjutan lainnya, gunakan contoh ini yang disediakan di 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
Simpan dan tutup file (ctrl+X, lalu Y, lalu Enter di nano).
3. Memulai Proxy Cassandra-Bigtable
Mulai server proxy.
# At the root of the cassandra-to-bigtable-proxy directory go run proxy.go
Proxy akan dimulai dan memproses di port 9042 untuk koneksi CQL yang masuk. Biarkan sesi terminal ini tetap berjalan. Catat alamat IP VM ini (hostname -I)
4. Membuat Tabel melalui CQL
Hubungkan cqlsh ke alamat IP VM Proxy Cassandra-Bigtable.
Di cqlsh, jalankan perintah berikut
-- 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
);
Pastikan di Konsol Google Cloud bahwa tabel karyawan dan tabel metadata ada di instance Bigtable Anda.
6. Menyiapkan Proxy ZDM
Proxy ZDM memerlukan minimal dua mesin: satu atau beberapa node proxy yang menangani traffic, dan "Jumphost" yang digunakan untuk deployment dan orkestrasi melalui Ansible.
1. Membuat VM Compute Engine untuk Proxy ZDM
Kita memerlukan dua VM: zdm-proxy-jumphost dan 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
Catat alamat IP kedua VM.
2. Menyiapkan jumphost
SSH ke zdm-jumphost
gcloud compute ssh zdm-jumphost
# Install Git and Ansible
sudo apt-get update
sudo apt-get install -y git ansible
Di dalam jumphost
git clone https:\/\/github.com/datastax/zdm-proxy-automation.git
cd zdm-proxy-automation/ansible/
Edit file konfigurasi utama vars/zdm_proxy_cluster_config.yml:
Perbarui origin_contact_points dan target_contact_points dengan alamat IP internal VM Cassandra dan VM Proxy Cassandra-Bigtable. Biarkan autentikasi dikomentari karena kita tidak menyiapkannya.
##############################
#### 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)
Simpan dan tutup file ini.
3. Men-deploy Proxy ZDM menggunakan Ansible
Jalankan playbook Ansible dari direktori ansible di jumphost:
ansible-playbook deploy_zdm_proxy.yml -i zdm_ansible_inventory
Perintah ini akan menginstal software yang diperlukan (seperti Docker) di node proxy (zdm-proxy-node-1), mengambil image Docker Proxy ZDM, dan memulai penampung proxy dengan konfigurasi yang Anda berikan.
4. Memverifikasi kondisi Proxy ZDM
Periksa endpoint kesiapan proxy ZDM yang berjalan di zdm-proxy-node-1 (port 14001) dari 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
Anda akan melihat output yang mirip dengan ini, yang menunjukkan bahwa Origin (Cassandra) dan Target (Cassandra-Bigtable Proxy) AKTIF:
{
"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. Mengonfigurasi aplikasi & memulai penulisan ganda
Durasi 0:05
Pada tahap ini dalam migrasi yang sebenarnya, Anda akan mengonfigurasi ulang aplikasi untuk mengarah ke alamat IP node ZDM Proxy (misalnya, :9042) alih-alih terhubung langsung ke Cassandra.
Setelah aplikasi terhubung ke Proxy ZDM: Operasi baca ditayangkan dari Origin (Cassandra) secara default. Operasi tulis dikirim ke Origin (Cassandra) dan Target (Bigtable, melalui Cassandra-Bigtable Proxy). Hal ini memungkinkan aplikasi Anda terus berfungsi secara normal sekaligus memastikan data baru ditulis ke kedua database secara bersamaan. Anda dapat menguji koneksi menggunakan cqlsh yang mengarah ke Proxy ZDM dari jumphost atau VM lain di jaringan:
Cqlsh <zdm-proxy-node-1-ip-address> 9042
Coba sisipkan beberapa data:
INSERT INTO zdmbigtable.employee (name, age, is_active) VALUES ('Alice', 30, true);
SELECT * FROM employee WHERE name = 'Alice';
Data ini harus ditulis ke Cassandra dan Bigtable. Anda dapat mengonfirmasi hal ini di Bigtable, dengan membuka Konsol Google Cloud dan membuka Bigtable Query Editor untuk instance Anda. Jalankan kueri "SELECT * FROM employee", dan data yang baru saja disisipkan akan terlihat.
8. Memigrasikan data historis menggunakan Cassandra Data Migrator
Setelah penulisan ganda aktif untuk data baru, gunakan alat Cassandra Data Migrator (CDM) untuk menyalin data historis yang ada dari Cassandra ke Bigtable.
1. Membuat VM Compute Engine untuk CDM
VM ini memerlukan memori yang cukup untuk 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. Menginstal prasyarat (Java 11, Spark)
Gunakan SSH untuk terhubung ke cdm-migrator-vm:
gcloud compute ssh cdm-migrator-vm
Di dalam 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. Mendownload Cassandra Data Migrator
Download file jar alat CDM. Periksa halaman Rilis GitHub Cassandra Data Migrator untuk mengetahui URL versi yang diinginkan yang benar.
# 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. Mengonfigurasi CDM
Buat file properti bernama cdm.properties
Nano cdm.properties
Tempelkan konfigurasi berikut, ganti alamat IP dan nonaktifkan fitur TTL/Writetime karena tidak didukung secara langsung oleh Bigtable dengan cara yang sama. Biarkan autentikasi dikomentari.
# 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
Simpan dan tutup file tersebut.
5. Menjalankan tugas migrasi
Jalankan migrasi menggunakan spark-submit. Perintah ini memberi tahu Spark untuk menjalankan jar CDM, menggunakan file properti Anda dan menentukan keyspace dan tabel yang akan dimigrasikan. Sesuaikan setelan memori (–driver-memory, –executor-memory) berdasarkan ukuran VM dan volume data Anda.
Pastikan Anda berada di direktori yang berisi file properti dan jar CDM. Ganti 'cassandra-data-migrator-5.2.2.jar' jika Anda mendownload versi yang berbeda.
./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
Migrasi akan berjalan di latar belakang, dan log akan ditulis ke cdm_migration_... .log. Pantau file log untuk mengetahui progres dan error apa pun:
tail -f cdm_migration_*.log
6. Memverifikasi migrasi data
Setelah tugas CDM berhasil diselesaikan, pastikan data historis ada di Bigtable. Karena Proxy Cassandra-Bigtable mengizinkan pembacaan CQL, Anda dapat kembali menggunakan cqlsh yang terhubung ke Proxy ZDM (yang merutekan pembacaan ke Target setelah migrasi, atau dapat dikonfigurasi ke) atau langsung ke Proxy Cassandra-Bigtable untuk membuat kueri data. Menghubungkan melalui Proxy ZDM:
cqlsh <zdm-proxy-node-1-ip-address> 9042
Di dalam cqlsh:
SELECT COUNT(*) FROM zdmbigtable.employee; -- Check row count matches origin SELECT * FROM employee LIMIT 10; -- Check some sample data
Atau, gunakan alat cbt (jika diinstal di VM CDM atau Cloud Shell) untuk mencari data langsung di 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. Migrasi sistem (konseptual)
Setelah memverifikasi konsistensi data antara Cassandra dan Bigtable secara menyeluruh, Anda dapat melanjutkan migrasi sistem akhir.
Dengan Proxy ZDM, peralihan melibatkan konfigurasi ulang agar terutama membaca dari target (Bigtable), bukan Origin (Cassandra). Hal ini biasanya dilakukan melalui konfigurasi ZDM Proxy, yang secara efektif mengalihkan traffic baca aplikasi Anda ke Bigtable.
Setelah yakin bahwa Bigtable menayangkan semua traffic dengan benar, Anda pada akhirnya dapat:
- Hentikan penulisan ganda dengan mengonfigurasi ulang Proxy ZDM.
- Nonaktifkan cluster Cassandra asli.
- Hapus Proxy ZDM dan minta aplikasi terhubung langsung ke Proxy Cassandra-Bigtable atau gunakan Klien CQL Bigtable native untuk Java.
Detail konfigurasi ulang Proxy ZDM untuk peralihan berada di luar codelab dasar ini, tetapi dijelaskan secara mendetail dalam dokumentasi Datastax ZDM.
10. Pembersihan
Untuk menghindari tagihan, hapus resource yang dibuat selama codelab ini.
1. Menghapus 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. Menghapus instance Bigtable
gcloud bigtable instances delete zdmbigtable
3. Menghapus aturan Firewall
gcloud compute firewall-rules delete allow-migration-internal
4. 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!
Anda telah berhasil mengikuti proses penyiapan jalur migrasi berbasis proxy dari Apache Cassandra ke Bigtable.
Anda telah mempelajari cara:
Men-deploy Cassandra dan Bigtable.
- Mengonfigurasi Proxy Cassandra-Bigtable untuk kompatibilitas CQL.
- Deploy Proxy ZDM Datastax untuk mengelola traffic dan penulisan ganda.
- Gunakan Cassandra Data Migrator untuk memindahkan data historis.
Pendekatan ini memungkinkan migrasi dengan downtime minimal dan tanpa perubahan kode dengan memanfaatkan lapisan proxy.
Langkah berikutnya
- Menjelajahi Dokumentasi Bigtable
- Lihat dokumentasi Proxy ZDM Datastax untuk konfigurasi lanjutan dan prosedur peralihan.
- Tinjau repositori Cassandra-Bigtable Proxy untuk mengetahui detail selengkapnya.
- Periksa repositori Cassandra Data Migrator untuk penggunaan lanjutan.
- Mencoba Codelab Google Cloud lainnya