백엔드 데이터 인프라 94편 — Kafka Broker 설정 30가지 (실무 핵심)

이 글은 백엔드 데이터 인프라 시리즈 130편 중 94편이에요. Part 5-3 API까지 데이터 흐름과 운영 자동화 API를 풀었고, 94편부터는 Part 5-4 — Kafka Configuration 5편으로 들어갑니다. 첫 글인 Broker 설정은 수백 가지 옵션 중 실무에서 자주 조정하는 30개만 추렸어요.

Broker 설정이 어렵게 느껴지는 이유

공식 문서는 수백 가지 설정을 그냥 나열해 둬서 어디서 시작해야 할지 막막해요. importance가 high/medium/low로 표시돼 있지만 high만 추려도 100개가 넘고, 상황별 권장값이 적혀 있지 않아서 기본값이 운영 환경에 맞는지 가늠하기 어렵습니다. 게다가 replication·log·network·security가 알파벳 순으로 섞여서 카테고리도 흩어져 있어요. 그래서 이 글에서는 실무에서 정말 자주 조정하는 30개만 카테고리별로 묶어 정리합니다.

1. Identity·Process (필수)

node.id (필수)

node.id=1

KRaft(ZooKeeper 없이 Kafka가 자체 합의) 모드에서 broker 식별자. cluster 안에서 unique한 정수.

process.roles

process.roles=broker,controller     # 결합 모드 (단일 노드)
# 또는
process.roles=broker                 # broker only
# 또는
process.roles=controller             # controller only

KRaft 모드의 핵심. 소규모는 결합, 대규모는 분리.

controller.quorum.bootstrap.servers

controller.quorum.bootstrap.servers=controller-1:9093,controller-2:9093,controller-3:9093

Controller quorum(과반 합의 그룹) 구성.

2. Log·Storage

log.dirs (필수)

log.dirs=/var/kafka-data
# 또는 여러 디스크 (JBOD)
log.dirs=/disk1/kafka,/disk2/kafka,/disk3/kafka

Topic partition의 데이터 저장 경로. 여러 디스크를 쓰면 JBOD(디스크를 묶지 않고 개별 사용)로 콤마 구분합니다.

log.retention.hours / log.retention.bytes

log.retention.hours=168              # 7일 (기본)
log.retention.bytes=-1               # -1 = 무제한

Topic 메시지의 보존 기간과 크기. 둘 중 먼저 도달한 쪽이 발동합니다.

log.segment.bytes

log.segment.bytes=1073741824         # 1GB (기본)

Segment 파일 크기. 작으면 retention이 정밀해지고, 크면 open file 수가 줄어요.

log.cleanup.policy

log.cleanup.policy=delete            # 기본, 시간/크기 retention
# 또는
log.cleanup.policy=compact           # log compaction (107편)
# 또는
log.cleanup.policy=delete,compact     # 둘 다

log.flush.interval.messages / log.flush.interval.ms

# 기본 = 둘 다 무한대 (OS pagecache 의존, 84편)
log.flush.interval.messages=10000
log.flush.interval.ms=1000

여기서 시험 함정이 하나 있어요 — 명시적 fsync(디스크 강제 동기화) 강제는 성능을 망칩니다. 84편에서 본 pagecache(OS가 파일을 RAM에 캐싱하는 영역) 의존이 Kafka의 핵심 전략이에요. 정말 필요한 경우에만 조정합니다.

3. Replication

default.replication.factor

default.replication.factor=3

Topic 생성 시 명시하지 않으면 사용할 RF(replication factor, 복제본 수).

min.insync.replicas

min.insync.replicas=2

86·89편에서 본 핵심. RF=3 + min.insync=2 + acks=all 이 안전 황금 조합입니다.

replica.lag.time.max.ms

replica.lag.time.max.ms=30000        # 30초 (기본)

Follower가 leader를 따라잡지 못해 ISR(In-Sync Replicas, 동기화된 복제본 집합)에서 제거되는 시간.

unclean.leader.election.enable

unclean.leader.election.enable=false   # 기본, 안전 우선

89편에서 본 데이터 손실과 가용성의 trade-off.

num.replica.fetchers

num.replica.fetchers=4                # follower 가 leader 에서 fetch 하는 스레드 수

큰 cluster나 고처리량이면 8~16으로 늘립니다.

