11. Kafka 3.9 노드 구성별 server.properties 예시: KRaft 모드

Kafka KRaft 모드 운영시 server.properties 설정 항목과 함께 단일 노드, 다중 노드, 고가용성(HA) 구성에 따른 예제 파일을 제공합니다.

 

Kafka 3.9 노드 구성별 server.properties 예시: KRaft 모드

 

목차

1. KRaft 모드에서의 server.properties 위치

2. server.properties 설정 항목 정리

3. 단일 노드 구성 예시(개발 및 테스트)

4. 다중 노드 구성 예시(프로덕션 운영)

5. 고가용성 구성 예시(HA 클러스터)

관련 글 링크

 

 

1. KRaft 모드에서의 server.properties 위치

Kafka 3.x 이후부터는 KRaft 모드가 기본 제공되며, 기존의 server.properties 대신 다음 경로를 사용합니다.

/config/kraft/server.properties

이 파일은 컨트롤러, 브로커 역할 지정부터 클러스터 메타데이터 설정까지 Kafka의 핵심 구성을 담당합니다.

 

 

2. server.properties 설정 항목 정리

설정항목	항목값 및 설명
process.roles	broker,controller  - 이 노드가 Kafka 브로커와 컨트롤러 역할을 모두 수행함.  - KRaft 모드에서는 broker, controller, 또는 둘 다 지정 가능.  - 기본값 없음 (반드시 설정해야 함).
node.id	1  - 이 노드의 고유 ID.  - KRaft 모드에서는 컨트롤러와 브로커 모두 각자 고유한 ID를 가져야 함.  - 기본값 없음.
controller.quorum.voters	1@127.0.0.1:9093  - 컨트롤러 선출을 위한 투표 노드를 지정함.  - nodeID@host:port 형식으로 설정.  - 기본값 없음 (반드시 설정 필요).
listeners	PLAINTEXT://:9092,CONTROLLER://:9093  - 브로커 및 컨트롤러가 바인딩할 네트워크 주소.  - 기본값 없음.
inter.broker.listener.name	PLAINTEXT  - 브로커 간 통신에 사용할 리스너 이름.  - 기본값 없음 (반드시 설정 필요).
advertised.listeners	PLAINTEXT://127.0.0.1:9092,CONTROLLER://127.0.0.1:9093  - 클라이언트가 접속할 때 사용할 브로커 및 컨트롤러 주소.  - 기본값: listeners 값과 동일.
controller.listener.names	CONTROLLER  - 컨트롤러가 사용할 리스너 이름.  - 기본값 없음.
listener.security.protocol.map	CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,SSL:SSL,SASL_PLAINTEXT:SASL_PLAINTEXT,SASL_SSL:SASL_SSL  - 리스너 이름과 보안 프로토콜 매핑.  - 기본값 없음.
num.network.threads	3  - 네트워크 요청을 처리할 스레드 개수.  - 기본값: 3.
num.io.threads	8  - 입출력(IO) 요청을 처리할 스레드 개수.  - 기본값: 8.
socket.send.buffer.bytes	102400  - 소켓 전송 버퍼 크기(Byte).  - 기본값: 102400.
socket.receive.buffer.bytes	102400  - 소켓 수신 버퍼 크기(Byte).  - 기본값: 102400.
socket.request.max.bytes	104857600  - 최대 요청 크기(Byte).  - 기본값: 104857600 (100MB).
log.dirs	/home/kafka/kafka_2.13-3.9.0/data  - 로그 데이터를 저장할 디렉터리.  - 기본값 없음.
num.partitions	1  - 새롭게 생성되는 토픽의 기본 파티션 개수.  - 기본값: 1.
num.recovery.threads.per.data.dir	1  - 로그 복구 및 종료 시 플러시에 사용할 스레드 개수.  - 기본값: 1.
offsets.topic.replication.factor	1  -  __consumer_offsets 토픽의 복제 계수.  - 기본값: 1.
transaction.state.log.replication.factor	1  - __transaction_state 토픽의 복제 계수.  - 기본값: 1.
transaction.state.log.min.isr	1  - 트랜잭션 로그를 유지할 최소 ISR(In-Sync Replicas) 개수.  - 기본값: 1.
log.retention.hours	168  - 로그 파일이 유지되는 최대 시간(168시간 = 7일).  - 기본값: 168.
log.retention.bytes	1073741824  - 로그의 총 크기가 초과하면 삭제, 오래된 세그먼트부터 삭제  - 기본값: 비활성화
log.segment.bytes	1073741824  - 새로운 로그 세그먼트 파일이 생성되는 최대 크기(1GB).  - 기본값: 1073741824 (1GB).
log.retention.check.interval.ms	300000  - 로그 유지 정책을 확인하는 주기(ms).  - 기본값: 300000 (5분).
cluster.id	${KAFKA_CLUSTER_ID}  - Kafka 클러스터 ID. 환경 변수에서 가져옴.  - 기본값 없음.

 

