Kafka 커넥터 (v4 고성능 아키텍처, 설정, v3 에서 옮기기)

구조

Snowflake Connector for Kafka 는 Kafka Connect 의 싱크 커넥터입니다. 고객이 운영하는 Kafka Connect 클러스터(직접 운영, Confluent, MSK Connect 등)에 올려서 토픽 메시지를 Snowflake 테이블로 보냅니다.

v4 에서 좋아진 것

• 처음부터 다시 쓴 구조로 테이블당 최대 10 GB/s, 끝에서 끝까지 5~10초 지연을 목표로 합니다.
• 채널 오프셋을 이용한 정확히 한 번, 순서 보장 전달.
• 검증과 스키마 진화를 서버 쪽 PIPE 객체에서 처리해 커넥터 워커 자원이 덜 듭니다.
• PIPE 안에서 COPY 문법으로 적재 중 변환과, 대상 테이블에 클러스터링 키가 있으면 사전 클러스터링.
• 잘못된 레코드를 담는 오류 테이블과 변환기 오류용 DLQ(Dead Letter Queue).
• 대상이 Iceberg 테이블이면 별도 설정 없이 자동으로 인식해 적재.

기본 설정 예 (v4)

name=orders-sink
connector.class=com.snowflake.kafka.connector.SnowflakeSinkConnector
tasks.max=8
topics=orders,payments
snowflake.url.name=myorg-prod.snowflakecomputing.com:443
snowflake.user.name=SVC_KAFKA
snowflake.private.key=${file:/secrets/kafka.properties:private_key}
snowflake.role.name=KAFKA_LOADER
snowflake.database.name=RAW
snowflake.schema.name=KAFKA
snowflake.topic2table.map=orders:ORDERS_RAW,payments:PAYMENTS_RAW
key.converter=org.apache.kafka.connect.storage.StringConverter
value.converter=org.apache.kafka.connect.json.JsonConverter
value.converter.schemas.enable=false
errors.tolerance=all
errors.deadletterqueue.topic.name=snowflake-dlq

• 인증은 키 페어입니다. Kafka 커넥터는 암호화된 개인 키를 지원하지 않는 클라이언트로 분류되므로 개인 키 파일 자체를 비밀 저장소로 보호합니다.
• tasks.max 는 토픽 파티션 수 이하로 둡니다. 파티션보다 태스크가 많으면 노는 태스크가 생깁니다.
• 세부 속성 이름은 v4 문서의 설정 표를 기준으로 하고, v3 설정 파일을 그대로 쓰지 마세요.

테이블 모양

기본으로 커넥터가 만든 테이블에는 두 열이 있습니다.

스키마화(schematization)를 켜면 메시지 필드를 열로 펼쳐 넣고, 새 필드가 오면 열을 추가합니다. 원본 VARIANT 를 그대로 두고 Dynamic Tables 로 정형화하는 방식도 운영이 단순해서 많이 씁니다.

-- 파티션별 마지막 오프셋 확인 (지연과 누락 점검)
SELECT record_metadata:partition::INT AS p,
       MAX(record_metadata:offset::INT) AS last_offset,
       MAX(TO_TIMESTAMP(record_metadata:CreateTime::NUMBER, 3)) AS last_created
FROM raw.kafka.orders_raw
GROUP BY 1 ORDER BY 1;

v3 에서 v4 로 옮기기

1. 공식 마이그레이션 가이드(migrate-v3-to-v4)를 읽고 v4 설정 파일을 새로 만듭니다.
2. 시작할 때 snowflake.streaming.validate.compatibility.with.classic 검사기로 기존 설정과 호환성을 확인합니다.
3. v3 Snowpipe Streaming 채널의 오프셋을 이어받으려면 snowflake.streaming.classic.offset.migration 을 설정합니다.
4. 테이블 이름 정리, 열 식별자 정규화, 스키마화 방식이 v3 과 같도록 호환 플래그를 맞춥니다.
5. 공식 문서는 올바르게 설정하면 Snowpipe 모드와 Snowpipe Streaming 모드 모두에서 빈틈이나 중복 없이 옮길 수 있다고 안내합니다. 문제가 생기면 v3 로 되돌릴 수 있고, 중복 제거는 RECORD_METADATA 의 토픽, 파티션, 오프셋으로 합니다.

팁 운영 토픽 하나를 먼저 v4 로 옮기고, 같은 기간의 행 수와 오프셋을 v3 테이블과 비교한 뒤 나머지를 옮깁니다.

Openflow Kafka 커넥터와의 차이

2026 Summit 에서는 Kafka 와 프로토콜 호환되는 Snowflake 안의 관리형 스트리밍 Snowflake Datastream 이 발표되었습니다 (발표 당시 PrPr 예정). 아직 일반에 열리지 않았으므로 운영 설계는 위 두 방식으로 합니다.

트러블슈팅

• 증상: 커넥터가 "JWT token is invalid" 로 실패합니다.

• 원인: 사용자에 등록한 공개 키와 커넥터의 개인 키가 다르거나, 계정 식별자(URL) 형식이 틀렸습니다.

• 해결: DESC USER 의 RSA_PUBLIC_KEY_FP 와 로컬에서 계산한 지문을 비교합니다. 방법은 인증 문서에 있습니다.

• 증상: 지연이 계속 늘어납니다.

• 원인: tasks.max 가 파티션 수보다 적거나, 메시지가 아주 커서 변환기에서 막히거나, 대상 테이블 PIPE 변환이 무겁습니다.

• 해결: 파티션 수만큼 태스크를 늘리고, 커넥터 지표와 오류 테이블을 확인합니다. 무거운 변환은 적재 후 단계로 옮깁니다.

공식 문서

• Snowflake Connector for Kafka
• Kafka connector v4.0 GA (release note)
• Kafka connector release notes 2026