[ETC] 카프카 properties 파일 세부 분석

 

카프카야 제발 분리해서 기동해 줘!!

 

1. server-n.properties 분석

# ── 역할 지정 (KRaft)
process.roles=broker,controller
# 이 프로세스가 브로커와 컨트롤러 역할을 동시에 수행한다는 뜻.
# controller-only 또는 broker-only로도 가능(그럴 땐 해당 역할만 기입).

# ── 고유 노드 ID
node.id=1
# 클러스터 내에서 유일해야 함. log.dirs 안의 meta.properties에 저장되며,
# 여기 값과 meta.properties의 node.id가 다르면 부팅 실패.

# ── KRaft 쿼럼(컨트롤러 합의) 멤버
controller.listener.names=CONTROLLER
controller.quorum.voters=1@ctrl-n1:9093,2@ctrl-n2:9094,3@ctrl-n3:9095
# 반드시 "모든 노드에서 문자열이 완전히 동일"해야 한다(스페이스/오탈자 금지).
# 각 항목의 host:port는 아래 listeners에 있는 CONTROLLER 리스너와 정확히 매칭되어야 함.
# NAT/망연계 환경에선 host를 호스트명으로 쓰고 /etc/hosts에서
# 자기 자신은 REAL/localhost, 상대는 NAT로 split-horizon 매핑.

# ── 네트워크 바인딩(소켓을 어디에 열 것인가)
listeners=PLAINTEXT://0.0.0.0:9096,CONTROLLER://0.0.0.0:9093
# "bind 주소"임. 0.0.0.0은 모든 NIC에서 수신 대기.
# 브로커 데이터포트(9096)와 컨트롤러 포트(9093)를 이 프로세스에서 LISTEN.

# ── 외부에 광고되는 주소(상대방이 접속할 대상)
advertised.listeners=PLAINTEXT://broker1-nat:9096
# "상대가 실제 접근할 수 있는 주소"를 적는다. 127.0.0.1 금지(원격에서 못 붙음).
# 망연계 환경이면 NAT IP(또는 NAT용 호스트명)를 사용.
# 컨슘/프로듀스/브로커간 복제는 이 advertised 주소로 접속한다.

# ── 브로커-브로커 통신에 사용할 리스너 선택
inter.broker.listener.name=PLAINTEXT
# listeners에서 정한 '이름' 중에 무엇으로 브로커끼리 통신할지 지정.
# 여기서 지정한 이름은 listener.security.protocol.map에 있어야 한다.

# ── 리스너 이름 ↔ 실제 보안 프로토콜 매핑
listener.security.protocol.map=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
# 나중에 SSL/SASL 쓰면 여기에 SSL/SASL_PLAINTEXT 등으로 추가/변경.

# ── 데이터 디렉터리
log.dirs=/data/kafka/node1
# 이 노드의 실제 로그/세그먼트/메타 저장 위치.
# 각 브로커(노드)마다 절대 다른 경로여야 한다(공유하면 큰일남).
# 권한/용량 확인 필수.

 

2) 각 항목 상세 설명 & 자주 겪는 함정

- process.roles

• 의미: 이 프로세스가 수행할 역할. broker, controller 중 하나 또는 둘 다.
• 주의: controller를 포함하면 반드시 controller.quorum.voters, controller.listener.names 설정 필요.
• 함정 로그:
  • (빠짐) Must configure process.roles when not using ZooKeeper

- node.id

• 의미: 클러스터에서 유일한 정수 ID.
• meta.properties와 일치해야 함. (불일치 시 부팅 실패)
• 점검:
  bin/kafka-storage.sh info -c server-1.properties
• 함정 로그:
  • Stored node id doesn't match previous node id ...

- controller.quorum.voters / controller.listener.names

• 의미: KRaft 합의를 할 컨트롤러 멤버 목록.
  형식: id@host:port를 콤마로 나열.
• 규칙:
  • 모든 노드에서 동일한 문자열 사용(한 글자라도 다르면 안 됨).
  • host:port는 그 노드의 CONTROLLER 리스너와 정확히 일치해야 함.
  • NAT/망연계면 호스트명을 쓰고 /etc/hosts로 split-horizon:
    • 자기 자신은 REAL/localhost로 해석
    • 상대는 NAT IP로 해석