◆ controller.quorum.voters 

• controller.quorum.voters는 Kafka 클러스터 내에서 컨트롤러 노드 목록을 정의하는 설정입니다.
• 이 항목은 Kafka가 어떤 노드들이 컨트롤러로 참여하는지를 알 수 있도록 하며, 컨트롤러 선출 투표에도 사용됩니다.

설정 형식: nodeId@IP:port
예시: 1@192.168.56.101:9093,2@192.168.56.102:9093,3@192.168.56.103:9093

• 이 설정을 기반으로 Kafka는 하나의 리더 컨트롤러를 선출하고, 장애가 발생하면 나머지 컨트롤러 중 하나를 자동으로 새 리더로 승격합니다.
• 브로커는 항상 리더 컨트롤러와 연결해 메타데이터 동기화를 수행하며, 이를 통해 클러스터 상태를 유지합니다.
• 운영 환경에서는 컨트롤러를 3대 이상(홀수) 구성하는 것이 권장됩니다.
• 컨트롤러가 1대뿐이라면 장애 발생 시 Kafka 전체가 동작하지 않을 수 있습니다.

◆ listener

• listeners는 Kafka 서버가 수신할 네트워크 주소(IP와 포트)를 설정하는 항목입니다.
• 브로커나 컨트롤러가 외부 요청을 수신할 수 있도록 리스너를 지정합니다.

listeners=PLAINTEXT://192.168.56.101:9092,CONTROLLER://192.168.56.101:9093

192.168.56.101:9092 → 클라이언트 요청을 받는 브로커 리스너
192.168.56.101:9093 → 컨트롤러 간 통신을 위한 리스너

각 리스너에는 명확한 역할을 지정해야 하며, 컨트롤러와 브로커는 각각 독립된 포트를 사용하는 것이 일반적입니다.

 

◆ advertised.listener

• advertised.listeners는 Kafka가 클라이언트나 다른 브로커에게 자신을 어떤 주소로 알려줄지를 설정하는 항목입니다.
• 실제 수신 주소(listeners)와 다를 수 있으며, 도커, 클라우드 환경, NAT 네트워크에서 자주 사용됩니다.

listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://public-kafka.example.com:9092

* 내부적으로는 0.0.0.0:9092에서 요청을 받지만
* 외부에서는 public-kafka.example.com:9092로 접근하도록 광고(advertise) 합니다

내부/외부 네트워크가 분리된 환경에서는 반드시 설정해줘야 하는 항목입니다.

 

◆ inter.broker.listener.name (브로커 간 통신 리스너)

• Kafka 브로커는 토픽의 리더/팔로워 간에 데이터를 복제하기 위해 브로커 간 통신을 수행합니다.
• 이때 어떤 리스너를 사용할지 지정하는 항목이 inter.broker.listener.name입니다.

listeners=PLAINTEXT://192.168.56.101:9092,SSL://192.168.56.101:9093
inter.broker.listener.name=PLAINTEXT

