Bagikan melalui


Panduan Migrasi: Azure Cosmos DB Kafka Connector V1 โ†’ V2

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

  1. 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).
  2. Menyebarkan Konektor V2

    • Tempatkan JAR konektor V2 ke jalur plugin Kafka Connect.
    • Hapus JAR konektor V1 lama untuk menghindari konflik.
  3. 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
      }
      
  4. Memulai Konektor V2

    • Kirim konfigurasi baru menggunakan Kafka Connect REST API.
    • Memantau log dan aliran data topik.
  5. 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.

๐Ÿ“š Referensi