DevOps 도구 및 베스트 프랙티스 마스터 - DevOps 지식 허브 DevOps 도구 및 베스트 프랙티스 마스터 - DevOps 지식 허브

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

kafka-topics.sh를 사용하여 Kafka 토픽을 생성, 목록 조회, 설명, 변경 및 삭제하는 방법을 알아보세요.

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

Apache Kafka 토픽은 프로듀서가 레코드를 쓰고 컨슈머가 읽는 곳입니다. 터미널에서 토픽을 생성, 검사, 크기 조정 또는 삭제해야 하는 경우 주요 도구는 kafka-topics.sh입니다.

그래픽 도구도 유용하지만, CLI 명령은 장애나 배포 중에 클러스터가 무엇을 하고 있는지 확인하는 가장 빠른 방법입니다. 이 가이드는 가장 자주 사용하는 토픽 명령을 보여주고 Kafka가 예상치 못한 동작을 할 수 있는 부분을 강조합니다.

전제 조건 및 설정

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

모든 명령은 --bootstrap-server로 지정된 최소 하나의 Kafka 브로커 주소가 필요합니다. 이전 Kafka 클러스터는 여전히 --zookeeper를 사용하는 예제를 보여줄 수 있지만, 브로커 기반 관리는 현재 패턴입니다.

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

# 표준 브로커 주소 자리 표시자
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 \
  --bootstrap-server $BROKER_ADDRESS \
  --partitions 3 \
  --replication-factor 2

팁: 프로덕션에서는 복제 계수 3이 일반적입니다. 이는 각 파티션의 여러 복사본을 다른 브로커에 유지하기 때문입니다. 실제 내결함성은 브로커 배치, min.insync.replicas 및 프로듀서 확인 설정에도 따라 달라집니다.

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 \
  --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): 안전한 장애 조치를 위해 충분히 따라잡은 복제본입니다. ISR이 줄어들면 브로커 상태, 디스크 지연 시간 및 네트워크 지연을 확인하세요.

4. 기존 토픽 변경

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

A. 파티션 증가

파티션은 증가만 가능하며 감소는 불가능합니다. 파티션을 늘리면 컨슈머 병렬 처리를 확장하는 데 도움이 됩니다.

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

sales-data에 현재 3개의 파티션이 있는 경우 5개로 늘릴 수 있습니다:

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

B. 토픽별 구성 변경

kafka-topics.sh --alter --config를 통해 토픽 구성을 변경하는 이전 예제를 볼 수 있습니다. 현재 Kafka 클러스터에서는 동적 구성을 위한 전용 관리 도구이므로 토픽 구성 변경에는 kafka-configs.sh를 선호합니다.

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

kafka-configs.sh --bootstrap-server $BROKER_ADDRESS \
  --alter --entity-type topics --entity-name sales-data \
  --add-config retention.ms=86400000

특정 구성 재정의를 제거하고 브로커 기본값으로 되돌리려면 --delete-config를 사용하세요:

kafka-configs.sh --bootstrap-server $BROKER_ADDRESS \
  --alter --entity-type topics --entity-name sales-data \
  --delete-config retention.ms

5. Kafka 토픽 삭제

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

토픽 삭제 활성화

Kafka 브로커는 이 명령이 데이터를 제거하기 전에 삭제를 허용해야 합니다. 많은 최신 배포에서 활성화되어 있지만 가정하지 마십시오. 브로커 구성에서 다음을 확인하세요:

delete.topic.enable=true

명령 예제: old-stream 삭제

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

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

확인 출력:

Deletion of topic old-stream initiated successfully.

토픽 관리 명령 요약

작업 플래그 목적 예제 매개변수
생성 --create 새 토픽을 초기화합니다. --partitions 5 --replication-factor 3
목록 조회 --list 클러스터의 모든 토픽을 표시합니다. 해당 없음
설명 --describe 현재 구성 및 레이아웃을 봅니다. --topic my-topic
변경 (파티션) --alter 파티션 수를 늘립니다. --partitions N (N > 현재 수)
변경 (구성) kafka-configs.sh --alter 특정 토픽에 대한 브로커 기본값을 재정의합니다. --add-config retention.ms=...
삭제 --delete 토픽을 영구적으로 제거합니다. --topic my-topic

다음 단계

  1. 개발 또는 스테이징 환경에서 이러한 명령을 연습하세요.
  2. 구성 변경 전후에 kafka-configs.sh --describe를 사용하여 어떤 값이 토픽 재정의인지 확인하세요.
  3. 프로듀서 및 컨슈머 테스트를 위한 해당 CLI 명령(kafka-console-producer.sh 및 kafka-console-consumer.sh)을 학습하세요.