Kafka 커넥터 v3에서 v4로 마이그레이션
Kafka 커넥터 v3에서 v4로 마이그레이션 (Migrate from Kafka connector v3 to v4)
이 문서는 Snowflake Connector for Kafka의 v3(클래식)에서 v4로 마이그레이션하는 방법을 설명해요.
참고: 클래식 Kafka 커넥터(v3 이하)는 현재 완전히 지원되지만, 향후 폐기될 예정이에요. Snowflake는 2026년 중반에 공식 폐기 공지를 발표할 계획이며, 공지 후 18개월의 마이그레이션 기간이 시작돼요. 모든 새 구현에는 Snowflake Connector for Kafka (v4)를 사용하는 것을 권장해요.
본문
v3와 v4의 차이점
Snowflake Connector for Kafka v4는 v3와 비교해 다음과 같은 차이가 있어요:
- 아키텍처: v4는 네이티브 커넥터로 다시 설계되었고, Snowpipe Streaming을 기본 수집 방식으로 사용해요.
- 구성 속성: v4에서는 일부 v3 구성 속성이 변경되거나 더 이상 사용되지 않아요.
- Snowpipe: v4는 기본적으로 Snowpipe Streaming을 사용하므로 기존 Snowpipe 기반 객체(스테이지, 파이프) 사용 방식이 달라져요.
마이그레이션 단계
-
현재 구성 백업: v3 커넥터의 구성 파일을 백업하세요.
-
v4 커넥터 다운로드: Snowflake Kafka 커넥터 릴리스에서 v4 버전의 JAR 파일을 다운로드하세요.
-
구성 속성 검토 및 업데이트: v4에서 달라진 구성 속성을 반영하세요. 다음 표는 주요 변경 사항을 보여줘요:
| v3 속성 | v4에서의 상태 | 비고 |
| snowflake.ingestion.method | 변경됨 | v4는 Snowpipe Streaming을 기본으로 사용해요. Snowpipe를 계속 쓰려면 SNOWPIPE로 명시적으로 설정하세요. |
| snowflake.topic2table.map | 유지 | 토픽-테이블 매핑 방식은 동일해요. |
| buffer.count.records / buffer.flush.time / buffer.size.bytes | 유지 | 버퍼링 관련 속성은 동일하게 동작해요. |
| key.converter / value.converter | 유지 | 변환기 속성은 동일해요. |
-
기존 객체 처리: v4로 전환하면 기존 v3가 만든 스테이지·파이프 객체가 더는 사용되지 않을 수 있어요. 필요 시 Kafka 커넥터 관리를 참고해 정리하세요.
-
커넥터 배포 및 테스트: 새 JAR로 커넥터를 배포하고, 구성이 올바른지 커넥터 테스트로 확인하세요.
-
데이터 유실 방지 확인: 마이그레이션 중 데이터 유실을 방지하기 위해, v4 커넥터가 이전 오프셋에서 재개하는지 확인하세요. 필요한 경우
enable.streaming.channel.offset.migration속성으로 오프셋 마이그레이션을 제어할 수 있어요.
참고 사항
- 마이그레이션 중에는 기존 v3 커넥터와 새 v4 커넥터가 동시에 같은 토픽을 처리하지 않도록 하세요. 같은 토픽/파티션을 두 인스턴스가 처리하면 중복 행이 발생할 수 있어요.
- 프로덕션 전환 전에 개발/스테이징 환경에서 충분히 테스트하세요.