MirrorMaker 설정

MirrorMaker 설정 (MirrorMaker Configs)

MirrorMaker 2는 Kafka 클러스터 간에 데이터를 미러링(복제)하는 도구예요. 이 문서는 MirrorMaker 2를 구성하는 커넥터들의 설정을 정리해요.

출처: 문서

참고: 공통 구성의 SSL(ssl.*), SASL(sasl.*), OAUTHBEARER(sasl.oauthbearer.*) 항목들은 Admin 설정 등 다른 클라이언트 설정 문서와 동일해요. 여기서는 MirrorMaker 특유의 설정을 중심으로 설명할게요.

본문

아래는 MirrorMaker 2를 구성하는 커넥터들의 설정이에요.

MirrorMaker 공통 설정 (MirrorMaker Common Configs)

아래는 세 커넥터 모두에 적용되는 공통 설정이에요.

• source.cluster.alias — 소스 클러스터의 별칭(alias).
  • 유형: string / 중요도: high
• target.cluster.alias — 타깃 클러스터의 별칭. 지표 보고에 사용돼요.
  • 유형: string / 기본값: target / 중요도: high
• ssl.* / sasl.* / sasl.oauthbearer.* / security.protocol — 클라이언트 보안 설정. ssl.key.password, ssl.keystore.*, ssl.truststore.*, ssl.enabled.protocols, ssl.keystore.type, ssl.protocol, ssl.provider, ssl.truststore.type, sasl.client.callback.handler.class, sasl.jaas.config, sasl.kerberos.service.name, sasl.login.callback.handler.class, sasl.login.class, sasl.mechanism, sasl.login.*, ssl.cipher.suites, ssl.endpoint.identification.algorithm, ssl.engine.factory.class, ssl.keymanager.algorithm, ssl.secure.random.implementation, ssl.trustmanager.algorithm 등의 항목은 다른 Kafka 클라이언트 설정 문서와 동일해요. 자세한 설명은 Admin/Producer/Consumer 설정 페이지를 참고해요. 대표적인 기본값은 security.protocol=PLAINTEXT, ssl.protocol=TLSv1.3, sasl.mechanism=GSSAPI예요.
• admin.timeout.ms — 관리 작업(예: 새 토픽 감지)의 타임아웃.
  • 유형: long / 기본값: 60000 (1분) / 중요도: low
• config.providers — ConfigProvider 인터페이스를 구현하는 클래스의 쉼표로 구분된 별칭 이름. 외부 소스에서 구성 데이터를 로드할 수 있게 해줘요.
  • 유형: list / 기본값: "" / 중요도: low
• enabled — source→target 복제를 할지 여부.
  • 유형: boolean / 기본값: true / 중요도: low
• forwarding.admin.class — 커스텀 클러스터 리소스 관리(토픽, 구성 등)를 정의하기 위해 ForwardingAdmin을 확장하는 클래스. (Map config) 시그니처의 생성자가 있어야 하며, KafkaAdminClient 구성에 사용되고 필요하면 외부 시스템용 클라이언트 구성에도 사용될 수 있어요.
  • 유형: class / 기본값: org.apache.kafka.clients.admin.ForwardingAdmin / 중요도: low
• metric.reporters — 지표 리포터 클래스 목록. JmxReporter가 필요하면 명시적으로 목록에 추가해야 해요. 유형: list / 기본값: org.apache.kafka.common.metrics.JmxReporter / 중요도: low
• replication.policy.class — 원격 토픽 이름 규칙을 정의하는 클래스.
  • 유형: class / 기본값: org.apache.kafka.connect.mirror.DefaultReplicationPolicy / 중요도: low
• replication.policy.internal.topic.separator.enabled — checkpoint와 offset-sync에 사용되는 토픽 이름을 replication.policy.separator로 제어할지 여부. 기본적으로 커스텀 구분자가 그 토픽 이름에 사용돼요. 다만 그 토픽 이름을 커스터마이즈할 수 없던 이전 버전에서 MirrorMaker 2를 업그레이드하는 경우, 같은 이름을 계속 쓰려면 이 속성을 false로 설정해야 할 수 있어요.
  • 유형: boolean / 기본값: true / 중요도: low
• replication.policy.separator — 원격 토픽 이름 규칙에 사용되는 구분자.
  • 유형: string / 기본값: . / 중요도: low
