Panduan Migrasi: Azure Cosmos DB Kafka Connector V1 → V2

2025-04-22

Panduan ini membantu pengguna meningkatkan dari Konektor Kafka Azure Cosmos DB V1 ke V2 (sumber dan sink). V2 memperkenalkan perubahan mencolok yang signifikan, peningkatan arsitektur, dan pembaruan konfigurasi.

🔄 Perbedaan Arsitektur Utama

Penting untuk memahami perbedaan antara konektor Kafka V1 dan Kafka V2. Meskipun konektor sink hampir tidak memiliki perbedaan dalam hal performa dan detail implementasi, konektor sumber V2 menggunakan kerangka kerja model pengambilan umpan perubahan. Ini memungkinkan konektor sumber V2 untuk menangani beberapa kontainer di bawah database dibandingkan dengan Konektor Sumber V1 yang hanya dapat menangani satu kontainer per instans konektor. Perbedaan ini membuat konektor sumber V2 lebih efisien dibandingkan dengan konektor sumber V1 dalam hal memori dan throughput. Konektor V2 memiliki optimasi skala planet yang lebih unggul dibandingkan konektor V1.

Fitur	Konektor V1 (Versi Lama)	Konektor V2 (Modern)
Ubah Mode Umpan	Prosesor Umpan Perubahan (Kontainer Penyewaan)	Ubah Model Penarikan Umpan (topik offset Kafka)
Penyimpanan Offset	Kontainer sewa untuk Cosmos DB	Topik internal offset Kafka
Semantik Pengiriman (Sumber)	Setidaknya sekali	Sekali-tepat
Semantik Pengiriman (Sink)	Setidaknya sekali	tepat satu kali
Paralelisme	Partisi Cosmos SDK	Model tugas/benang Kafka Connect
Versi SDK	SDK Lama	Azure Cosmos Java SDK V4
Kompatibilitas Keadaan/Pos Pemeriksaan	Dikelola oleh Cosmos (di dalam kontainer)	Dikelola Kafka (dalam topik)
Gaya Konfigurasi	Khusus Kosmos, berbasis sewa	Kafka-asli, deklaratif
Mekanisme Autentikasi	Hanya dukungan autentikasi berbasis kunci	Dukungan autentikasi Berbasis Kunci + ID Entra
Dukungan Kontrol Laju Produksi	Tidak didukung	Grup Kontrol Throughput didukung

⚙️ Perbandingan Konfigurasi (V1 vs. V2)

🔹 Konfigurasi Koneksi

Konfigurasi V1	Konfigurasi V2	Catatan
`connect.cosmos.master.key`	`azure.cosmos.account.key`	Diganti namanya untuk kejelasan
`connect.cosmos.host`	`azure.cosmos.account.endpoint`	Diganti namanya untuk konsistensi

Konfigurasi Koneksi yang baru ditambahkan di konektor V2

Nama Konfigurasi	Catatan
`azure.cosmos.account.tenantId`	Diperlukan untuk autentikasi prinsipal layanan
`azure.cosmos.auth.aad.clientSecret`	Diperlukan untuk autentikasi entitas layanan
`azure.cosmos.auth.aad.clientId`	ClientId/ApplicationId dari prinsipal layanan
`azure.cosmos.auth.aad.clientSecret`	Rahasia/kata sandi klien dari perwakilan layanan

🔹 Konfigurasi Konektor Sumber

Konfigurasi V1	Konfigurasi V2	Catatan
`connect.cosmos.source.container`	`azure.cosmos.container.name`	Penamaan terpadu
`connect.cosmos.database.name`	`azure.cosmos.database.name`	Tidak diubah
`connect.cosmos.source.database`	Dihapus	Gunakan `cosmos.database.name`
`connect.cosmos.source.lease.container`	Dihapus	Leasing tidak digunakan di V2
`connect.cosmos.source.lease.prefix`	Dihapus	Manajemen sewa dihapus
`connect.cosmos.source.start.from.latest`	`azure.cosmos.source.start.from`	Gunakan `Beginning` atau `Now`
`connect.cosmos.source.task.count`	`tasks.max`	Konfigurasi Kafka Connect Standar