4. Network·Threads

listeners

listeners=PLAINTEXT://0.0.0.0:9092,SSL://0.0.0.0:9093

Broker가 듣는 endpoint. 0.0.0.0은 모든 인터페이스를 의미해요.

advertised.listeners

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

Client에게 알려주는 주소. Docker·Kubernetes 환경에서 자주 함정으로 작동합니다. 클라이언트가 advertised로 다시 연결하므로 resolvable hostname이어야 해요.

num.network.threads

num.network.threads=3                 # 기본

Socket 처리 스레드. 큰 cluster면 8~16으로 늘립니다.

num.io.threads

num.io.threads=8                      # 기본

요청 처리 스레드. 디스크 I/O 부담이 크면 늘립니다.

socket.send.buffer.bytes / socket.receive.buffer.bytes

socket.send.buffer.bytes=102400
socket.receive.buffer.bytes=102400

TCP buffer. 고대역폭 환경에서 늘립니다.

message.max.bytes

message.max.bytes=1048588             # 1MB (기본)

Broker가 받는 최대 메시지 크기. 큰 메시지 환경이면 조정합니다.

5. Compression

compression.type

compression.type=producer             # 기본, producer 가 선택
# 또는
compression.type=zstd                  # broker 가 강제 압축

producer는 producer가 보낸 그대로 저장해 가장 효율이 좋아요. zstd·lz4·gzip·snappy는 broker가 재압축하니 CPU 비용이 올라갑니다.

6. Consumer Group

offsets.retention.minutes

offsets.retention.minutes=10080       # 7일 (기본)

Consumer Group의 committed offset 보존 기간. 초과되면 그룹 offset이 사라지고, 다음 시작 때 auto.offset.reset이 발동합니다.

group.initial.rebalance.delay.ms

group.initial.rebalance.delay.ms=3000   # 3초 (기본)

새 그룹의 첫 rebalance 전 대기 시간. 여러 consumer가 동시에 시작될 때 한 번에 join하게 만들어 불필요한 rebalance를 줄여요.

group.max.session.timeout.ms

group.max.session.timeout.ms=1800000   # 30분 (기본)

Consumer 측 session.timeout.ms의 broker 측 한계.

7. Security (113~116편 깊이)

security.inter.broker.protocol

security.inter.broker.protocol=PLAINTEXT
# 운영 환경
security.inter.broker.protocol=SSL

Broker끼리의 통신 protocol.

ssl.keystore.location·ssl.truststore.location

114편 SSL 깊이.

sasl.enabled.mechanisms

sasl.enabled.mechanisms=PLAIN,SCRAM-SHA-512

115편 SASL(Simple Authentication and Security Layer, 인증 프로토콜) 깊이.

authorizer.class.name

authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer

ACL authorizer 활성화. 116편 깊이.

8. KRaft Specific (105편 깊이)

controller.listener.names

controller.listener.names=CONTROLLER

controller.quorum.voters

controller.quorum.voters=1@controller-1:9093,2@controller-2:9093,3@controller-3:9093

KRaft controller quorum 멤버.

9. JMX·Monitoring (100편 깊이)

JMX_PORT (환경변수)

export JMX_PORT=9999
$ bin/kafka-server-start.sh ...

JMX(Java Management Extensions, 자바 모니터링 표준) 메트릭 노출 port.

auto.create.topics.enable

auto.create.topics.enable=false       # 운영 환경 권장

true(기본)면 producer가 없는 topic으로 send할 때 자동 생성됩니다. 운영 환경에서는 명시적 provisioning만 허용해요.

delete.topic.enable

delete.topic.enable=true              # Kafka 1.0+ 기본

Topic 삭제 허용 여부.

운영 환경 권장 설정 예시

# Identity
node.id=1
process.roles=broker,controller
controller.quorum.voters=1@host1:9093,2@host2:9093,3@host3:9093

# Storage
log.dirs=/var/kafka-data
log.retention.hours=168
log.segment.bytes=1073741824

# Replication
default.replication.factor=3
min.insync.replicas=2
unclean.leader.election.enable=false
num.replica.fetchers=4

# Network
listeners=SSL://0.0.0.0:9093
advertised.listeners=SSL://kafka-1.example.com:9093
num.network.threads=8
num.io.threads=16

# Compression
compression.type=producer

