명령줄을 사용하여 Kafka 토픽을 생성하고 관리하는 방법

명령줄을 사용하여 Kafka 토픽 생성 및 관리 방법

Apache Kafka는 높은 처리량의 데이터 파이프라인, 실시간 분석 및 마이크로서비스 통신에 자주 활용되는 분산 이벤트 스트리밍 플랫폼입니다. Kafka 내의 기본적인 조직 단위는 토픽이며, 이는 레코드가 게시되는 카테고리 또는 피드 이름입니다.

그래픽 도구가 존재하지만, Kafka 인프라와 상호 작용하고 관리하는 가장 강력하고 신뢰할 수 있으며 일반적인 방법은 명령줄 인터페이스(CLI)를 직접 사용하는 것입니다. 이러한 필수 명령을 숙달하는 것은 건강하고 효율적인 Kafka 클러스터를 유지 관리할 책임이 있는 관리자와 개발자에게 중요합니다. 이 가이드는 kafka-topics.sh 스크립트를 사용하여 가장 일반적인 토픽 관리 작업을 수행하는 방법에 대한 단계별 튜토리얼을 제공합니다.

사전 요구 사항 및 설정

이 가이드의 명령을 실행하려면 Kafka 바이너리가 설치된 머신에 액세스할 수 있어야 합니다. 모든 토픽 관리 작업은 일반적으로 Kafka 설치의 bin 디렉터리에 있는 kafka-topics.sh 유틸리티를 사용하여 수행됩니다.

모든 명령은 --bootstrap-server 플래그를 사용하여 지정된 하나 이상의 Kafka 브로커 주소를 필요로 합니다. 이전 Kafka 버전(2.2 이전)을 사용하는 경우 --zookeeper 플래그에 계속 의존할 수 있지만, --bootstrap-server가 권장되는 최신 표준입니다.

아래 예제에서는 브로커가 기본 포트에서 로컬로 실행 중이라고 가정합니다.

# 표준 브로커 주소 자리표시자
BROKER_ADDRESS="localhost:9092"

1. 새 Kafka 토픽 생성

토픽을 생성하려면 토픽 이름과 토픽의 동작 및 내결함성을 결정하는 두 가지 중요한 매개변수인 파티션 수와 복제 계수를 정의해야 합니다.

필수 매개변수

--topic <name>: 토픽의 이름.
--partitions <N>: 토픽이 분할될 파티션 수. 파티션은 토픽 내에서 병렬 처리 및 순서의 단위입니다.
--replication-factor <N>: 다른 브로커에 걸쳐 유지될 데이터 복사본 수. 복제 계수가 1이면 중복성이 없습니다.

명령 예시: `sales-data` 생성

이 명령은 3개의 파티션과 복제 계수 2(클러스터 전반에 걸쳐 모든 파티션의 복사본이 2개 존재함을 의미)를 가진 sales-data라는 토픽을 생성합니다.

kafka-topics.sh --create --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --partitions 3 \n  --replication-factor 2

팁: N개의 브로커가 있는 프로덕션 환경에서는 고가용성을 위해 복제 계수 3이 종종 권장되며(두 브로커 손실까지 데이터 손실 방지), 파티션 수는 예상 처리량과 소비자 병렬 처리 요구 사항에 따라 조정되어야 합니다.

2. 모든 토픽 나열

Kafka 클러스터에서 현재 사용 가능한 모든 토픽을 보려면 --list 플래그를 사용합니다.

명령 예시

kafka-topics.sh --list --bootstrap-server $BROKER_ADDRESS

출력 예시:

sales-data
logistics-stream
__consumer_offsets

3. 토픽 구성 설명

특정 토픽에 대한 기존 구성, 파티션 수 및 브로커 할당을 확인하는 것은 문제 해결 및 확인에 필수적입니다. --describe 플래그를 사용합니다.

명령 예시: `sales-data` 설명

kafka-topics.sh --describe --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS

출력 해석:

출력은 토픽 수준과 파티션 수준 모두에서 구성을 보여줍니다.

Topic: sales-data  PartitionCount: 3 ReplicationFactor: 2 Configs:
  Topic: sales-data  Partition: 0 Leader: 1 Replicas: 1,2 Isr: 1,2
  Topic: sales-data  Partition: 1 Leader: 2 Replicas: 2,0 Isr: 2,0
  Topic: sales-data  Partition: 2 Leader: 0 Replicas: 0,1 Isr: 0,1