Properti konfigurasi lebih lanjut dapat ditemukan pada dokumentasi konektor sumber Kafka Connector V2

🔹 Konfigurasi Konektor Sink

Konfigurasi V1	Konfigurasi V2	Catatan
`connect.cosmos.sink.database.name`	`azure.cosmos.database.name`	Terpadu
`connect.cosmos.sink.container.name`	`azure.cosmos.container.name`	Terpadu
`connect.cosmos.sink.upsert.enabled`	`azure.cosmos.sink.upsert.enabled`	Diawetkan
`connect.cosmos.sink.id.strategy`	`azure.cosmos.sink.id.strategy`	Diawetkan

Properti konfigurasi lebih lanjut dapat ditemukan pada dokumentasi konektor sink Kafka Connector V2

🧪 Pengamatan & Pemecahan Masalah

Konfigurasi V1	Konfigurasi V2	Catatan
Pengelogan kustom dalam kode	Pengelogan SLF4J standar	Menggunakan log Kafka Connect
Inspeksi kontainer sewa	Inspeksi topik offset Kafka	Kompatibel dengan peralatan Kafka

⚠️ Perubahan yang Mengganggu

Kontainer Sewa Dihapus: Metadata tidak lagi disimpan dalam kontainer Cosmos.
Posisi Mulai: V2 harus dimulai ulang dari waktu awal atau saat ini menggunakan cosmos.source.start.from.
Manajemen Offset: Sekarang ditangani oleh Kafka secara internal — tidak dapat ditransfer dari kontainer sewa.
Model Thread: V2 menggunakan model threading tugas Kafka. Sesuaikan tasks.max alih-alih pengaturan khusus Cosmos.

✅ Langkah-langkah Migrasi

Hentikan Konektor V1
- Gunakan REST API Kafka Connect untuk menghentikan konektor V1 yang sedang berjalan dengan lancar.
- Cadangkan data apa pun yang diperlukan dari kontainer sewa (jika diperlukan).
Menyebarkan Konektor V2
- Tempatkan JAR konektor V2 ke jalur plugin Kafka Connect.
- Hapus JAR konektor V1 lama untuk menghindari konflik.

Membuat Konfigurasi Baru

Contoh Konfigurasi Sumber (V2):

{
  "name": "cosmos-source",
  "connector.class": "com.azure.cosmos.kafka.connect.source.CosmosSourceConnector",
  "tasks.max": "1",
  "cosmos.account.endpoint": "<endpoint>",
  "cosmos.account.key": "<key>",
  "cosmos.database.name": "<database>",
  "cosmos.container.name": "<container>",
  "topic": "<kafka-topic>",
  "cosmos.source.start.from": "Beginning"
}

Contoh Konfigurasi Sink (V2):

{
  "name": "cosmos-sink",
  "connector.class": "com.azure.cosmos.kafka.connect.sink.CosmosSinkConnector",
  "tasks.max": "1",
  "cosmos.account.endpoint": "<endpoint>",
  "cosmos.account.key": "<key>",
  "cosmos.database.name": "<database>",
  "cosmos.container.name": "<container>",
  "topics": "<kafka-topic>",
  "cosmos.sink.upsert.enabled": true
}

Memulai Konektor V2
- Kirim konfigurasi baru menggunakan Kafka Connect REST API.
- Memantau log dan aliran data topik.
Validasi Output
- Konfirmasikan penyerapan dokumen atau baca kemajuan melalui metrik dan Wawasan Cosmos DB.
- Validasi penerapan offset dalam topik Kafka internal.

📌 Tips Tambahan

Uji dalam penahapan sebelum menjalankan V2 dalam produksi.
Jika jaminan pengiriman yang tepat sangat penting, mulailah dengan topik Kafka baru untuk menghindari duplikat.
Bersihkan kontainer sewa lama setelah yakin dengan V2.