• name — 이 커넥터에 사용할 전역적으로 고유한 이름. 유형: string / 유효 값: ISO 제어 문자가 없는 비어 있지 않은 문자열 / 중요도: high
• connector.class — 이 커넥터의 클래스 이름 또는 별칭. org.apache.kafka.connect.connector.Connector의 하위 클래스여야 해요. org.apache.kafka.connect.file.FileStreamSinkConnector라면 전체 이름 대신 FileStreamSink나 FileStreamSinkConnector를 써서 짧게 할 수 있어요.
  • 유형: string / 중요도: high
• connector.plugin.version — 커넥터 버전. 유형: string / 기본값: null / 중요도: medium
• tasks.max — 이 커넥터에 사용할 최대 작업(task) 수. 유형: int / 기본값: 1 / 유효 값: [1,...] / 중요도: high
• tasks.max.enforce — (비권장) 커넥터가 tasks.max 속성을 존중하도록 강제할지 여부. 기본적으로 너무 많은 작업을 생성하는 커넥터는 실패하고, tasks.max를 초과하는 기존 작업 집합도 실패해요. false로 설정하면 커넥터가 최대 작업 수보다 더 많이 생성할 수 있고, 초과 작업 집합도 실행이 허용돼요. 이 속성은 비권장이며 다가오는 메이저 릴리스에서 제거될 예정이에요.
  • 유형: boolean / 기본값: true / 중요도: low
• key.converter / value.converter — Kafka Connect 형식과 Kafka에 쓰이는 직렬화 형식 사이를 변환하는 컨버터 클래스. 메시지의 키/값 형식을 제어하며, 커넥터와 독립적이라 어떤 커넥터든 어떤 직렬화 형식과도 동작해요. 일반적인 형식에는 JSON과 Avro가 있어요.
  • 유형: class / 기본값: null / 중요도: low
• key.converter.plugin.version / value.converter.plugin.version — 키/값 컨버터 버전. 유형: string / 기본값: null / 중요도: low
• header.converter — Kafka Connect 형식과 Kafka에 쓰이는 직렬화 형식 사이의 헤더 값을 변환하는 HeaderConverter 클래스. 기본적으로 SimpleHeaderConverter가 헤더 값을 문자열로 직렬화하고 스키마를 추론해 역직렬화해요.
  • 유형: class / 기본값: null / 중요도: low
• config.action.reload — 외부 구성 프로바이더의 변경으로 커넥터 구성 속성이 바뀌었을 때 Connect가 취할 조치. none은 아무것도 안 함, restart는 갱신된 구성으로 커넥터를 재시작/다시 로드함(restart는 나중으로 예약될 수도 있어요 — 외부 프로바이더가 구성 값이 미래에 만료된다고 표시하면).
  • 유형: string / 기본값: restart / 유효 값: [none, restart] / 중요도: low
• transforms — 레코드에 적용할 변환(transform)의 별칭. 유형: list / 기본값: "" / 중요도: low
• predicates — 변환이 사용하는 술어(predicate)의 별칭. 유형: list / 기본값: "" / 중요도: low
• errors.retry.timeout — 실패한 작업을 재시도할 최대 기간(밀리초). 기본값 0은 재시도를 하지 않는다는 뜻이에요. 무한 재시도는 -1 사용. 유형: long / 기본값: 0 / 중요도: medium
• errors.retry.delay.max.ms — 연속 재시도 사이의 최대 기간(밀리초). 이 한도에 도달하면 썬더링 허드 문제를 막기 위해 지연에 지터가 추가돼요. 유형: long / 기본값: 60000 (1분) / 중요도: medium
• errors.tolerance — 커넥터 동작 중 오류를 허용하는 방식. none(기본값)은 어떤 오류든 즉시 커넥터 작업 실패로 이어지고, all은 문제가 있는 레코드를 건너뛰도록 동작을 바꿔요.
  • 유형: string / 기본값: none / 유효 값: [none, all] / 중요도: medium
• errors.log.enable — true면 각 오류와 실패한 작업·문제 레코드의 세부 사항을 Connect 애플리케이션 로그에 기록해요. 기본값은 false라 허용되지 않은 오류만 보고돼요. 유형: boolean / 기본값: false / 중요도: medium
• errors.log.include.messages — 실패를 일으킨 Connect 레코드를 로그에 포함할지 여부. 싱크 레코드의 경우 토픽·파티션·오프셋·타임스탬프가 기록되고, 소스 레코드의 경우 키·값(및 스키마)·헤더·타임스탬프·Kafka 토픽·Kafka 파티션·소스 파티션·소스 오프셋이 기록돼요. 기본값은 false라 레코드 키·값·헤더가 로그 파일에 기록되지 않아요. 유형: boolean / 기본값: false / 중요도: medium