* 클라이언트는 PLAINTEXT 또는 SSL 리스너로 접속 가능
* 브로커 간에는 PLAINTEXT 리스너를 사용해 통신하도록 지정

 

◆ controller.listener.names (컨트롤러가 사용할 리스너)

• Kafka KRaft 모드에서 컨트롤러는 브로커들과 메타데이터를 동기화합니다.
• 이때 어떤 리스너를 사용할지를 지정하는 항목이 controller.listener.names입니다.

listeners=PLAINTEXT://192.168.56.101:9092,CONTROLLER://192.168.56.101:9093
controller.listener.names=CONTROLLER

* CONTROLLER://... 리스너는 컨트롤러 전용 포트
* controller.listener.names=CONTROLLER로 지정하여 이 리스너를 메타데이터 동기화에 사용

이 항목을 명확히 설정하지 않으면, 컨트롤러 간 또는 브로커와 컨트롤러 간 통신이 제대로 되지 않을 수 있습니다.

---

◆ num.partitions(새롭게 생성되는 토픽의 기본 파티션 수)

• Kafka에서는 데이터를 파티션(Partition) 단위로 나누어 브로커에 분산 저장합니다.
• num.partitions는 새로운 토픽을 만들 때 기본적으로 생성되는 파티션 수를 의미합니다.
• 파티션 수가 많을수록 병렬 처리 성능이 향상됩니다.
• 하지만 너무 많은 파티션은 리소스 낭비 및 운영 관리 부담을 초래할 수 있습니다.
• 실습/테스트 환경에서는 1~3개, 운영 환경에서는 트래픽과 소비자 수에 따라 적절히 조정하는 것이 좋습니다.

◆ offsets.topic.replication.factor( __consumer_offsets 토픽의 복제 개수 설정)

• Kafka는 소비자(Consumer)의 읽기 위치인 오프셋(Offset)을 __consumer_offsets라는 내부 토픽에 저장합니다.
• 이 토픽의 복제 개수를 설정하는 항목이 offsets.topic.replication.factor입니다.
• 복제본(replica)이 많을수록 장애 발생 시에도 데이터 복구 가능성이 높아집니다.
• 단, 복제 개수는 브로커 수 이하여야 합니다. (예: 브로커가 3개이면 최대 3으로 설정)
• 운영 환경에서는 2~3 이상의 복제를 권장합니다.

◆ transaction.state.log.replication.factor( __transaction_state 토픽의 복제 개수 설정)

• Kafka에서 트랜잭션을 사용할 경우, 내부 로그를 __transaction_state 토픽에 저장합니다.
• 이 설정은 해당 로그를 몇 개의 브로커에 복제할지를 지정합니다.
• 복제를 통해 트랜잭션 관련 데이터의 안정성을 보장합니다.
• 역시 복제 개수는 브로커 수 이하여야 합니다.
• 고가용성이 필요한 경우 3으로 설정하는 것이 일반적입니다.

◆ transaction.state.log.min.isr( 트랜잭션 로그의 최소 ISR(In-Sync Replicas) 개수)

• Kafka는 트랜잭션 로그를 유지하기 위해 최소한 몇 개의 복제본이 동기화되어 있어야 하는지를 이 설정으로 지정합니다.
• 이때 ISR(In-Sync Replicas)은 리더와 동기화된 팔로워 복제본의 수를 말합니다.
• 이 값이 높을수록 데이터의 안전성은 높아지지만 반면, 성능과 가용성은 낮아질 수 있습니다.
• transaction.state.log.min.isr 값은 transaction.state.log.replication.factor보다 작거나 같아야 합니다.
• 예: replication factor가 3이면 min ISR은 2 또는 3이 적절합니다.

◆ 운영환경에 따른 설정 예시

