브로커 설정

브로커 설정 (Broker Configs)

Kafka 브로커 자체의 설정 항목들을 정리한 문서예요. 클러스터 동작, 로그 저장·보존, 리플리케이션, 컨트롤러/쿼럼, 그룹 코디네이터, 보안 리스너 같은 브로커의 근간을 결정하는 값들이 여기 있어요.

출처: 문서

본문

필수 설정은 다음과 같아요.

node.id — 이 프로세스가 맡는 역할(node id)과 연결된 노드 ID. KRaft 모드 실행 시 필수 구성이에요.
log.dirs — 로그 데이터를 저장하는 디렉토리 목록.
process.roles — 이 프로세스가 맡는 역할: broker, controller, 또는 둘 다면 broker,controller.
controller.quorum.bootstrap.servers — 클러스터 메타데이터 부트스트랩에 사용할 엔드포인트 목록.
controller.listener.names — 컨트롤러가 사용하는 리스너 이름 목록.

아래에서 브로커 구성과 기본값을 더 자세히 다룰게요.

중요도 high 설정

controller.listener.names — 컨트롤러가 사용하는 리스너 이름의 쉼표로 구분된 목록. 컨트롤러 쿼럼과 통신할 때 필요하며, 브로커는 항상 이 목록의 첫 번째 리스너를 사용해요.
- 유형: list / 중요도: high / 갱신 모드: 읽기 전용
node.id — process.roles가 비어 있지 않을 때 이 프로세스가 맡는 역할과 연결된 노드 ID. KRaft 모드에서 필수 구성.
- 유형: int / 유효 값: [0,...] / 중요도: high / 갱신 모드: 읽기 전용
process.roles — 이 프로세스가 맡는 역할: broker, controller, 또는 둘 다면 broker,controller.
- 유형: list / 유효 값: [broker, controller] / 중요도: high / 갱신 모드: 읽기 전용
add.partitions.to.txn.retry.backoff.max.ms — 서버 측에서 트랜잭션에 파티션을 추가하는 최대 허용 타임아웃. 실제 add partition 연산에만 적용되고 검증에는 적용되지 않아요. request.timeout.ms보다 크면 효과가 없어요.
- 유형: int / 기본값: 100 / 유효 값: [0,...] / 중요도: high / 갱신 모드: 읽기 전용
add.partitions.to.txn.retry.backoff.ms — 서버가 트랜잭션에 파티션을 추가하려 할 때의 서버 측 재시도 백오프.
- 유형: int / 기본값: 20 / 유효 값: [1,...] / 중요도: high / 갱신 모드: 읽기 전용
advertised.listeners — Kafka 브로커가 클라이언트와 다른 브로커에게 광고할 리스너 주소. 실제 리스너 구성 listeners가 클라우드 환경처럼 클라이언트가 연결해야 할 주소를 나타내지 않을 때 유용해요. 설정하지 않으면 listeners 값을 사용해요. listeners와 달리 0.0.0.0 메타 주소는 광고할 수 없고, 중복 포트가 허용돼요(한 리스너가 다른 리스너의 주소를 광고하게 할 수 있음).
- 유형: list / 기본값: null / 중요도: high / 갱신 모드: 읽기 전용
auto.create.topics.enable — 서버에서 토픽 자동 생성을 활성화할지 여부. 유형: boolean / 기본값: true / 중요도: high / 갱신 모드: 읽기 전용
auto.leader.rebalance.enable — 자동 리더 균형을 활성화해요. 백그라운드 스레드가 leader.imbalance.check.interval.seconds로 구성된 간격으로 파티션 리더의 분포를 검사하고, 불균형이면 파티션을 preferred leader로 리밸런스해요. 유형: boolean / 기본값: true / 중요도: high / 갱신 모드: 읽기 전용
background.threads — 다양한 백그라운드 처리 작업에 사용할 스레드 수. 유형: int / 기본값: 10 / 유효 값: [1,...] / 중요도: high / 갱신 모드: cluster-wide
broker.id — 이 서버의 브로커 id. 유형: int / 기본값: -1 / 중요도: high / 갱신 모드: 읽기 전용
compression.type — 주어진 토픽의 최종 압축 유형. 표준 압축 코덱(gzip, snappy, lz4, zstd)과, 압축 없는 uncompressed, 프로듀서가 설정한 원래 코덱을 유지하는 producer를 받아요. 유형: string / 기본값: producer / 유효 값: [uncompressed, zstd, lz4, snappy, gzip, producer] / 중요도: high / 갱신 모드: cluster-wide
controller.quorum.bootstrap.servers — 클러스터 메타데이터 부트스트랩에 사용할 엔드포인트 목록. {host}:{port} 항목의 쉼표 구분 목록. 예: localhost:9092,localhost:9093,localhost:9094. 유형: list / 기본값: "" / 유효 값: 비어 있지 않은 목록 / 중요도: high / 갱신 모드: 읽기 전용
controller.quorum.election.backoff.max.ms — 새 선거를 시작하기 전의 최대 시간(밀리초). 교착 선거를 막는 이진 지수 백오프 메커니즘에 사용돼요. 유형: int / 기본값: 1000 (1초) / 유효 값: [0,...] / 중요도: high / 갱신 모드: 읽기 전용
controller.quorum.election.timeout.ms — 새 선거를 트리거하기 전에 리더에게서 fetch하지 못한 채 기다리는 최대 시간(밀리초). 유형: int / 기본값: 1000 (1초) / 중요도: high / 갱신 모드: 읽기 전용
controller.quorum.fetch.timeout.ms — 현재 리더에게서 성공적 fetch 없이 지낸 최대 시간(후보가 되어 선거 트리거); 리더가 쿼럼 과반에게서 유효한 fetch/fetchSnapshot을 받지 못한 채 견딜 수 있는 최대 시간(사임하기 전). 유형: int / 기본값: 2000 (2초) / 중요도: high / 갱신 모드: 읽기 전용
controller.quorum.voters — {id}@{host}:{port} 항목의 쉼표 구분 목록으로 된 voter 집합의 id/엔드포인트 맵. 컨트롤러 쿼럼 멤버십을 정의하는 옛 방식이며 동적 쿼럼을 쓰면 설정하지 말아야 해요. 대신 controller.quorum.bootstrap.servers를 설정하고, 포맷 시 --standalone 또는 --initial-controllers 플래그로 voter 집합을 결정해요. 유형: list / 기본값: "" / 유효 값: 비어 있지 않은 목록 / 중요도: high / 갱신 모드: 읽기 전용
delete.topic.enable — true면 admin 클라이언트가 토픽을 삭제할 수 있어요. false면 삭제 요청이 브로커에서 명시적으로 거부돼요. 유형: boolean / 기본값: true / 중요도: high / 갱신 모드: 읽기 전용
early.start.listeners — authorizer 초기화가 끝나기 전에 시작될 수 있는 리스너 이름의 쉼표 구분 목록. ACL을 메타데이터 로그에 저장하는 StandardAuthorizer처럼 authorizer가 부트스트랩에 클러스터 자신에 의존할 때 유용해요. 기본적으로 controller.listener.names에 포함된 모든 리스너가 early start 리스너예요. 외부 트래픽을 받는 리스너는 이 목록에 있으면 안 돼요. 유형: list / 기본값: null / 중요도: high / 갱신 모드: 읽기 전용
group.coordinator.background.threads — 그룹 코디네이터가 백그라운드 작업(예: 정규식 구독, 오프로드된 할당 갱신)을 처리하는 데 사용하는 스레드 수. 유형: int / 기본값: 2 / 유효 값: [1,...] / 중요도: high / 갱신 모드: 읽기 전용
group.coordinator.threads — 그룹 코디네이터가 요청을 처리하는 데 사용하는 스레드 수. 유형: int / 기본값: 4 / 유효 값: [1,...] / 중요도: high / 갱신 모드: 읽기 전용
leader.imbalance.check.interval.seconds — 컨트롤러가 파티션 리밸런스 검사를 트리거하는 빈도. 유형: long / 기본값: 300 / 유효 값: [1,...] / 중요도: high / 갱신 모드: 읽기 전용
listeners — 리스너 목록. 수신할 URI와 리스너 이름의 쉼표 구분 목록. 리스너 이름이 보안 프로토콜이 아니면 listener.security.protocol.map도 설정해야 해요. 리스너 이름과 포트 번호는 고유해야 해요(하나가 IPv4, 다른 하나가 같은 포트의 IPv6가 아닌 한). 호스트를 0.0.0.0으로 지정하면 모든 인터페이스에 바인딩, 비우면 기본 인터페이스에 바인딩. 예: PLAINTEXT://myhost:9092,SSL://:9091. 유형: list / 기본값: PLAINTEXT://:9092 / 중요도: high / 갱신 모드: per-broker
log.dir — 로그 데이터를 저장하는 디렉토리의 쉼표 구분 목록(log.dirs에 대한 보조 속성). 유형: list / 기본값: /tmp/kafka-logs / 중요도: high / 갱신 모드: 읽기 전용
log.dirs — 로그 데이터를 저장하는 디렉토리의 쉼표 구분 목록. 설정하지 않으면 log.dir 값을 사용해요. 유형: list / 기본값: null / 중요도: high / 갱신 모드: 읽기 전용
log.flush.interval.messages — 메시지가 디스크로 플러시되기 전에 로그 파티션에 쌓이는 메시지 수. 유형: long / 기본값: 9223372036854775807 / 중요도: high / 갱신 모드: cluster-wide
log.flush.interval.ms — 어떤 토픽의 메시지가 디스크로 플러시되기 전에 메모리에 유지되는 최대 시간(ms). 설정하지 않으면 log.flush.scheduler.interval.ms 값을 사용해요. 유형: long / 기본값: null / 중요도: high / 갱신 모드: cluster-wide
log.flush.offset.checkpoint.interval.ms — 로그 복구 지점 역할을 하는 마지막 플러시의 지속 기록을 갱신하는 빈도. 유형: int / 기본값: 60000 (1분) / 중요도: high / 갱신 모드: 읽기 전용
log.flush.scheduler.interval.ms — 로그 플러셔가 어떤 로그를 디스크로 플러시해야 하는지 검사하는 빈도(ms). 유형: long / 기본값: 9223372036854775807 / 중요도: high / 갱신 모드: 읽기 전용
log.flush.start.offset.checkpoint.interval.ms — 로그 시작 오프셋의 지속 기록을 갱신하는 빈도. 유형: int / 기본값: 60000 (1분) / 중요도: high / 갱신 모드: 읽기 전용
log.retention.bytes — 로그를 삭제하기 전의 최대 크기. 유형: long / 기본값: -1 / 중요도: high / 갱신 모드: cluster-wide
log.retention.hours — 로그 파일을 삭제하기 전에 유지하는 시간(시간), log.retention.ms보다 3차 우선. 유형: int / 기본값: 168 / 중요도: high / 갱신 모드: 읽기 전용
log.retention.minutes — 로그 파일을 삭제하기 전 유지하는 시간(분), log.retention.ms에 2차. 설정하지 않으면 log.retention.hours 사용. 유형: int / 기본값: null / 중요도: high / 갱신 모드: 읽기 전용
log.retention.ms — 로그 파일을 삭제하기 전 유지하는 시간(ms). 설정하지 않으면 log.retention.minutes 사용, -1이면 시간 제한 없음. 유형: long / 기본값: null / 중요도: high / 갱신 모드: cluster-wide
log.roll.hours — 새 로그 세그먼트가 롤되기 전 최대 시간(시간), log.roll.ms에 2차. 유형: int / 기본값: 168 / 중요도: high / 갱신 모드: 읽기 전용
log.roll.jitter.hours — logRollTimeMillis에서 빼는 최대 지터(시간), log.roll.jitter.ms에 2차. 유형: int / 기본값: 0 / 중요도: high / 갱신 모드: 읽기 전용
log.roll.jitter.ms — logRollTimeMillis에서 빼는 최대 지터(ms). 설정하지 않으면 log.roll.jitter.hours 사용. 유형: long / 기본값: null / 중요도: high / 갱신 모드: cluster-wide
log.roll.ms — 새 로그 세그먼트가 롤되기 전 최대 시간(ms). 설정하지 않으면 log.roll.hours 사용. 유형: long / 기본값: null / 중요도: high / 갱신 모드: cluster-wide
log.segment.bytes — 단일 로그 파일의 최대 크기. 유형: int / 기본값: 1073741824 (1 gibibyte) / 유효 값: [1048576,...] / 중요도: high / 갱신 모드: cluster-wide
log.segment.delete.delay.ms — 파일을 파일시스템에서 삭제하기 전에 기다리는 시간. 값이 0이고 삭제할 파일이 없으면 1ms 기다려요. 낮은 값은 busy-wait를 일으켜요. 유형: long / 기본값: 60000 (1분) / 중요도: high / 갱신 모드: cluster-wide
message.max.bytes — Kafka가 허용하는 가장 큰 레코드 배치 크기(압축 활성화 시 압축 후). 토픽 레벨 max.message.bytes로 토픽별 설정 가능. 유형: int / 기본값: 1048588 / 유효 값: [0,...] / 중요도: high / 갱신 모드: cluster-wide
metadata.log.dir — 메타데이터 로그를 넣을 위치를 정하는 구성. 설정하지 않으면 log.dirs의 첫 번째 로그 디렉토리에 넣어요. 유형: string / 기본값: null / 중요도: high / 갱신 모드: 읽기 전용
metadata.log.max.record.bytes.between.snapshots — 새 스냅샷을 생성하기 전에 최신 스냅샷과 하이 워터마크 사이의 로그 최대 바이트 수. 기본값 20971520. 시간 기반 스냅샷은 metadata.log.max.snapshot.interval.ms 참고. Kafka 노드는 최대 시간 간격 또는 최대 바이트 한도에 도달할 때 스냅샷을 생성해요. 유형: long / 기본값: 20971520 / 중요도: high / 갱신 모드: 읽기 전용
metadata.log.max.snapshot.interval.ms — 최신 스냅샷에 포함되지 않은 커밋된 레코드가 로그에 있으면 스냅샷을 생성하기 전에 기다리는 최대 밀리초. 0이면 시간 기반 스냅샷 생성을 비활성화. 기본값 3600000. 유형: long / 기본값: 3600000 (1시간) / 중요도: high / 갱신 모드: 읽기 전용
metadata.log.segment.bytes — 단일 메타데이터 로그 파일의 최대 크기. 유형: int / 기본값: 1073741824 (1 gibibyte) / 유효 값: [8388608,...] / 중요도: high / 갱신 모드: 읽기 전용
metadata.log.segment.ms — 새 메타데이터 로그 파일이 롤되기 전 최대 시간(ms). 유형: long / 기본값: 604800000 (7일) / 중요도: high / 갱신 모드: 읽기 전용
metadata.max.retention.bytes — 오래된 스냅샷과 로그 파일을 삭제하기 전 메타데이터 로그와 스냅샷의 최대 결합 크기. 로그를 삭제하려면 스냅샷이 최소 하나 있어야 하므로 소프트 한도예요. 유형: long / 기본값: 104857600 (100 mebibytes) / 중요도: high / 갱신 모드: 읽기 전용
metadata.max.retention.ms — 메타데이터 로그 파일 또는 스냅샷을 삭제하기 전 유지하는 밀리초. 스냅샷이 하나 있어야 삭제할 수 있으므로 소프트 한도. 유형: long / 기본값: 604800000 (7일) / 중요도: high / 갱신 모드: 읽기 전용
min.insync.replicas — 프로듀서가 acks를 all(또는 -1)로 설정했을 때 쓰기가 성공하려면 필요한 동기화된 복제본(ISR)(리더 포함)의 최소 수. acks=all이면 모든 동기화 복제본이 승인해야 해요. acks=all이고 ISR이 min.insync.replicas보다 적으면 프로듀서가 NotEnoughReplicas 또는 NotEnoughReplicasAfterAppend 예외를 일으켜요. min.insync.replicas와 acks를 함께 쓰면 더 강한 내구성 보장을 강제할 수 있어요. 일반적인 시나리오는 복제 팩터 3, min.insync.replicas=2, acks=all로 프로듀스하는 것이에요. 참고: Eligible Leader Replicas(ELR) 기능이 활성화되면 의미가 바뀌어요. 유형: int / 기본값: 1 / 중요도: high / 갱신 모드: cluster-wide
num.io.threads — 서버가 요청 처리에 사용하는 스레드 수(디스크 I/O 포함 가능). 유형: int / 기본값: 8 / 중요도: high / 갱신 모드: cluster-wide
num.network.threads — 서버가 네트워크에서 요청 수신·응답 전송에 사용하는 스레드 수. 각 리스너(컨트롤러 제외)는 고유 스레드 풀을 만들어요. 유형: int / 기본값: 3 / 중요도: high / 갱신 모드: cluster-wide
num.recovery.threads.per.data.dir — 시작 시 로그 복구와 종료 시 플러시에 데이터 디렉토리당 사용하는 스레드 수. 유형: int / 기본값: 2 / 유효 값: [1,...] / 중요도: high / 갱신 모드: cluster-wide
num.replica.alter.log.dirs.threads — 로그 디렉토리 사이에서 복제본을 옮길 수 있는 스레드 수(디스크 I/O 포함 가능). 기본값은 log.dir/log.dirs에 지정된 디렉토리 수와 같아요. 유형: int / 기본값: null / 중요도: high / 갱신 모드: 읽기 전용
num.replica.fetchers — 각 소스 브로커에서 레코드를 복제하는 데 사용하는 fetcher 스레드 수. 각 브로커의 총 fetcher 수는 num.replica.fetchers × 클러스터의 브로커 수에 묶여요. 값을 늘리면 팔로워·리더 브로커의 I/O 병렬성이 높아지지만 CPU·메모리 사용이 늘어요. 유형: int / 기본값: 1 / 중요도: high / 갱신 모드: cluster-wide
offset.metadata.max.bytes — 오프셋 커밋과 연결된 메타데이터 항목의 최대 크기. 유형: int / 기본값: 4096 (4 kibibytes) / 중요도: high / 갱신 모드: 읽기 전용
offsets.commit.timeout.ms — offsets 토픽의 모든 복제본이 커밋을 받거나 이 타임아웃에 도달할 때까지 오프셋 커밋이 지연돼요. 프로듀서 요청 타임아웃과 비슷해요. 코디네이터가 하는 모든 쓰기에 적용돼요. 유형: int / 기본값: 5000 (5초) / 중요도: high / 갱신 모드: 읽기 전용
offsets.load.buffer.size — 그룹 메타데이터를 캐시에 로드할 때 offsets 세그먼트를 읽는 배치 크기(소프트 한도, 레코드가 너무 크면 무시). 유형: int / 기본값: 5242880 / 중요도: high / 갱신 모드: 읽기 전용
offsets.retention.check.interval.ms — 오래된 오프셋을 검사하는 빈도. 유형: long / 기본값: 600000 (10분) / 중요도: high / 갱신 모드: 읽기 전용
offsets.retention.minutes — 구독 컨슈머의 경우 다음과 같을 때 특정 파티션의 커밋된 오프셋이 만료·폐기돼요: 1) 컨슈머 그룹이 모든 컨슈머를 잃은(즉 비게 된) 뒤 이 보존 기간이 지났거나, 2) 파티션에 오프셋이 커밋된 마지막 시간 이후 이 기간이 지나고 그룹이 해당 토픽을 더 이상 구독하지 않을 때. 독립 컨슈머(수동 할당)는 마지막 커밋 이후 이 보존 기간이 지나면 오프셋이 만료돼요. 그룹 삭제·토픽 삭제 시 커밋된 오프셋도 추가 보존 없이 삭제돼요. 유형: int / 기본값: 10080 / 중요도: high / 갱신 모드: 읽기 전용
offsets.topic.compression.codec — offsets 토픽의 압축 코덱. 압축을 사용해 "원자적" 커밋을 달성할 수 있어요. 유형: int / 기본값: 0 / 중요도: high / 갱신 모드: 읽기 전용
offsets.topic.num.partitions — 오프셋 커밋 토픽의 파티션 수(배포 후 변경하면 안 됨). 유형: int / 기본값: 50 / 중요도: high / 갱신 모드: 읽기 전용
offsets.topic.replication.factor — offsets 토픽의 복제 팩터(가용성 보장을 위해 더 높게 설정). 클러스터 크기가 이 복제 팩터 요구를 충족할 때까지 내부 토픽 생성을 실패해요. 유형: short / 기본값: 3 / 중요도: high / 갱신 모드: 읽기 전용

더 알아보기 (Learn more)

참고: 이 페이지는 broker-configs의 핵심(essential + 중요도 high) 설정을 다뤄요. medium/low 중요도의 토픽·로그·리플리케이션·보안 등 수많은 항목의 전체 목록은 원문을 참고해요.
브로커 설정은 보통 config/server.properties에 들어가고, 중요도에 따라 동적 갱신(클러스터 전역·브로커별)되거나 읽기 전용(재시작 필요)이에요.
로그 보존·세그먼트와 관련된 항목(log.retention.*, log.segment.bytes, log.roll.*)은 운영에서 가장 자주 만지는 값이에요.