MirrorMaker 소스 설정 (MirrorMaker Source Configs)

아래는 토픽을 복제하는 MirrorMaker 2 소스 커넥터의 설정이에요.

• config.properties.exclude — 복제하지 않을 토픽 구성 속성. 쉼표로 구분된 속성 이름과 정규식을 지원해요.
  • 유형: list / 기본값: follower.replication.throttled.replicas,leader.replication.throttled.replicas,message.timestamp.difference.max.ms,log.message.timestamp.before.max.ms,log.message.timestamp.after.max.ms,message.timestamp.type,unclean.leader.election.enable,min.insync.replicas / 중요도: high
• topics — 복제할 토픽. 쉼표로 구분된 토픽 이름과 정규식을 지원해요.
  • 유형: list / 기본값: .* / 중요도: high
• topics.exclude — 제외할 토픽. 쉼표로 구분된 토픽 이름과 정규식을 지원해요. 제외가 포함보다 우선해요.
  • 유형: list / 기본값: mm2.*\.internal,.*\.replica,__.* / 중요도: high
• config.property.filter.class — 사용할 ConfigPropertyFilter. 복제할 토픽 구성 속성을 선택해요. 유형: class / 기본값: org.apache.kafka.connect.mirror.DefaultConfigPropertyFilter / 중요도: low
• consumer.poll.timeout.ms — 소스 클러스터를 폴링할 때의 타임아웃. 유형: long / 기본값: 1000 (1초) / 중요도: low
• emit.offset-syncs.enabled — 복제된 레코드의 새 오프셋을 offset-syncs 토픽에 저장할지 여부. emit.offset-syncs.enabled가 비활성화된 동안 emit.checkpoints.enabled나 sync.group.offsets.enabled가 활성화되면 MirrorCheckpointConnector는 그룹 오프셋 동기화나 checkpoint 발행을 할 수 없어요.
  • 유형: boolean / 기본값: true / 중요도: low
• heartbeats.replication.enabled — 토픽 필터에 포함되지 않아도 하트비트 토픽을 복제할지 여부. true면 복제 정책이 식별하는 하트비트 토픽이 토픽 필터 구성과 무관하게 항상 복제돼요. false면 토픽 필터가 허용할 때만 복제돼요.
  • 유형: boolean / 기본값: true / 중요도: low
• metric.names.formats — (비권장) 지표가 발행되는 형식. 값은 legacy와 new. legacy는 kafka.connect.mirror:type=MirrorSourceConnector,... 같은 이름, new는 kafka.connect:type=plugins,... 같은 이름으로 발행해요. legacy,new로 설정하면 두 이름 모두로 발행하는데, 새 형식으로 마이그레이션할 때 유용하지만 지표 양이 두 배가 돼요. Kafka 5.0에서 legacy 형식과 이 구성은 제거되고 지표는 항상 새 이름을 사용해요.
  • 유형: list / 기본값: legacy / 유효 값: [legacy, new] / 중요도: low
• offset-syncs.topic.location — offset-syncs 토픽의 위치(소스/타깃).
  • 유형: string / 기본값: source / 유효 값: [source, target] / 중요도: low
• offset-syncs.topic.replication.factor — offset-syncs 토픽의 복제 팩터. 유형: short / 기본값: 3 / 중요도: low
• offset.lag.max — 원격 파티션이 재동기화(resync)되기 전에 얼마나 동기화에서 벗어날 수 있는지. 유형: long / 기본값: 100 / 중요도: low
• refresh.topics.enabled — 주기적으로 새 토픽·파티션을 확인할지 여부. 유형: boolean / 기본값: true / 중요도: low
• refresh.topics.interval.seconds — 토픽 갱신 빈도. 유형: long / 기본값: 600 / 중요도: low
• replication.factor — 새로 생성된 원격 토픽의 복제 팩터. 유형: int / 기본값: 2 / 중요도: low
• sync.topic.acls.enabled — 주기적으로 원격 토픽 ACL을 해당 업스트림 토픽과 일치하도록 구성할지 여부. 유형: boolean / 기본값: true / 중요도: low
• sync.topic.acls.interval.seconds — 토픽 ACL 동기화 빈도. 유형: long / 기본값: 600 / 중요도: low
• sync.topic.configs.enabled — 주기적으로 원격 토픽을 해당 업스트림 토픽과 일치하도록 구성할지 여부. 유형: boolean / 기본값: true / 중요도: low
• sync.topic.configs.interval.seconds — 토픽 구성 동기화 빈도. 유형: long / 기본값: 600 / 중요도: low
• topic.filter.class — 사용할 TopicFilter. 복제할 토픽을 선택해요. 유형: class / 기본값: org.apache.kafka.connect.mirror.DefaultTopicFilter / 중요도: low

