Kafka KRaft 모드 운영 시 필수적인 클러스터, 스토리지, 메타데이터 관리 명령어를 정리했습니다.
kafka-cluster.sh, kafka-storage.sh, kafka-log-dirs.sh, kafka-metadata-quorum.sh 도구 활용을 소개 합니다.
Kafka KRaft 명령어 예제 정리: Cluster, Storage, Metadata
목차
1. kafka-cluster.sh 명령어
◆ 클러스터 ID 조회
1. 클러스터 ID 조회
kafka-cluster.sh cluster-id --bootstrap-server localhost:9092
2. 결과 예시
Cluster ID: nXyz1234ABC56789defG
◆ 브로커 등록 해제:
1. 브로커 등록 해제
kafka-cluster.sh unregister --bootstrap-server localhost:9092 --broker-id 2
2. 설명
--broker-id 2 : 브로커 ID가 2인 브로커를 클러스터에서 제거
주의!: 브로커를 등록 해제하면 해당 브로커는 클러스터에서 더 이상 사용할 수 없음
2. kafka-storage.sh 명령어
kafka-storage.sh는 Kafka 스토리지(로그 디렉토리) 관리와 관련된 작업을 수행하는 도구입니다.
Kafka의 로그 디렉토리를 확인하거나 초기화할 때 사용됩니다.
◆ Kafka 로그 디렉토리 정보 확인
1. 로그 디렉토리 정보 확인
./kafka-storage.sh info --config ../config/kraft/server.properties
2. 출력예시
Found log directory:
/home/kafka/kafka_2.13-3.9.0/data
Found metadata: {cluster.id=NOgQ3G41T96rqFL6y4FZJA, directory.id=XHGaRy_OlpDfqWQJUv-lzw, node.id=1, version=1}
◆ Kafka 로그 디렉토리 포맷
1. 로그 디렉토리 포맷(초기화)
./kafka-storage.sh format \
-t $KAFKA_CLUSTER_ID \
-c ../config/kraft/server.properties
2. 설명
Kafka 저장소를 초기화하여 클러스터를 재설정
--config <설정파일>: 설정 파일 지정 (클러스터 ID 포함)
--cluster-id <클러스터 ID>: 클러스터 ID 명시 (없으면 새로 생성 필요)
◆ 랜덤 UUID 생성(클러스터 ID생성)
1. 랜덤 UUID 생성
kafka-storage.sh random-uuid
2. 출력예시
E-cXDxzgQjS1FVZ2BjCkTg
3. kafka-log-dirs.sh 명령어|
Kafka의 로그 디렉토리(log directory) 사용량 및 저장 상태를 조회하는 명령어입니다.
특정 브로커나 토픽에 대한 로그 디렉토리 정보를 확인할 수 있습니다.
◆ 전체 브로커의 로그 디렉토리 상태 조회
1. 명령문 예시
kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe
2. 설명
Kafka 클러스터 내 모든 브로커의 로그 디렉토리 정보 출력
각 브로커에 저장된 파티션 크기, 사용량, 복제본 정보 확인 가능
◆ 특정 브로커(예: ID 1과 2)의 로그 디렉토리 상태 조회
1. 명령문 예시
kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe --broker-list 1,2
2. 설명
브로커 1과 2에서 저장된 로그 정보만 조회
◆ 특정 토픽(예: my-topic)의 로그 디렉토리 상태 조회
kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe --topic-list my-topic
◆ 특정 브로커(1번)에서 특정 토픽(orders)의 로그 디렉토리 상태 조회
kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe \
--broker-list 1 \
--topic-list orders
4. kafka-metadata-quorum.sh 명령어
Kafka에서 KRaft 모드를 사용하는 경우, 메타데이터 투표 상태를 조회하고 컨트롤러를 추가/제거하는 명령어입니다.
| 옵션 | 설명 |
| --bootstrap-server <호스트:포트> | Kafka 클러스터에 연결 |
| --bootstrap-controller <호스트:포트> | Kafka 컨트롤러에 직접 연결 |
| --command-config <설정 파일> | Admin Client 설정 파일 지정 |
| describe --status | 현재 KRaft 메타데이터 투표 상태 조회 |
| describe --replication | 컨트롤러의 복제 상태 확인 |
| add-controller --controller-id <ID> | 특정 컨트롤러 추가 |
| remove-controller --controller-id <ID> | 특정 컨트롤러 제거 |
◆ KRaft 메타데이터 투표 상태 확인
- 현재 Kafka KRaft 클러스터의 메타데이터 투표 상태를 조회 합니다.
- 어떤 노드가 리더(Leader)이며, 팔로워(Follower) 노드가 어떻게 동작하는지를 확인합니다.
1. 명령문
kafka-metadata-quorum.sh --bootstrap-server 192.168.56.101:9092 describe --status
2. 출력 예
ClusterId: NOgQ3G41T96rqFL6y4FZJA
LeaderId: 1
LeaderEpoch: 46
HighWatermark: 889767
MaxFollowerLag: 0
MaxFollowerLagTimeMs: 0
CurrentVoters: [{"id": 1, "directoryId": null, "endpoints": ["CONTROLLER://192.168.56.101:9093"]},
{"id": 2, "directoryId": null, "endpoints": ["CONTROLLER://192.168.56.102:9093"]},
{"id": 3, "directoryId": null, "endpoints": ["CONTROLLER://192.168.56.103:9093"]}]
CurrentObservers: []
3. 설명
ClusterId: KRaft 클러스터 ID
LeaderId: 현재 리더 컨트롤러 ID (1)
LeaderEpoch: 현재 리더의 선출 횟수 (46)
HighWatermark: Kafka가 가장 최근에 커밋한 오프셋 (889767)
MaxFollowerLag: 가장 뒤쳐진 팔로워의 오프셋 지연 (0이면 동기화 완료)
CurrentVoters: 현재 투표 가능한 컨트롤러 목록 (1,2,3)
CurrentObservers: 현재 참관자 컨트롤러(Observer) 목록 (없음)
◆ 컨트롤러 복제 상태 확인
describe --replication 실행 후 Lag 값이 크다면 브로커 간 네트워크 지연이 있거나 컨트롤러 장애 가능성 존재합니다.
1. 명령문
kafka-metadata-quorum.sh --bootstrap-server 192.168.56.101:9092 describe --replication
2.출력 예시
NodeId DirectoryId LogEndOffset Lag LastFetchTimestamp LastCaughtUpTimestamp Status
1 AAAAAAAAAAAAAAAAAAAAAA 889792 0 1742361223666 1742361223666 Leader
2 AAAAAAAAAAAAAAAAAAAAAA 889791 1 1742361223630 1742361223144 Follower
3 AAAAAAAAAAAAAAAAAAAAAA 889791 1 1742361223630 1742361223142 Follower
3. 설명
NodeId: 컨트롤러 ID (1, 2, 3)
LogEndOffset: 컨트롤러가 기록한 최신 로그 위치 (889792, 889791)
Lag: 로그 복제 지연량 (0이면 동기화 완료, 1이면 1개의 로그가 밀려 있음)
LastFetchTimestamp: 컨트롤러가 마지막으로 로그를 가져온 시간
LastCaughtUpTimestamp: 컨트롤러가 마지막으로 동기화된 시간
Status: 현재 컨트롤러의 역할 (Leader, Follower)
◆ 컨트롤러 추가/삭제
1. Controller 추가
kafka-metadata-quorum.sh --bootstrap-server 192.168.56.101:9092 \
add-controller \
--controller-id 4
2. Controller 삭제
kafka-metadata-quorum.sh --bootstrap-server 192.168.56.101:9092 \
remove-controller \
--controller-id 3- 컨트롤러 추가 시 기존 컨트롤러(1,2,3)의 server.properties는 자동으로 변경되지 않음.
- 기존 컨트롤러에서도 controller.quorum.voters를 수동으로 업데이트 후 Kafka를 재시작해야 함.
Kafka KRaft 모드 클러스터 운영에 필요한 주요 명령어를 예제와 함께 정리했습니다. 클러스터 ID 확인, 로그 디렉토리 초기화, 메타데이터 투표 상태 및 컨트롤러 복제 상태 확인, 컨트롤러 추가/삭제까지 포함 합니다.
관련 글 링크
13.Kafka 명령어 예제 정리: Topic, Producer, Consumer
4. Kafka 클러스터 다중 파티션 구성 이해: 고가용성과 장애복구
3. Kafka 단일 파티션 기반 리더-팔로워 동작 원리: 장애복구
'1.시스템&인프라 > Apache Kafka' 카테고리의 다른 글
| 16. Kafka AdminClient API 예제: Topic,Cluster,ConsumerGroups (0) | 2025.04.03 |
|---|---|
| 15. Kafka UI 관리도구 AKHQ 설치 및 설정 하기: 사용자 인증 (0) | 2025.04.01 |
| 13.Kafka 명령어 예제 정리: Topic, Producer, Consumer (0) | 2025.03.31 |
| 12. Kafka KRaft 모드 장애복구 및 증설 테스트 (Controller 3, Broker 3) (0) | 2025.03.31 |
| 11. Kafka 3.9 노드 구성별 server.properties 예시: KRaft 모드 (0) | 2025.03.31 |