Dokumen ini menjelaskan cara melakukan migrasi data langsung dari instance MySQL sumber ke Spanner dengan periode nonaktif minimal menggunakan Terraform untuk men-deploy Dataflow dan Datastream.
Setelah melakukan migrasi data langsung dan yakin bahwa semua data Anda telah ditransfer, Anda telah memigrasikan kode dan dependensi, serta menyelesaikan pengujian, Anda dapat mengalihkan aplikasi untuk menggunakan Spanner, bukan database MySQL sumber.
Anda dapat melakukan migrasi data langsung setelah membuat database Spanner target. Anda perlu membuat skema yang kompatibel di database target sebelum memigrasikan data.
Cara kerjanya
Migrasi data langsung terdiri dari dua fase berikut:
Migrasi pengisian ulang:
- Selama migrasi pengisian ulang, Dataflow membaca data yang ada dari database MySQL sumber Anda dan memigrasikan data tersebut ke database Spanner target. Anda harus menggunakan template Dataflow migrasi massal untuk memindahkan data dari instance MySQL sumber ke Spanner.
- Jika migrasi pengisian ulang gagal menulis baris ke Spanner, migrasi tersebut akan menulis baris tersebut ke direktori dead-letter queue (DLQ) di bucket Cloud Storage. Anda dapat meminta migrasi pengisian ulang mencoba lagi menulis baris ini ke Spanner.
Migrasi pengambilan data perubahan (CDC):
- Fase ini berjalan bersamaan dengan migrasi pengisian ulang, yang merekam perubahan yang terjadi di instance MySQL sumber secara real time. Perubahan ini kemudian diterapkan ke Spanner setelah migrasi pengisian ulang selesai.
- Anda perlu menggunakan Datastream untuk menangkap perubahan yang terjadi di instance MySQL sumber secara real time dan menulisnya ke bucket Cloud Storage.
- Setelah migrasi pengisian ulang selesai, Anda harus menggunakan Dataflow untuk memindahkan CDC dari bucket Cloud Storage ke Spanner. Jika Dataflow gagal menulis baris ke Spanner karena alasan apa pun, Dataflow akan menulis baris tersebut ke direktori DLQ di bucket Cloud Storage yang berbeda. Migrasi CDC otomatis mencoba lagi penulisan baris dari direktori DLQ ke Spanner.
Merencanakan migrasi data langsung
Anda perlu mengonfigurasi infrastruktur jaringan yang diperlukan agar data dapat mengalir di antara instance MySQL sumber, Datastream, Dataflow , bucket Cloud Storage, dan database Spanner target. Sebaiknya konfigurasikan konektivitas jaringan pribadi untuk migrasi yang aman. Bergantung pada persyaratan kepatuhan organisasi, Anda mungkin harus mengonfigurasi konektivitas jaringan publik atau pribadi. Untuk mengetahui informasi selengkapnya tentang konektivitas Datastream, lihat Opsi konektivitas jaringan.
Untuk merencanakan migrasi data langsung, Anda mungkin memerlukan administrator jaringan organisasi Anda untuk melakukan tugas-tugas berikut:
- Gunakan VPC default atau buat VPC baru di project Anda dengan persyaratan berikut:
- Instance MySQL sumber harus tersedia di VPC ini. Anda mungkin perlu membuat aturan firewall egress di VPC ini, dan aturan firewall ingress di VPC tempat instance MySQL sumber berada.
- Bucket Datastream, Dataflow, Cloud Storage, dan database Spanner target harus tersedia di VPC ini.
- Anda harus membuat daftar yang diizinkan di instance MySQL sumber untuk mengizinkan koneksi dari VPC.
- Tentukan dan alokasikan rentang alamat IP di VPC yang dapat digunakan Datastream.
- Buat subnetwork di VPC untuk digunakan Dataflow guna menyelesaikan migrasi pengisian ulang.
- Buat subnetwork di VPC yang akan digunakan Dataflow untuk menyelesaikan migrasi CDC nanti.
Untuk melakukan migrasi data langsung, ikuti langkah-langkah berikut:
- Siapkan migrasi CDC.
- Lakukan migrasi pengisian ulang.
- Lakukan migrasi CDC setelah migrasi pengisian ulang selesai.
- Memantau dan menyelesaikan error CDC.
- Selesaikan migrasi CDC.
Melakukan migrasi data langsung memerlukan deployment dan pengelolaan sejumlah besar resource. Spanner menyediakan dua contoh template Terraform untuk setiap fase migrasi data langsung.
Template migrasi langsung melakukan migrasi CDC dalam dua fase:
- Siapkan migrasi CDC ke bucket Cloud Storage menggunakan Datastream. Anda dapat menggunakan variabel Terraform untuk mencegah template membuat tugas Dataflow.
- Migrasikan CDC ke Spanner dari bucket Cloud Storage menggunakan Dataflow. Anda harus melakukan fase ini hanya setelah template Terraform migrasi pengisian ulang selesai dengan migrasi pengisian ulang.
Template Terraform migrasi pengisian ulang melakukan migrasi pengisian ulang dari instance MySQL sumber Anda ke Spanner.
Sebelum memulai
- Pastikan Terraform diinstal di shell lokal Anda.
- Buat akun layanan untuk menjalankan migrasi data langsung. Untuk mengetahui informasi selengkapnya tentang cara membuat akun layanan, lihat Membuat akun layanan.
-
Untuk memastikan bahwa akun layanan memiliki izin yang diperlukan untuk melakukan migrasi langsung, minta administrator untuk memberikan peran IAM berikut kepada akun layanan di project Anda:
- Dataflow Admin (
roles/dataflow.admin) - Datastream Admin (
roles/datastream.admin) - Security Admin (
roles/iam.securityAdmin) - Service Account Admin (
roles/iam.serviceAccountAdmin) - Pub/Sub Admin (
roles/pubsub.admin) - Storage Admin (
roles/storage.admin) - Compute Network Admin (
roles/compute.networkAdmin) - Pelihat (
roles/viewer)
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.
Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk melakukan migrasi langsung. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:
Izin yang diperlukan
Izin berikut diperlukan untuk melakukan migrasi langsung:
-
compute.globalAddresses.create -
compute.globalAddresses.createInternal -
compute.globalAddresses.createInternal -
compute.globalAddresses.delete -
compute.globalAddresses.deleteInternal -
compute.globalAddresses.get -
compute.globalOperations.get -
compute.networks.addPeering -
compute.networks.get -
compute.networks.listPeeringRoutes -
compute.networks.removePeering -
compute.networks.use -
compute.routes.get -
compute.routes.list -
compute.subnetworks.get -
compute.subnetworks.list -
dataflow.jobs.cancel -
dataflow.jobs.create -
dataflow.jobs.updateContents -
datastream.connectionProfiles.create -
datastream.connectionProfiles.delete -
datastream.privateConnections.create -
datastream.privateConnections.delete -
datastream.streams.create -
datastream.streams.delete -
datastream.streams.update -
iam.roles.get -
iam.serviceAccounts.actAs -
pubsub.subscriptions.create -
pubsub.subscriptions.delete -
pubsub.topics.attachSubscription -
pubsub.topics.create -
pubsub.topics.delete -
pubsub.topics.getIamPolicy -
pubsub.topics.setIamPolicy -
resourcemanager.projects.setIamPolicy -
storage.buckets.create -
storage.buckets.delete -
storage.buckets.update -
storage.objects.delete
Administrator mungkin juga dapat memberi akun layanan izin ini dengan peran khusus atau peran yang telah ditetapkan sebelumnya.
- Dataflow Admin (
Menyiapkan migrasi CDC
Spanner menawarkan template Terraform yang menyiapkan CDC dan kemudian, menyelesaikan migrasi CDC. Anda dapat menggunakan variabel Terraform untuk menonaktifkan template agar tidak membuat tugas Dataflow. Template Terraform men-deploy dan mengelola resource berikut untuk menyiapkan migrasi CDC:
Koneksi pribadi Datastream: koneksi pribadi Datastream dideploy di VPC yang Anda konfigurasi.
Profil koneksi Datastream sumber: profil koneksi yang memungkinkan Datastream terhubung ke instance MySQL sumber Anda.
Bucket Cloud Storage: bucket Cloud Storage tempat Datastream menulis data.
Profil koneksi Datastream target: profil koneksi ini memungkinkan Datastream terhubung dan menulis ke bucket Cloud Storage.
Aliran data Datastream: aliran data Datastream yang membaca dari instance MySQL sumber dan menulis ke bucket Cloud Storage seperti yang ditentukan dalam profil koneksi.
Topik dan langganan Pub/Sub: bucket Cloud Storage mengirimkan notifikasi objek ke topik Pub/Sub dan Dataflow menggunakan langganan Pub/Sub untuk menulis data ke Spanner.
Notifikasi bucket Cloud Storage: notifikasi bucket Cloud Storage yang memublikasikan ke topik Pub/Sub.
Menyiapkan konfigurasi Terraform CDC
Anda dapat menyiapkan template Terraform untuk menyertakan konfigurasi variabel Dataflow, tetapi menonaktifkan pembuatan tugas Dataflow:
common_params = {
project = "PROJECT_ID"
region = "GCP_REGION"
}
datastream_params = {
mysql_host = "MYSQL_HOST_IP_ADDRESS"
mysql_username = "MYSQL_USERNAME"
mysql_password = "MYSQL_PASSWORD"
mysql_port = 3306
mysql_database = {
database = "DATABASE_NAME"
}
private_connectivity = {
vpc_name = "VPC_NAME"
range = "RESERVED_RANGE"
}
}
dataflow_params = {
skip_dataflow = false
enable_backfill = false
template_params = {
spanner_database_id = "SPANNER_DATABASE_ID"
spanner_instance_id = "SPANNER_INSTANCE_ID"
}
runner_params = {
max_workers = 10
num_workers = 4
on_delete = "cancel"
network = "VPC_NETWORK"
subnetwork = "SUBNETWORK_NAME"
}
}
Ganti kode berikut:
PROJECT_ID: Google Cloud Project IDGCP_REGION: Google Cloud region tempat Anda ingin menjalankan tugas Dataflow.MYSQL_HOST_IP_ADDRESS: alamat IP instance MySQL sumber Anda.MYSQL_USERNAME: nama pengguna instance MySQL sumber Anda.MYSQL_PASSWORD: sandi instance MySQL sumber Anda.DATABASE_NAME: nama database MySQL sumber Anda di instance.VPC_NAME: nama VPC yang ada yang digunakan oleh Datastream.RESERVED_RANGE: rentang alamat IP di VPC yang Anda cadangkan untuk Datastream.SPANNER_DATABASE_ID: ID database Spanner target.SPANNER_INSTANCE_ID: ID instance Spanner target.VPC_NETWORK: nama VPC yang ada yang digunakan oleh Dataflow.SUBNETWORK_NAME: nama subnetwork yang ditetapkan dalam VPC tempat Dataflow membuat worker.
Menjalankan template Terraform CDC
Untuk melakukan migrasi CDC, Anda harus menjalankan template Terraform:
Lakukan inisialisasi Terraform menggunakan perintah berikut:
terraform init
Validasi file Terraform menggunakan perintah berikut:
terraform plan --var-file=terraform_simple.tfvars
Jalankan konfigurasi Terraform menggunakan perintah berikut:
terraform apply --var-file=terraform_simple.tfvars
Konfigurasi Terraform menghasilkan output yang mirip dengan berikut ini:
Outputs: resource_ids = { "datastream_source_connection_profile" = "source-mysql-thorough-wombat" "datastream_stream" = "mysql-stream-thorough-wombat" "datastream_target_connection_profile" = "target-gcs-thorough-wombat" "gcs_bucket" = "live-migration-thorough-wombat" "pubsub_subscription" = "live-migration-thorough-wombat-sub" "pubsub_topic" = "live-migration-thorough-wombat" } resource_urls = { "datastream_source_connection_profile" = "https://console.cloud.google.com/datastream/connection-profiles/locations/us-central1/instances/source-mysql-thorough-wombat?project=your-project-here" "datastream_stream" = "https://console.cloud.google.com/datastream/streams/locations/us-central1/instances/mysql-stream-thorough-wombat?project=your-project-here" "datastream_target_connection_profile" = "https://console.cloud.google.com/datastream/connection-profiles/locations/us-central1/instances/target-gcs-thorough-wombat?project=your-project-here" "gcs_bucket" = "https://console.cloud.google.com/storage/browser/live-migration-thorough-wombat?project=your-project-here" "pubsub_subscription" = "https://console.cloud.google.com/cloudpubsub/subscription/detail/live-migration-thorough-wombat-sub?project=your-project-here" "pubsub_topic" = "https://console.cloud.google.com/cloudpubsub/topic/detail/live-migration-thorough-wombat?project=your-project-here" }
Datastream kini melakukan streaming CDC ke bucket Cloud Storage. Anda harus melakukan migrasi pengisian ulang dan menyelesaikan migrasi CDC nanti.
Melakukan migrasi pengisian ulang
Spanner menawarkan template Terraform untuk melakukan migrasi pengisian ulang. Template Terraform men-deploy dan mengelola resource berikut:
- Tugas Dataflow: Tugas Dataflow yang membaca dari instance MySQL sumber dan menulis ke database Spanner target.
Menyiapkan konfigurasi Terraform migrasi pengisian ulang
job_name = "JOB_NAME" project = "PROJECT_ID" region = "GCP_REGION" working_directory_bucket = "WORKING_DIRECTORY_BUCKET" working_directory_prefix = "WORKING_DIRECTORY_PREFIX" source_config_url = "SOURCE_CONFIG_URL" username = "USERNAME" password = "PASSWORD" instance_id = "SPANNER_INSTANCE_ID" database_id = "SPANNER_DATABASE_ID" spanner_project_id = "SPANNER_PROJECT_ID"
Ganti kode berikut:
JOB_NAME: nama tugas Dataflow.PROJECT_ID: Project ID Google Cloud tempat tugas Dataflow berjalan.GCP_REGION: Google Cloud region tempat Anda ingin menjalankan tugas Dataflow.WORKING_DIRECTORY_BUCKET: bucket Cloud Storage untuk mengupload file sesi dan membuat direktori output.WORKING_DIRECTORY_PREFIX: awalan bucket Cloud Storage untuk direktori kerja Dataflow.SOURCE_CONFIG_URL: alamat IP instance MySQL sumber Anda.USERNAME: nama pengguna instance MySQL sumber Anda.PASSWORD: sandi instance MySQL sumber Anda.SPANNER_INSTANCE_ID: ID instance Spanner target.SPANNER_DATABASE_ID: ID database Spanner target.SPANNER_PROJECT_ID: project ID tempat instance Spanner Anda berada. Project ID ini dapat berbeda dengan project tempat Anda menjalankan Dataflow.
Menjalankan template Terraform migrasi pengisian ulang
Untuk melakukan migrasi pengisian ulang, lakukan hal berikut:
Lakukan inisialisasi Terraform menggunakan perintah berikut:
terraform init
Validasi file Terraform menggunakan perintah berikut:
terraform plan --var-file=terraform_simple.tfvars
Jalankan konfigurasi Terraform menggunakan perintah berikut:
terraform apply --var-file=terraform_simple.tfvars
Konfigurasi Terraform menghasilkan output yang mirip dengan berikut ini:
Apply complete! Resources: 1 added, 0 changed, 0 destroyed. Outputs: dataflow_job_id = [ "2024-06-05_00_41_11-4759981257849547781", ] dataflow_job_url = [ "https://console.cloud.google.com/dataflow/jobs/gcp-region/2024-06-05_00_41_11-4759981257849547781", ]
Jika migrasi pengisian ulang tidak dapat menulis baris ke Spanner, baris tersebut akan ditulis ke direktori antrean pesan yang dihentikan pengirimannya di bucket Cloud Storage.
Anda dapat mencoba lagi penulisan baris ini dari direktori antrean pesan yang tidak terkirim ke Spanner sebelum menyelesaikan migrasi CDC.
Untuk mencoba kembali menulis baris ini dari direktori antrean pesan yang tidak terkirim ke Spanner sebelum menyelesaikan migrasi CDC, jalankan perintah berikut:
gcloud dataflow flex-template run JOB_NAME \
--project=PROJECT_ID \
--region=GCP_REGION \
--template-file-gcs-location=gs://dataflow-templates/latest/flex/Cloud_Datastream_to_Spanner \
--additional-experiments=use_runner_v2 \
--parameters inputFilePattern=INPUT_FILE_PATTERN,\
streamName="ignore",\
datastreamSourceType=SOURCE_TYPE,\
instanceId=INSTANCE_ID,databaseId=DATABASE_ID,sessionFilePath=SESSION_FILE_PATH,\
deadLetterQueueDirectory=DLQ_DIRECTORY,\
runMode="retryDLQ"
Ganti kode berikut:
JOB_NAME: nama tugas Dataflow.PROJECT_ID: Project ID Google Cloud tempat tugas Dataflow berjalan.GCP_REGION: Google Cloud region tempat Anda ingin menjalankan tugas Dataflow.INPUT_FILE_PATTERN: lokasi bucket Cloud Storage dari pola file input.SOURCE_TYPE: jenis database sumber (misalnya,mysql).INSTANCE_ID: ID instance Spanner target.DATABASE_ID: ID database Spanner target.SESSION_FILE_PATH: jalur Cloud Storage ke file sesi yang dihasilkan oleh alat migrasi Spanner.DLQ_DIRECTORY: jalur Cloud Storage ke direktori root antrean pesan yang tidak terkirim yang berisi file error untuk dicoba lagi (misalnya,gs://MIGRATION_BUCKET/ENV/SERVICE/cdc/DB_SCHEMA/).
Melakukan migrasi CDC
Setelah migrasi pengisian ulang selesai, Anda dapat menggunakan Dataflow untuk memigrasikan CDC ke Spanner. Tugas Dataflow mengambil peristiwa perubahan dari bucket Cloud Storage dan menuliskannya ke Spanner.
Untuk melakukan migrasi CDC, ubah nilai parameter Terraform skip_dataflow menjadi false dan jalankan ulang template Terraform migrasi langsung.
Jalankan konfigurasi Terraform menggunakan perintah berikut:
terraform apply --var-file=terraform_simple.tfvars
Memantau dan menyelesaikan error CDC
Selama replikasi change data capture (CDC) langsung dari MySQL ke
Spanner, jika tugas Dataflow streaming Anda tidak dapat
menulis peristiwa perubahan ke Spanner, tugas tersebut akan mengklasifikasikan kegagalan ke dalam
salah satu dari dua kategori error dan menulis data ke direktori DLQ
di bucket Cloud Storage deadLetterQueueDirectory:
Error yang dapat dicoba lagi: Kegagalan sementara, yang mencakup, tetapi tidak terbatas pada hal berikut:
- Error batas waktu Spanner terlampaui
- Pelanggaran batasan tabel yang disisipkan dan kunci asing. Hal ini dapat terjadi saat baris turunan tiba sebelum baris induknya karena error jaringan atau pemrosesan paralel.
Dataflow menulis peristiwa ini ke direktori DLQ
retry/dan mencoba ulang peristiwa tersebut dalam pipeline yang sama hingga berhasil atau melampaui batas percobaan ulang maksimum.Error berat: Kegagalan permanen yang tidak dapat diselesaikan dengan percobaan ulang otomatis, yang mencakup, tetapi tidak terbatas pada, hal berikut:
- Error konversi jenis data
- Pelanggaran indeks unik
- Pengecualian di dalam JAR transformasi kustom
Dataflow menulis peristiwa ini ke direktori DLQ
severe/dan meningkatkan penghitung pengguna kustomTotal permanent errors.
Karena error berat tidak dapat diselesaikan dengan percobaan ulang otomatis, Dataflow menghapus peristiwa yang gagal tersebut dari aliran replikasi aktif dan menyimpannya di direktori severe/. Jika tidak ditangani, database Spanner tujuan Anda akan kehilangan data tersebut.
Pantau penghitung Total permanent errors dan direktori severe/ secara rutin selama migrasi langsung sehingga Anda dapat menyelesaikan dan memutar ulang peristiwa perubahan yang gagal sebelum memulai cutover aplikasi.
Perhatikan bahwa penghitung kustom Dataflow Total permanent errors adalah metrik kumulatif yang mencatat jumlah total error parah yang terjadi sejak tugas streaming dimulai. Saat Anda memutar ulang dan menyelesaikan data yang gagal menggunakan tugas percobaan ulang DLQ, penghitung ini di pipeline streaming asli Anda tidak akan berkurang. Oleh karena itu, direktori DLQ parah Cloud Storage Anda
(gs://.../severe/) adalah sumber tepercaya yang kredibel untuk mengetahui apakah ada error
yang tidak tertangani.
Memutar ulang rekaman yang gagal
Saat data yang gagal muncul di direktori DLQ parah, periksa file error JSON di Cloud Storage, identifikasi penyebab utamanya, dan selesaikan masalah mendasar di Spanner (seperti menyisipkan data induk yang hilang secara manual atau memperbarui pemetaan penggantian skema).
Untuk memutar ulang data DLQ yang telah dikoreksi ke Spanner, luncurkan tugas Dataflow baru menggunakan salah satu mode operasi percobaan ulang DLQ berikut:
- Mode
retryDLQ: Jalankan mode ini sebagai tugas batch bersama dengan pipeline streaming aktif Anda untuk memproses file error di direktorisevere/tanpa menghentikan replikasi CDC langsung. - Mode
retryAllDLQ: Jika pipeline streaming reguler Anda dihentikan, gunakan mode ini untuk memproses direktoriretry/dansevere/. Jangan jalankanretryAllDLQsecara serentak dengan pipeline yang aktif, karena akan menyebabkan pertentangan file dan konflik pemrosesan.
Untuk meluncurkan tugas percobaan ulang DLQ menggunakan gcloud CLI, jalankan perintah berikut:
gcloud dataflow flex-template run RETRY_JOB_NAME \
--project=PROJECT_ID \
--region=GCP_REGION \
--template-file-gcs-location=gs://dataflow-templates/latest/flex/Cloud_Datastream_to_Spanner \
--additional-experiments=use_runner_v2 \
--parameters streamName="ignore",\
datastreamSourceType=SOURCE_TYPE,\
instanceId=INSTANCE_ID,databaseId=DATABASE_ID,sessionFilePath=SESSION_FILE_PATH,\
deadLetterQueueDirectory=DLQ_DIRECTORY,\
runMode="retryDLQ"
Ganti kode berikut:
RETRY_JOB_NAME: nama tugas percobaan ulang DLQ Dataflow.PROJECT_ID: Project ID Google Cloud tempat tugas Dataflow berjalan.GCP_REGION: Google Cloud region tempat Anda ingin menjalankan tugas Dataflow.SOURCE_TYPE: jenis database sumber (misalnya,mysql).INSTANCE_ID: ID instance Spanner target.DATABASE_ID: ID database Spanner target.SESSION_FILE_PATH: jalur Cloud Storage ke file sesi yang dihasilkan oleh alat migrasi Spanner.DLQ_DIRECTORY: jalur Cloud Storage ke direktori root antrean yang tidak bisa diproses yang berisi file error untuk dicoba ulang (misalnya,gs://MIGRATION_BUCKET/ENV/SERVICE/cdc/DB_SCHEMA/).
Menyelesaikan migrasi CDC
Setelah hampir semua data dari bucket Cloud Storage ditulis ke Spanner, hentikan penulisan pada instance MySQL sumber agar perubahan yang tersisa dapat ditulis ke Spanner.
Hal ini menyebabkan periode nonaktif singkat saat Spanner menyusul instance MySQL sumber. Setelah semua perubahan ditulis ke Spanner, aplikasi Anda dapat mulai menggunakan Spanner sebagai databasenya.
Untuk mengetahui petunjuk langkah demi langkah yang mendetail untuk menjeda penulisan aplikasi, mengosongkan data dalam pengiriman, dan melakukan cutover aplikasi, lihat Melakukan cutover dari MySQL.