MirrorMaker Checkpoint 설정 (MirrorMaker Checkpoint Configs)

아래는 컨슈머 오프셋 checkpoint를 발행하는 MirrorMaker 2 체크포인트 커넥터의 설정이에요.

• groups — 복제할 컨슈머 그룹. 쉼표로 구분된 그룹 ID와 정규식을 지원해요.
  • 유형: list / 기본값: .* / 중요도: high
• groups.exclude — 제외할 그룹. 쉼표로 구분된 그룹 ID와 정규식을 지원해요. 제외가 포함보다 우선해요.
  • 유형: list / 기본값: console-consumer-.*,connect-.*,__.* / 중요도: high
• checkpoints.topic.replication.factor — checkpoints 토픽의 복제 팩터. 유형: short / 기본값: 3 / 중요도: low
• consumer.poll.timeout.ms — 소스 클러스터를 폴링할 때의 타임아웃. 유형: long / 기본값: 1000 (1초) / 중요도: low
• emit.checkpoints.enabled — 컨슈머 오프셋을 타깃 클러스터로 복제할지 여부. 유형: boolean / 기본값: true / 중요도: low
• emit.checkpoints.interval.seconds — checkpoint 빈도. 유형: long / 기본값: 60 / 중요도: low
• group.filter.class — 사용할 GroupFilter. 복제할 컨슈머 그룹을 선택해요. 유형: class / 기본값: org.apache.kafka.connect.mirror.DefaultGroupFilter / 중요도: low
• metric.names.formats — (비권장) 지표 발행 형식. legacy와 new 중 선택, legacy,new로 둘 다 가능(마이그레이션용, 지표 2배). Kafka 5.0에서 제거되고 항상 new 형식 사용. 유형: list / 기본값: legacy / 유효 값: [legacy, new] / 중요도: low
• offset-syncs.topic.location — offset-syncs 토픽의 위치(소스/타깃). 유형: string / 기본값: source / 유효 값: [source, target] / 중요도: low
• refresh.groups.enabled — 주기적으로 새 컨슈머 그룹을 확인할지 여부. 유형: boolean / 기본값: true / 중요도: low
• refresh.groups.interval.seconds — 그룹 갱신 빈도. 유형: long / 기본값: 600 / 중요도: low
• sync.group.offsets.enabled — 타깃 클러스터에서 활성 컨슈머가 없는 한, 번역된 오프셋을 주기적으로 타깃 클러스터의 __consumer_offsets 토픽에 쓸지 여부.
  • 유형: boolean / 기본값: false / 중요도: low
• sync.group.offsets.interval.seconds — 컨슈머 그룹 오프셋 동기화 빈도. 유형: long / 기본값: 60 / 중요도: low
• topic.filter.class — 사용할 TopicFilter. 유형: class / 기본값: org.apache.kafka.connect.mirror.DefaultTopicFilter / 중요도: low

MirrorMaker 하트비트 설정 (MirrorMaker HeartBeat Configs)

아래는 커넥터와 클러스터 사이의 연결을 확인하는 MirrorMaker 2 하트비트 커넥터의 설정이에요.

• emit.heartbeats.enabled — 타깃 클러스터로 하트비트를 발행할지 여부. 유형: boolean / 기본값: true / 중요도: low
• emit.heartbeats.interval.seconds — 하트비트 빈도. 유형: long / 기본값: 1 / 중요도: low
• heartbeats.topic.replication.factor — 하트비트 토픽의 복제 팩터. 유형: short / 기본값: 3 / 중요도: low

더 알아보기 (Learn more)

• MirrorMaker 2는 소스(토픽 복제), 체크포인트(오프셋·그룹 동기화), 하트비트(연결 확인) 세 커넥터로 동작해요.
• source.cluster.alias·target.cluster.alias와 replication.policy.*(토픽 이름 규칙)이 미러링의 골격을 결정해요.