Leader: 현재 해당 파티션의 읽기/쓰기를 처리하는 브로커.
Replicas: 해당 파티션의 복사본을 보유하고 있는 브로커 목록.
Isr (In-Sync Replicas): Leader와 완전히 동기화된 레플리카의 하위 집합. 고가용성을 위해서는 Leader가 ISR에 있어야 합니다.

4. 기존 토픽 변경

Kafka는 생성 후 토픽을 변경하기 위한 제한적인 메커니즘을 제공합니다. 가장 일반적인 두 가지 변경 작업은 파티션 수 증가 및 기본 브로커 구성 설정 재정의입니다.

A. 파티션 수 증가

파티션은 증가만 가능하며, 감소될 수 없습니다. 파티션 수를 늘리면 소비자 병렬 처리를 확장하는 데 도움이 됩니다.

경고: 파티션 수를 늘리면 메시지가 파티션에 매핑(해싱)되는 방식이 변경됩니다. 프로듀서가 키 기반 순서 보장에 의존하는 경우, 파티션 수를 늘리면 기존 키에 대한 순서 있는 전달이 깨질 수 있습니다.

sales-data가 현재 3개의 파티션을 가지고 있다면, 5개로 늘릴 수 있습니다.

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --partitions 5

B. 토픽별 구성 변경

--config 플래그를 사용하여 개별 토픽에 대해 전역 브로커 설정(예: 메시지 보존 시간 또는 정리 정책)을 재정의할 수 있습니다.

예시: sales-data에 대해 메시지 보존 시간을 24시간(86400000밀리초)으로 설정합니다.

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROKER_ADDRESS \n  --config retention.ms=86400000

특정 구성 재정의를 제거하고 기본 브로커 설정으로 되돌리려면 --delete-config 플래그를 사용합니다.

kafka-topics.sh --alter --topic sales-data \n  --bootstrap-server $BROROKER_ADDRESS \n  --delete-config retention.ms

5. Kafka 토픽 삭제

더 이상 사용하지 않는 토픽은 디스크 공간을 회수하고 클러스터 위생을 유지하기 위해 적절히 삭제해야 합니다.

토픽 삭제 활성화

기본적으로 Kafka 브로커는 안전을 위해 토픽 삭제를 비활성화할 수 있습니다. 토픽을 삭제하기 전에 모든 브로커의 server.properties 파일에서 다음 설정이 활성화되어 있는지 확인하십시오.

delete.topic.enable=true

명령 예시: `old-stream` 삭제

--delete 플래그를 사용하여 토픽 제거를 시작합니다. 토픽 삭제는 종종 비동기적이므로, 명령은 요청을 제출하고 삭제는 백그라운드에서 이루어집니다.

kafka-topics.sh --delete --topic old-stream \n  --bootstrap-server $BROKER_ADDRESS

확인 출력:

Deletion of topic old-stream initiated successfully.

토픽 관리 명령 요약

작업	플래그	목적	예시 매개변수
생성	`--create`	새 토픽 초기화.	`--partitions 5 --replication-factor 3`
나열	`--list`	클러스터의 모든 토픽 표시.	N/A
설명	`--describe`	현재 구성 및 레이아웃 보기.	`--topic my-topic`
변경 (파티션)	`--alter`	파티션 수 증가.	`--partitions N` (N > 현재 개수)
변경 (구성)	`--alter --config`	특정 토픽에 대한 브로커 기본값 재정의.	`--config retention.ms=...`
삭제	`--delete`	토픽 영구 제거.	`--topic my-topic`

결론 및 다음 단계

명령줄은 Kafka 클러스터를 관리하기 위한 가장 강력하고 유연한 인터페이스로 남아 있습니다. kafka-topics.sh 유틸리티를 숙달함으로써 토픽 생성 매개변수, 구성 재정의, 그리고 삭제 및 설명과 같은 필수 관리 작업에 대한 세분화된 제어 권한을 얻게 됩니다.

다음 단계:

개발 또는 스테이징 환경에서 이 명령을 연습하십시오.
--describe 명령을 사용하여 고급 구성 옵션(예: cleanup.policy, max.message.bytes)의 전체 목록을 확인하십시오.
프로듀서 및 컨슈머 테스트를 위한 해당 CLI 명령(kafka-console-producer.sh 및 kafka-console-consumer.sh)을 배우십시오.