Deployment Architecture

이 도메인이 묻는 것

핵심 개념 요약 — 운영 관점

노드 롤 — process.roles

컨트롤러 쿼럼 사이징 — 3 vs 5

메타데이터 쿼럼은 Raft이므로 과반이 살아 있어야 쓰기(메타데이터 변경)가 가능합니다. 동시 장애 N건을 견디려면 컨트롤러가 2N+1대 필요합니다.

정적 쿼럼 vs 동적 쿼럼

KRaft에는 두 가지 운영 방식이 있습니다. 어느 쪽인지는 포맷 시점에 결정됩니다.

랙 인식 — broker.rack

브로커에 broker.rack=my-rack-id를 붙이면 토픽 생성·수정·재배치 시 같은 파티션의 레플리카가 서로 다른 랙에 퍼집니다. 정확히는 한 파티션이 min(랙 수, replication factor)개의 랙에 걸칩니다. 클라우드에서는 가용 영역(AZ)을 랙으로 쓰는 것이 일반적입니다.

브로커 사이징과 디스크

멀티 데이터센터

권장 구성은 DC마다 로컬 Kafka 클러스터를 두고, 애플리케이션은 자기 DC의 클러스터만 쓰고, 클러스터 사이를 미러링하는 것입니다. 전체 데이터가 필요한 애플리케이션을 위해 집계(aggregate) 클러스터를 따로 두고 각 DC에서 미러링해 채웁니다.

MirrorMaker 2

MM2는 Kafka Connect 프레임워크 위에 만들어진 클러스터 간 복제 도구입니다. 클러스터 내부 복제(레플리카)와는 완전히 다른 것입니다. 토픽 데이터와 설정, 컨슈머 그룹과 오프셋, ACL을 복제하고 파티셔닝을 보존합니다.

# 클러스터 별칭 정의
clusters = us-west, us-east
us-west.bootstrap.servers = broker3-west:9092
us-east.bootstrap.servers = broker5-east:9092

# 기본 복제 대상: 모든 토픽
topics = .*

# 흐름 활성화와 흐름별 오버라이드
us-west->us-east.enabled = true
us-west->us-east.topics = orders.*, payments.*

# 워커 수보다 태스크를 넉넉히 (기본값 1은 너무 작습니다)
tasks.max = 5

# 클러스터별 클라이언트 설정 오버라이드
us-west.consumer.isolation.level = read_committed
us-east.producer.compression.type = zstd

# 이 프로세스가 담당할 대상 클러스터만 지정 (대상 클러스터 근처에서 실행하는 것이 일반적)
bin/connect-mirror-maker.sh connect-mirror-maker.properties --clusters us-east

# 지정하지 않으면 설정에 정의된 모든 흐름을 이 프로세스가 담당합니다
bin/connect-mirror-maker.sh connect-mirror-maker.properties

필수 CLI 명령어

# 클러스터 ID 생성 (전 노드가 같은 값을 씁니다)
CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# (권장) 첫 컨트롤러 하나로 부트스트랩한 뒤 나머지를 동적으로 추가
bin/kafka-storage.sh format --cluster-id $CLUSTER_ID --standalone \
    --config config/controller.properties

# 또는 처음부터 여러 voter 로 부트스트랩 (모든 컨트롤러에서 같은 값으로 실행)
bin/kafka-storage.sh format --cluster-id $CLUSTER_ID \
    --initial-controllers "0@controller-0:9093:$UUID0,1@controller-1:9093:$UUID1,2@controller-2:9093:$UUID2" \
    --config config/controller.properties

# 기존 클러스터에 합류할 브로커·컨트롤러
bin/kafka-storage.sh format --cluster-id $CLUSTER_ID \
    --config config/server.properties --no-initial-controllers

# 리더·에폭·voter·observer
bin/kafka-metadata-quorum.sh --bootstrap-server localhost:9092 describe --status

# 노드별 Lag / LastFetchTimestamp / LastCaughtUpTimestamp
bin/kafka-metadata-quorum.sh --bootstrap-server localhost:9092 describe --replication

# kraft.version 이 0 이면 정적, 1 이상이면 동적 쿼럼
bin/kafka-features.sh --bootstrap-controller localhost:9093 describe

# 기능 버전 업그레이드
bin/kafka-features.sh --bootstrap-server localhost:9092 upgrade --feature kraft.version=1

# 추가: 프로비저닝 → 기동 → --replication 으로 따라잡았는지 확인 → add-controller
bin/kafka-metadata-quorum.sh --command-config config/controller.properties \
    --bootstrap-controller localhost:9093 add-controller

# 제거: 노드를 내리기 전에 먼저 쿼럼에서 뺀다
bin/kafka-metadata-quorum.sh --bootstrap-controller localhost:9093 remove-controller \
    --controller-id 3 --controller-directory-id <directory-id>

# 1) cordon: 이 브로커의 로그 디렉터리를 신규 배치 대상에서 제외
bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter \
    --add-config cordoned.log.dirs="*" --entity-type brokers --entity-name 1

# 2) 이 브로커의 모든 파티션을 다른 브로커로 재할당 (계획은 직접 작성)
#    절차는 Cluster Configuration 페이지 참고

# 3) 브로커 종료 후 클러스터에서 등록 해제
bin/kafka-cluster.sh unregister --bootstrap-server localhost:9092 --id 1

# 메타데이터 로그 세그먼트 디코딩
bin/kafka-dump-log.sh --cluster-metadata-decoder \
    --files metadata_log_dir/__cluster_metadata-0/00000000000000000000.log

