Przewodnik migracji: Łącznik Kafka dla Azure Cosmos DB w wersji 1 → V2

2025-04-17

Ten przewodnik pomaga użytkownikom w aktualizacji łączników Kafka usługi Azure Cosmos DB z wersji V1 do V2 (źródłowy i ujściowy). Wersja 2 wprowadza istotne zmiany niekompatybilne, ulepszenia architektury i aktualizacje konfiguracji.

🔄 Kluczowe różnice w architekturze

Ważne jest, aby zrozumieć różnicę między konektorem Kafka V1 i konektorem Kafka V2. Chociaż łącznik zlewu nie ma prawie żadnej różnicy pod względem wydajności i szczegółów implementacji, łącznik źródłowy w wersji 2 używa struktury modelu ściągania strumienia zmian. Dzięki temu łącznik źródłowy w wersji 2 może obsługiwać wiele kontenerów w bazie danych w porównaniu z łącznikiem źródłowym W1, który był w stanie obsłużyć tylko jeden kontener na wystąpienie łącznika. Ta różnica sprawia, że łącznik źródłowy W wersji 2 jest bardziej wydajny w porównaniu z łącznikiem źródłowym W1 pod względem pamięci i przepływności. Łącznik wersji 2 oferuje optymalizację na skalę globalną w porównaniu z łącznikiem wersji 1.

Funkcja	Łącznik V1 (starsza wersja)	Łącznik V2 (nowoczesny)
Tryb zestawienia zmian	Procesor cech zmian (kontener z dzierżawą)	Model pobierania danych (temat dotyczący przesunięcia offsetu w Kafka)
Przesunięcie magazynu	Kontener dzierżawczy Cosmos DB	Tematy wewnętrznych offsetów w Kafka
Semantyka dostarczania (źródło)	Co najmniej raz	Dokładnie raz
Semantyka dostarczania (ujście)	Co najmniej raz	Dokładnie raz
Paralelizm	Podziały w Cosmos SDK	Kafka Connect — model zadania/wątku
Wersja zestawu SDK	Starszy zestaw SDK	Zestaw Java SDK usługi Azure Cosmos w wersji 4
Zgodność stanu/punktu kontrolnego	Zarządzana przez Cosmos (w kontenerze)	Zarządzane przez platformę Kafka (w temacie)
Styl konfiguracji	Specyficzne dla Cosmos, oparte na dzierżawie	Natywna dla Kafka, deklaratywna
Mechanizm uwierzytelniania	Tylko obsługa uwierzytelniania opartego na kluczach	Obsługa uwierzytelniania opartego na kluczach oraz uwierzytelniania Entra ID
Obsługa kontroli przepływności	Niewspierane	Grupa Kontroli Przepustowości jest wspierana

⚙️ Porównanie konfiguracji (wersja 1 a wersja 2)

🔹 Konfiguracja połączenia

Konfiguracja V1	Konfiguracja w wersji 2	Notatki
`connect.cosmos.master.key`	`azure.cosmos.account.key`	Zmieniono nazwę, aby uzyskać jasność
`connect.cosmos.host`	`azure.cosmos.account.endpoint`	Zmieniono nazwę dla spójności

Dodane ostatnio konfiguracje połączeń w łączniku wersji 2

Nazwa konfiguracji	Notatki
`azure.cosmos.account.tenantId`	Wymagane do uwierzytelniania powiązanego konta usługi
`azure.cosmos.auth.aad.clientSecret`	Wymagane do uwierzytelniania głównego elementu usługi
`azure.cosmos.auth.aad.clientId`	ClientId/ApplicationId jednostki usługi
`azure.cosmos.auth.aad.clientSecret`	Klucz tajny klienta/hasło jednostki usługi

🔹 Konfiguracja łącznika źródłowego