항목	설명	단일노드	소규모(3~5)	대부모(10 이상)
num.partitions	새 토픽의 기본 파티션 개수	1	3	10~50
offsets.topic.replication.factor	__consumer_offsets 토픽 복제 개수 broker node 개수 이하	1	2	3
transaction.state.log.replication.factor	__transaction_state 토픽 복제 개수 broker node 개수 이하	1	2	3
transaction.state.log.min.isr	트랜잭션 로그의 최소 ISR 개수 replication.factor 이하	1	2	3

 

 

3. 단일 노드 구성 예시(개발 및 테스트)

하나의 노드에서 브로커와 컨트롤러 역할을 모두 수행합니다.

설정이 간단하며 테스트 및 개발 환경에 적합합니다.

장애 발생 시 데이터 손실 및 서비스 중단 가능성이 높습니다.

노드ID	역할	리스너	설명
1	브로커 + 컨트롤러	PLAINTEXT://192.168.56.101:9092, CONTROLLER://192.168.56.101:9093	단일 노드로 모든 역할 수행

process.roles=broker,controller
node.id=1
controller.quorum.voters=1@192.168.56.101:9093

listeners=PLAINTEXT://192.168.56.101:9092,CONTROLLER://192.168.56.101:9093
advertised.listeners=PLAINTEXT://192.168.56.101:9092,CONTROLLER://192.168.56.101:9093
inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER

log.dirs=/home/kafka/kafka_2.13-3.9.0/data
num.partitions=1

offsets.topic.replication.factor=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1

cluster.id=${KAFKA_CLUSTER_ID}

 

 

4. 다중 노드 구성 예시(프로덕션 운영)

모든 노드가 컨트롤러와 브로커 역할을 동시에 수행합니다.

최소 3개의 노드를 구성하여 컨트롤러 선출 시 과반수 투표를 유지할 수 있습니다.

특정 컨트롤러가 다운되더라도 다른 컨트롤러가 선출되므로, 운영 안정성이 증가합니다.

브로커 확장도 가능하지만, 컨트롤러 역할을 동시에 수행하는 노드에 과부하가 걸릴 수 있습니다.

노드ID	역할	리스너	설명
1	브로커 + 컨트롤러	PLAINTEXT://192.168.56.101:9092, CONTROLLER://192.168.56.101:9093	컨트롤러 및 브로커 역할
2	브로커 + 컨트롤러	PLAINTEXT://192.168.56.102:9092, CONTROLLER://192.168.56.102:9093	컨트롤러 및 브로커 역할
3	브로커 + 컨트롤러	PLAINTEXT://192.168.56.103:9092, CONTROLLER://192.168.56.103:9093	컨트롤러 및 브로커 역할

process.roles=broker,controller

# 각 노드별 ID (서버마다 다르게 설정)
node.id=1  # 노드 1 (192.168.56.101)
#node.id=2  # 노드 2 (192.168.56.102)
#node.id=3  # 노드 3 (192.168.56.103)

controller.quorum.voters=1@192.168.56.101:9093,2@192.168.56.102:9093,3@192.168.56.103:9093

listeners=PLAINTEXT://192.168.56.101:9092,CONTROLLER://192.168.56.101:9093
#listeners=PLAINTEXT://192.168.56.102:9092,CONTROLLER://192.168.56.102:9093
#listeners=PLAINTEXT://192.168.56.103:9092,CONTROLLER://192.168.56.103:9093

advertised.listeners=PLAINTEXT://192.168.56.101:9092,CONTROLLER://192.168.56.101:9093
#advertised.listeners=PLAINTEXT://192.168.56.102:9092,CONTROLLER://192.168.56.102:9093
#advertised.listeners=PLAINTEXT://192.168.56.103:9092,CONTROLLER://192.168.56.103:9093

inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER

log.dirs=/home/kafka/kafka_2.13-3.9.0/data
num.partitions=3

offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2

cluster.id=${KAFKA_CLUSTER_ID}

다른 노드도 동일한 구성을 사용하되 node.id, listeners, log.dirs만 다르게 설정해야 합니다.

 

 

5. 고가용성 구성 예시(HA 클러스터)

