Tutorial: Set Up a Multi-Broker Kafka Cluster

김소은·2026년 1월 28일

https://docs.confluent.io/platform/current/get-started/tutorial-multi-broker.html

아래 튜토리얼은 로컬(압축파일 설치, Docker 미사용) 환경에서 KRaft(주키퍼 없이) 로 멀티 브로커 Kafka 클러스터(브로커 3개 + 컨트롤러 1개) 를 구성하고, CLI로 테스트하며, (옵션) Confluent Control Center(+Prometheus) 로 모니터링하는 전체 흐름을 설명합니다.

1) 목표 구성

KRaft isolated mode
Controller 1대 + Broker 3대
필요한 파일
- 컨트롤러 설정: my-controller.properties
- 브로커 설정: broker0.properties, broker1.properties, broker2.properties
- (옵션) Control Center 설정 파일 + Metrics/Telemetry 설정

2) 사전 준비(Prerequisites)

인터넷 연결
Confluent Platform 8 이상을 ZIP/TAR로 설치
Java 17 또는 11 (Java 8 deprecated, 9/10 미지원)
환경변수
- CONFLUENT_HOME: Confluent 설치 경로
- (옵션) CONTROL_CENTER_HOME: Control Center 설치 경로
- KAFKA_CLUSTER_ID: kafka-storage random-uuid로 생성하는 클러스터 ID

3) 핵심 설정 포인트(브로커/컨트롤러 공통 개념)

각 노드는 node.id가 유니크해야 함
각 브로커는 리스너 포트 / log.dirs가 유니크해야 함
컨트롤러는 별도 포트에서 CONTROLLER 리스너로 동작
브로커들은 동일한 컨트롤러를 바라보도록:
- controller.quorum.voters=3@localhost:9097 (예시)
멀티 브로커이므로 시스템 토픽 replication factor를 3으로 맞춤(개발/학습용이지만 안정성 측면에서 의미 있음)
- offsets.topic.replication.factor=3
- transaction.state.log.replication.factor=3
- 그리고 Confluent 관련 토픽들도 3으로

4) 설정 파일 만드는 방법(요약)

컨트롤러

controller.properties를 복사해 my-controller.properties
node.id=3
컨트롤러 포트 9097
controller.quorum.voters=3@localhost:9097
기본 telemetry는 꺼둠(후에 Control Center용 설정을 따로 넣기 위함)

브로커 0

기본 broker.properties를 복사해 broker0.properties 생성
node.id=0
리스너 포트 9092, 컨트롤러 포트 9097, 로그 디렉토리 ...logs-0
controller.quorum.voters=3@localhost:9097 추가
(Control Center용) REST 엔드포인트:
- confluent.http.server.listeners=http://localhost:8090

브로커 1/2

broker0.properties 복사 후
브로커1: node.id=1, 9093, logs-1, 8091
브로커2: node.id=2, 9094, logs-2, 8092

5) 기동 절차(KRaft에서 제일 중요한 흐름)

클러스터 ID 생성 (1회)
- KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
각 노드(컨트롤러/브로커)마다 log dir 포맷 (각각 1회)
- bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c <properties> ...
컨트롤러 먼저 시작
- bin/kafka-server-start.sh config/my-controller.properties
브로커 0/1/2를 각각 다른 터미널에서 시작
- bin/kafka-server-start.sh config/broker0.properties 등

포인트: kafka-storage format은 클러스터를 “초기화”하는 작업이라, 설정 실수하면 보통 /tmp/kraft-... 로그 디렉토리를 지우고 다시 해야 합니다.

6) 트러블슈팅(핵심만)

kafka-storage 관련 에러가 나면:
- /tmp/kraft-broker-logs-* 또는 /tmp/kraft-controller-log 같은 기존 로그 디렉토리 삭제 후 재시도

7) CLI로 정상 동작 테스트

토픽 생성/조회
- kafka-topics --create --topic test-topic --bootstrap-server localhost:9092
- kafka-topics --list --bootstrap-server localhost:9092
토픽 상세(파티션/리더/ISR 확인)
- kafka-topics --describe --topic cool-topic --bootstrap-server localhost:9092
프로듀서/컨슈머로 메시지 송수신
- kafka-console-producer --topic cool-topic --bootstrap-server localhost:9092
- kafka-console-consumer --topic cool-topic --from-beginning --bootstrap-server localhost:9092
부하 테스트(메시지 자동 생성)
- kafka-producer-perf-test ...

8) (옵션) Control Center로 모니터링

Control Center(Next Gen)는 Confluent Platform과 별도 설치/실행 디렉토리를 사용
Prometheus를 먼저 띄우고, Control Center 실행
브로커 REST 엔드포인트(8090~8092)를 Control Center 설정에 등록해야 브로커들이 보임
이후 컨트롤러/브로커 설정에 telemetry exporter(OTLP) 설정을 추가해서
- 브로커/컨트롤러 → Control Center(OTLP receiver, localhost:9090)로 메트릭 전송
웹 UI 접속: http://localhost:9021/