# Consumer Group
offsets.retention.minutes=10080
group.initial.rebalance.delay.ms=3000

# Security
security.inter.broker.protocol=SSL
ssl.keystore.location=/etc/kafka/ssl/keystore.jks
ssl.truststore.location=/etc/kafka/ssl/truststore.jks
authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer

# Operational
auto.create.topics.enable=false
delete.topic.enable=true

동적 설정 vs 정적 설정

런타임 변경:

$ kafka-configs.sh --bootstrap-server localhost:9092 \
    --entity-type brokers --entity-name 1 \
    --alter --add-config "log.retention.hours=240"

모니터링·실수 함정

1. auto.create.topics.enable=true 운영 환경

오타 topic name으로 무의미한 topic이 잔뜩 생깁니다. 운영 환경은 false로 둬요.

2. advertised.listeners 미설정 (Docker)

listeners=PLAINTEXT://0.0.0.0:9092만 박으면 client가 localhost:9092로 연결을 시도해 실패합니다. advertised는 반드시 설정해야 해요.

3. min.insync.replicas 미설정

89편에서 본 함정. acks=all만 박고 min.insync=1이면 사실상 acks=1이에요.

4. unclean.leader.election=true 무신경

데이터 손실 위험을 명시적으로 받아들이는 셈. 운영 환경 기본은 false.

5. log.flush.interval.* 명시 설정

OS pagecache 의존이 깨지면서 성능이 망가집니다. 정말 필요한 경우에만.

시험 직전 한 번 더 — Kafka Broker Config 함정 압축 노트

• Identity 필수 = node.id + process.roles + controller.quorum.bootstrap.servers
• process.roles = broker / controller / broker,controller (소규모 결합)
• Log = log.dirs (여러 디스크 콤마) + log.retention.hours/bytes + log.segment.bytes + log.cleanup.policy
• Replication = default.replication.factor=3 + min.insync.replicas=2 + unclean.leader.election.enable=false
• 황금 조합 = RF=3 + min.insync=2 + acks=all
• Network = listeners·advertised.listeners·num.network.threads·num.io.threads
• Docker/K8s 함정 = advertised.listeners 반드시 resolvable
• message.max.bytes 1MB 기본 — 큰 메시지 환경 조정
• Compression = compression.type=producer (가장 효율) vs zstd/lz4/gzip/snappy (broker 재압축)
• Consumer Group = offsets.retention.minutes=7일 + group.initial.rebalance.delay.ms
• Security (113~116편) = security.inter.broker.protocol·ssl.*·sasl.*·authorizer.class.name
• KRaft = controller.listener.names·controller.quorum.voters
• 운영 권장 = auto.create.topics.enable=false + delete.topic.enable=true
• 동적 vs 정적 = read-only (재시작 필요) vs per-broker/cluster-wide (kafka-configs.sh)
• 모니터링 = JMX (100편)
• 함정 — auto.create.topics 운영에서 켜져 있음 → 오타 topic 폭증
• 함정 — advertised.listeners 미설정 (Docker)
• 함정 — min.insync.replicas 미설정 → acks=all 무용
• 함정 — unclean.leader.election=true → 데이터 손실
• 함정 — log.flush.interval 명시 → 성능 폭망

공식 문서: Kafka Broker Configs 에서 모든 설정의 자세한 사양을 확인할 수 있어요.

시리즈 다른 편 (앞뒤 글 모음)

이전 글:

• 89편 — Kafka Replication (ISR · Leader Election · Unclean)
• 90편 — Kafka API 5종 종합 (Producer · Consumer · Streams · Connect · Admin)
• 91편 — Kafka Producer API 깊이 (Serializer · Callback · Interceptor)
• 92편 — Kafka Consumer API 깊이 (Commit · Rebalance · Seek)
• 93편 — Kafka Admin Client API (Topic·ACL·Consumer Group 관리)

다음 글:

• 95편 — Kafka Topic 설정 (Retention · Compression · Cleanup)
• 96편 — Kafka Producer 설정 20가지 (Batching · Retries · Idempotence)
• 97편 — Kafka Consumer 설정 25가지 (Group · Commit · Fetch)
• 98편 — Kafka Admin Client 설정 (간결 정리)
• 99편 — Kafka 운영 기본 (Topic·Partition·Reassign·Rolling Restart)