여러 개의 브로커와 3개 이상의 컨트롤러를 설정하여 고가용성을 보장합니다.

컨트롤러 중 과반수 이상이 정상 동작하면 클러스터가 유지됩니다.

컨트롤러가 다중화되어 장애 발생 시 자동으로 새로운 컨트롤러를 선출할 수 있습니다.

브로커 확장(3개 이상 권장)을 통해 높은 트래픽을 처리할 수 있으며, 안정적인 운영이 가능합니다.

초기 구축 비용과 운영 관리 비용이 증가하지만, 안정성과 확장성을 최우선으로 고려한 구성입니다.

노드ID	역할	리스너	설명
1	컨트롤러	CONTROLLER://192.168.56.101:9093	컨트롤러 1
2	컨트롤러	CONTROLLER://192.168.56.102:9093	컨트롤러 2
3	컨트롤러	CONTROLLER://192.168.56.103:9093	컨트롤러 3
4	브로커	PLAINTEXT://192.168.56.104:9092	메시지 저장 및 전송
5	브로커	PLAINTEXT://192.168.56.105:9092	메시지 저장 및 전송
6	브로커	PLAINTEXT://192.168.56.106:9092	메시지 저장 및 전송

 

◆  컨트롤러 : controller.properties

process.roles=controller

node.id=1  # 컨트롤러 1 (192.168.56.101)
# node.id=2  # 컨트롤러 2 (192.168.56.102)
# node.id=3  # 컨트롤러 3 (192.168.56.103)

controller.quorum.voters=1@192.168.56.101:9093,2@192.168.56.102:9093,3@192.168.56.103:9093

listeners=CONTROLLER://192.168.56.101:9093
# listeners=CONTROLLER://192.168.56.102:9093  # 컨트롤러 2
# listeners=CONTROLLER://192.168.56.103:9093  # 컨트롤러 3

advertised.listeners=CONTROLLER://192.168.56.101:9093
# advertised.listeners=CONTROLLER://192.168.56.102:9093  # 컨트롤러 2
# advertised.listeners=CONTROLLER://192.168.56.103:9093  # 컨트롤러 3

controller.listener.names=CONTROLLER
listener.security.protocol.map=CONTROLLER:PLAINTEXT

log.dirs=/home/kafka/kafka_2.13-3.9.0/controller-data
num.partitions=1
cluster.id=${KAFKA_CLUSTER_ID}

 

◆  브로커 : broker.properties

process.roles=broker

node.id=4  # 브로커 1 (192.168.56.104)
# node.id=5  # 브로커 2 (192.168.56.105)
# node.id=6  # 브로커 3 (192.168.56.106)

controller.quorum.voters=1@192.168.56.101:9093,2@192.168.56.102:9093,3@192.168.56.103:9093

listeners=PLAINTEXT://192.168.56.104:9092
# listeners=PLAINTEXT://192.168.56.105:9092  # 브로커 2
# listeners=PLAINTEXT://192.168.56.106:9092  # 브로커 3


advertised.listeners=PLAINTEXT://192.168.56.104:9092
# advertised.listeners=PLAINTEXT://192.168.56.105:9092  # 브로커 2
# advertised.listeners=PLAINTEXT://192.168.56.106:9092  # 브로커 3

inter.broker.listener.name=PLAINTEXT
controller.listener.names=CONTROLLER
listener.security.protocol.map=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT

log.dirs=/home/kafka/kafka_2.13-3.9.0/data
num.partitions=3

offsets.topic.replication.factor=3
transaction.state.log.replication.factor=3
transaction.state.log.min.isr=2

cluster.id=${KAFKA_CLUSTER_ID}

 

---

구성 환경(단일, 다중, HA)에 따라 server.properties 설정을 적절히 구성하면 안정적인 클러스터를 운영할 수 있습니다.

 

 

관련 글 링크

2025.03.31 - [1.시스템&인프라/Apache Kafka] - 10. Kafka 3.9 KRaft 모드 설치 (JDK 17 + 단일 노드 구성)