• 함정 로그:
  • Not enough live voters, Timed out waiting for quorum
  • If using process.roles, controller.quorum.voters must contain a parseable set of voters.

- listeners (bind 주소)

• 의미: 소켓을 어디에 열지 지정.
  이름://호스트:포트 (이름은 논리명)
• TIP: 대개 0.0.0.0으로 바인딩해서 모든 NIC에서 수신.
• 주의: 포트 중복/점유 시 바로 실패.
• 함정 로그:
  • BindException: Address already in use

- advertised.listeners (상대방이 접속할 주소)

• 의미: 상대가 접근할 수 있는 주소(브로커가 외부에 자신을 ‘광고’하는 주소)
• 원칙:
  • 127.0.0.1 금지(원격에서 접근 불가 → 자기만 붙음)
  • 망연계면 NAT IP(또는 NAT용 호스트명)를 사용
• 증상(오입력 시):
  • 컨슈머/프로듀서 연결 실패
  • 브로커 등록 타임아웃 (Unable to register the broker because the RPC timed out)

- inter.broker.listener.name

• 의미: 브로커 간 복제/메타 통신에 쓸 리스너 이름 선택.
• 주의: 선택한 이름이 listeners에 존재하고, listener.security.protocol.map에도 매핑돼 있어야 함.

- listener.security.protocol.map

• 의미: 리스너 ‘이름’을 실제 보안프로토콜(PLAINTEXT/SSL/…)에 매핑.
• 주의: 이름 오타/누락 시 부팅 시점에 오류.

- log.dirs

• 의미: 브로커 데이터 저장 위치(세그먼트, 메타 포함).
• 규칙:
  • 브로커마다 서로 다른 디렉터리(node1, node2 …)
  • 퍼미션/용량 충분히 확보
• 함정 로그:
  • No readable meta.properties files found (포맷 전)
  • DuplicateBrokerRegistrationException (같은 log.dirs를 둘이 공유)

 

3) NAT/망연계 환경에서 꼭 기억할 것

• voters 문자열은 모든 노드에서 동일해야 한다.
• CONTROLLER 포트(9093/9094/9095) 는 양방향 TCP가 되어야 합의가 돈다.
• advertised.listeners 는 상대가 실제로 접근 가능한 주소로(127.0.0.1 금지).
• 헤어핀 미지원이면 /etc/hosts로 자기 자신은 REAL/localhost, 상대는 NAT로 split-horizon.

 

4) 올바른지 빠르게 검증하는 루틴

 

# 1) 포트 바인딩
ss -lntp | grep -E ':9093|:9096'

# 2) 쿼럼 상태(리더/유권자)
bin/kafka-metadata-quorum.sh --bootstrap-server <브로커:포트> describe --status

# 3) 브로커 등록/동작 여부(토픽 조회)
bin/kafka-topics.sh --bootstrap-server <브로커:포트> --list

# 4) 네트워크 도달성
nc -vz <상대노드IP또는호스트명> 9093   # 컨트롤러
nc -vz <상대노드IP또는호스트명> 9096   # 브로커

 

 

4) 에러 메시지 ↔ 원인 치트시트

로그 키워드 ( server.log)	원인	조치
Not enough live voters / quorum timeout	컨트롤러 간 포트 미개방/단방향, voters 불일치, 헤어핀 문제	9093/9094/9095 양방향 오픈, voters 통일, /etc/hosts split
Unable to register the broker because the RPC timed out	advertised.listeners가 외부에서 도달 불가, 컨트롤러 불안정	advertised 주소 수정, 컨트롤러 합의부터 안정화
BindException: Address already in use	포트 충돌(이미 점유)	포트 변경 또는 충돌 프로세스 종료
No readable meta.properties files found	포맷 안 함/경로 오타	kafka-storage.sh format, 경로 점검
Stored node id doesn't match ...	node.id와 meta.properties 불일치	log.dirs 정리 후 동일 node.id로 재포맷
DuplicateBrokerRegistrationException	두 브로커가 같은 log.dirs/node.id 사용	디렉터리 분리, node.id 고유 보장

 

카프카야 제발 분리해서 기동해 줘!!