# 스냅샷을 대화식으로 탐색
bin/kafka-metadata-shell.sh \
    --snapshot metadata_log_dir/__cluster_metadata-0/00000000000000007228-0000000001.checkpoint

반드시 외워야 할 설정값

장애 시나리오와 대응

시나리오 1 — 컨트롤러 과반을 잃었다

1. 증상: 토픽 생성·삭제·설정 변경이 모두 타임아웃. 기존 파티션의 읽기·쓰기는 한동안 계속됩니다.
2. kafka-metadata-quorum.sh --bootstrap-controller ... describe --status로 현재 voter와 리더를 확인합니다.
3. 브로커도 못 붙는 상황이면 --bootstrap-controller로 컨트롤러에 직접 조회합니다.
4. 과반을 복구하는 것이 유일한 정답입니다. 내려간 컨트롤러를 다시 올립니다.
5. 디스크가 날아간 컨트롤러를 새로 넣을 때는 포맷 전에 describe --replication으로 과반이 커밋된 데이터를 갖고 있는지 확인합니다. 빈 로그 디렉터리로 과반이 기동하면 커밋된 데이터가 빠진 리더가 뽑힐 수 있습니다.

시나리오 2 — 컨트롤러를 3대에서 5대로 늘려야 한다

이 절차가 list order 유형으로 자주 나옵니다. 순서를 바꾸면 쿼럼이 위험해집니다.

1. kafka-features.sh describe로 동적 쿼럼(kraft.version 1 이상)인지 확인합니다. 정적이면 먼저 업그레이드해야 합니다.
2. 새 컨트롤러 노드를 --no-initial-controllers로 포맷합니다.
3. 새 컨트롤러를 기동합니다. 이 시점에는 아직 voter가 아니라 observer입니다.
4. describe --replication으로 새 노드가 리더를 따라잡았는지 확인합니다.
5. 따라잡은 뒤 add-controller로 쿼럼에 편입합니다.
6. 한 대씩 반복합니다. 여러 대를 동시에 넣으면 과반 계산이 흔들립니다.

제거는 순서가 반대입니다. remove-controller를 먼저 실행하고 그 다음에 노드를 내립니다. 노드를 먼저 내리면 쿼럼은 그 노드를 여전히 voter로 세면서 과반 계산에 포함합니다.

시나리오 3 — AZ 한 곳이 죽자 일부 토픽이 쓰기 불가가 되었다

1. 랙 인식이 켜져 있었는지 확인합니다. broker.rack이 없으면 배치가 랙을 고려하지 않았습니다.
2. broker.rack이 있어도 랙 인식은 배치 시점에만 적용됩니다. 나중에 broker.rack을 붙였다면 기존 파티션 배치는 바뀌지 않습니다.
3. kafka-topics.sh --describe로 문제 토픽의 레플리카가 어느 브로커에 있는지 확인합니다.
4. 랙을 고려한 배치로 되돌리려면 파티션 재할당을 명시적으로 실행해야 합니다.
5. 랙마다 브로커 수가 다르면 배치가 불균등해지므로, 그 기회에 랙별 브로커 수를 맞춥니다.

시나리오 4 — MM2 복제가 계속 뒤처진다

1. tasks.max가 기본값 1인지 확인합니다. 공식 권고는 최소 2, 가능하면 더 크게입니다.
2. 복제 토픽의 파티션 수를 확인합니다. 태스크는 토픽-파티션 단위로 나뉩니다.
3. WAN이라면 socket.send.buffer.bytes·socket.receive.buffer.bytes를 대역폭·지연 곱에 맞춰 올립니다.
4. 대상 클러스터 쪽 프로듀서 압축({target}.producer.compression.type)으로 전송량을 줄입니다.
5. 새로 만든 토픽이 늦게 복제된다면 refresh.topics.interval.seconds(기본 600)를 확인합니다. 탐지 주기 문제입니다.

자주 나오는 함정

관련 케이스 스터디

• 케이스 6 · RF=3인데 브로커 1대 죽자 유실됐다 — 배치와 min.insync.replicas
• 케이스 3 · 브로커 장애 후 메시지가 유실됐다 — 복제 배치와 확인 조건

KRaft 구조의 배경은 3장 KRaft와 클러스터 메타데이터, 업그레이드 경로와 레거시 대응은 부록, MM2 실습은 예제 11에 있습니다. 구성 변경 절차는 Cluster Configuration과 이어집니다.

미니 퀴즈

쿼럼 사이징 계산과 절차 배열이 중심입니다.

공식 문서 출처

• KRaft — process.roles, 컨트롤러 3 또는 5, 2N+1, combined 모드 권장 사항, 정적·동적 쿼럼, 컨트롤러 추가·제거, 메모리·디스크 5GB
• Hardware and OS — 메모리 산정, 디스크·파일시스템, XFS·noatime, 파일 디스크립터, vm.max_map_count, flush 정책, 컨트롤러 디스크 교체 절차
• Basic Kafka Operations — broker.rack과 min(랙 수, RF), 랙별 브로커 수 권고, 브로커 제거(cordon · unregister)
• Datacenters — DC별 클러스터 + 미러링 권장, 단일 클러스터 확장 비권장, 소켓 버퍼 튜닝
• Geo-Replication (MirrorMaker 2) — 복제 흐름 표기, DefaultReplicationPolicy, tasks.max 권고, exactly-once 3.5.0
• MirrorMaker Configs — replication.factor, sync.group.offsets.enabled, refresh.topics.interval.seconds 기본값
• Java Version — Java 17 · 21 · 25