Konfiguracja wersji 1	Konfiguracja V2	Notatki
`connect.cosmos.source.container`	`azure.cosmos.container.name`	Ujednolicone nazewnictwo
`connect.cosmos.database.name`	`azure.cosmos.database.name`	Niezmienione
`connect.cosmos.source.database`	Usunięte	Użyj `cosmos.database.name`
`connect.cosmos.source.lease.container`	Usunięte	Dzierżawy nie są wykorzystywane w wersji 2
`connect.cosmos.source.lease.prefix`	Usunięte	Usunięto zarządzanie dzierżawami
`connect.cosmos.source.start.from.latest`	`azure.cosmos.source.start.from`	Użyj `Beginning` lub `Now`
`connect.cosmos.source.task.count`	`tasks.max`	Standardowa konfiguracja platformy Kafka Connect

Dalsze ustawienia konfiguracyjne można znaleźć w dokumentacji źródłowego łącznika Kafka Connector V2

🔹 Konfiguracja łącznika ujścia

Konfiguracja wersji 1	Konfiguracja w wersji 2	Notatki
`connect.cosmos.sink.database.name`	`azure.cosmos.database.name`	Zjednoczony
`connect.cosmos.sink.container.name`	`azure.cosmos.container.name`	Zunifikowany
`connect.cosmos.sink.upsert.enabled`	`azure.cosmos.sink.upsert.enabled`	Zachowane
`connect.cosmos.sink.id.strategy`	`azure.cosmos.sink.id.strategy`	Zachowane

Dalsze właściwości konfiguracji można znaleźć w dokumentacji łącznika typu sink wersji 2 łącznika Kafka

🧪 Obserwowanie i debugowanie

Konfiguracja V1	Konfiguracja V2	Notatki
Rejestrowanie niestandardowe w kodzie	Standardowe rejestrowanie SLF4J	Korzystanie z dzienników programu Kafka Connect
Inspekcja kontenera dzierżawy	Przegląd topicu offsetów w Kafka	Zgodność z narzędziami platformy Kafka

⚠️ Zmiany powodujące niezgodność

Usunięto kontener 'Lease': metadane nie są już przechowywane w kontenerze Cosmos.
Pozycja początkowa: V2 musi zostać ponownie uruchomione od początku lub bieżącego czasu za pomocą cosmos.source.start.from.
Zarządzanie przesunięciami: teraz obsługiwane wewnętrznie przez platformę Kafka — nie można przenieść z kontenerów dzierżawczych.
Model wątków: wersja 2 używa modelu wątkowania zadań platformy Kafka. Dostosuj tasks.max zamiast ustawień specyficznych dla Cosmos.

✅ Kroki migracji

Zatrzymaj V1 Connector
- Użyj interfejsu API REST platformy Kafka Connect, aby bezpiecznie zatrzymać uruchomiony łącznik V1.
- Tworzenie kopii zapasowej wszystkich danych potrzebnych z kontenera dzierżawy (jeśli jest to wymagane).
Wdróż łącznik V2
- Umieść pliki JAR łącznika V2 w ścieżce wtyczki platformy Kafka Connect.
- Usuń stare pliki JAR łącznika V1, aby uniknąć konfliktów.

Tworzenie nowych konfiguracji

Przykładowa konfiguracja źródła (wersja 2):

{
  "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"
}

Przykładowa konfiguracja zlewu (wersja 2):

{
  "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
}

Uruchom łącznik V2
- Prześlij nową konfigurację przy użyciu interfejsu API REST platformy Kafka Connect.
- Monitoruj dzienniki oraz przepływ danych dotyczących tematów.
Weryfikowanie danych wyjściowych
- Za pomocą metryk i usługi Cosmos DB Insights potwierdź pobieranie dokumentów lub postęp odczytu.
- Weryfikowanie zatwierdzeń przesunięcia w wewnętrznych tematach platformy Kafka.

📌 Dodatkowe porady

Przetestuj w środowisku przejściowym przed uruchomieniem wersji 2 w środowisku produkcyjnym.
Jeśli dokładne gwarancje dostarczania mają krytyczne znaczenie, zacznij od nowego tematu platformy Kafka, aby uniknąć duplikatów.
Wyczyść stare kontenery dzierżawy, gdy będziesz pewny wersji 2.