Kafka 명령줄 도구 이해: CLI 참조 가이드

Apache Kafka는 높은 처리량, 내결함성 및 확장 가능한 실시간 데이터 파이프라인을 지원하는 강력한 분산 이벤트 스트리밍 플랫폼입니다. Kafka는 API를 통해 프로그래밍 방식으로 관리하고 상호 작용할 수 있지만, 명령줄 인터페이스(CLI) 도구는 필수 관리 작업을 수행하고, 토픽을 관리하며, 컨슈머와 상호 작용하고, 클러스터 상태를 모니터링하는 직접적이고 효율적인 방법을 제공합니다. 이 가이드는 가장 일반적으로 사용되는 Kafka CLI 도구에 대한 포괄적인 참조를 제공하며, 각 도구의 목적, 필수 인수 및 실제 사용 사례를 자세히 설명합니다.

이러한 도구를 이해하는 것은 Kafka 관리자, 개발자 및 Kafka 클러스터 관리 또는 문제 해결에 관련된 모든 사람에게 중요합니다. 이 도구들을 통해 간단한 작업을 위해 사용자 지정 스크립트나 애플리케이션을 작성할 필요 없이 신속한 검사, 조작 및 진단을 수행할 수 있습니다.

핵심 Kafka CLI 도구

Kafka 배포판에는 일반적으로 다양한 스크립트와 실행 파일이 포함된 bin/ 디렉토리가 있습니다. 우리는 Kafka를 효과적으로 관리하는 데 가장 자주 사용되는 도구에 중점을 둘 것입니다.

1. kafka-topics.sh

이것은 아마도 가장 자주 사용되는 명령줄 도구일 것입니다. 이를 통해 Kafka 토픽을 생성, 나열, 설명, 삭제, 변경 및 관리할 수 있습니다. 토픽 관리는 Kafka 내에서 데이터 스트림을 구성하는 데 필수적입니다.

일반적인 서브커맨드 및 인수:

• --create: 새 토픽을 생성합니다.
• --list: 클러스터의 모든 토픽을 나열합니다.
• --describe: 특정 토픽에 대한 자세한 정보를 제공합니다.
• --delete: 하나 이상의 토픽을 삭제합니다.
• --alter: 기존 토픽의 구성을 수정합니다.
• --topic <topic_name>: 토픽 이름을 지정합니다.
• --partitions <num_partitions>: 토픽의 파티션 수를 설정합니다 (--create와 함께 사용).
• --replication-factor <factor>: 토픽의 복제 인자를 설정합니다 (--create와 함께 사용).
• --bootstrap-server <host:port>: 연결할 Kafka 브로커를 지정합니다.

예시:

• my_topic이라는 토픽을 3개의 파티션과 복제 인자 2로 생성합니다:
  bash kafka-topics.sh --create --topic my_topic --partitions 3 --replication-factor 2 --bootstrap-server kafka-broker-1:9092,kafka-broker-2:9092

• 클러스터의 모든 토픽을 나열합니다:
  bash kafka-topics.sh --list --bootstrap-server kafka-broker-1:9092

• my_topic이라는 토픽을 설명합니다:
  bash kafka-topics.sh --describe --topic my_topic --bootstrap-server kafka-broker-1:9092
  이것은 파티션, 리더, 복제본 및 ISR(In-Sync Replicas)과 같은 세부 정보를 보여줍니다.

• old_topic이라는 토픽을 삭제합니다:
  bash kafka-topics.sh --delete --topic old_topic --bootstrap-server kafka-broker-1:9092
  참고: 토픽 삭제는 Kafka 브로커 구성(delete.topic.enable=true)에서 활성화되어야 합니다.

2. kafka-console-producer.sh

이 도구를 사용하면 표준 입력에서 Kafka 토픽으로 메시지를 보낼 수 있습니다. 이는 프로듀서 테스트, 샘플 데이터 주입 또는 수동 메시지 게시를 위해 매우 유용합니다.

일반적인 인수:

• --topic <topic_name>: 대상 토픽을 지정합니다.
• --bootstrap-server <host:port>: 연결할 Kafka 브로커를 지정합니다.
• --property <key>=<value>: 프로듀서 속성을 설정할 수 있습니다 (예: key.serializer, value.serializer).
• --producer-property <key>=<value>: --property와 유사하지만 프로듀서 측 구성에만 해당합니다.

예시:

• my_topic으로 메시지를 보냅니다:
  bash kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092
  이것을 실행한 후 한 줄씩 메시지를 입력할 수 있습니다. Ctrl+C를 눌러 종료합니다.

• 키와 함께 메시지를 보냅니다 (JSON 형식):
  bash kafka-console-producer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property parse.key=true --property key.separator=':'
  이제 key:value 쌍을 입력할 수 있으며, Kafka는 지정된 키로 메시지를 보냅니다.

3. kafka-console-consumer.sh

이 도구는 하나 이상의 Kafka 토픽을 구독하고 수신한 메시지를 표준 출력으로 인쇄합니다. 컨슈머 테스트, 토픽의 데이터 검사 및 프로듀서/컨슈머 애플리케이션 디버깅에 필수적입니다.

일반적인 인수:

• --topic <topic_name>: 소비할 토픽을 지정합니다.
• --bootstrap-server <host:port>: 연결할 Kafka 브로커를 지정합니다.
• --group-id <group_id>: 컨슈머 그룹 ID를 지정합니다. 이는 오프셋 관리 및 여러 컨슈머가 소비 부하를 공유할 수 있도록 하는 데 중요합니다.
• --from-beginning: 토픽 로그의 시작부터 메시지를 읽습니다.
• --offset <offset>: 특정 오프셋부터 소비를 시작합니다.
• --partition <partition_id>: 특정 파티션에서 소비합니다.
• --property <key>=<value>: 컨슈머 속성을 설정할 수 있습니다 (예: value.deserializer).

예시:

• my_topic의 모든 메시지를 소비합니다:
  bash kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092

• 컨슈머 그룹 my_group을 위해 my_topic의 시작부터 메시지를 소비합니다:
  bash kafka-console-consumer.sh --topic my_topic --group-id my_group --from-beginning --bootstrap-server kafka-broker-1:9092

• 오프셋 및 키가 인쇄된 메시지를 소비합니다:
  bash kafka-console-consumer.sh --topic my_topic --bootstrap-server kafka-broker-1:9092 --property print.key=true --property key.separator="\t" --property print.offset=true --property print.headers=true

4. kafka-consumer-groups.sh

이 도구는 컨슈머 그룹을 관리하고 검사하는 데 사용됩니다. 컨슈머 랙 이해, 파티션 재할당 및 소비 문제 해결에 필수적입니다.

일반적인 서브커맨드 및 인수:

• --list: 클러스터의 모든 컨슈머 그룹을 나열합니다.
• --describe: 랙을 포함하여 특정 컨슈머 그룹에 대한 세부 정보를 제공합니다.
• --bootstrap-server <host:port>: 연결할 Kafka 브로커를 지정합니다.
• --group <group_id>: 컨슈머 그룹 ID를 지정합니다.
• --reset-offsets: 컨슈머 그룹의 오프셋을 재설정합니다.
• --topic <topic_name>: 오프셋 재설정을 위한 토픽을 지정합니다.
• --to-earliest: 오프셋을 가장 초기의 사용 가능한 메시지로 재설정합니다.
• --to-latest: 오프셋을 가장 최근의 사용 가능한 메시지로 재설정합니다.
• --execute: 오프셋 재설정 작업을 실행합니다.

예시:

• 모든 컨슈머 그룹을 나열합니다:
  bash kafka-consumer-groups.sh --list --bootstrap-server kafka-broker-1:9092

• 컨슈머 그룹 my_group을 설명하고 랙을 보여줍니다:
  bash kafka-consumer-groups.sh --describe --group my_group --bootstrap-server kafka-broker-1:9092
  출력은 토픽, 파티션, 현재 오프셋, 로그 끝 오프셋 및 랙을 보여줍니다.

• my_topic에 있는 my_group의 오프셋을 가장 초기의 사용 가능한 메시지로 재설정합니다:
  bash kafka-consumer-groups.sh --group my_group --topic my_topic --reset-offsets --to-earliest --execute --bootstrap-server kafka-broker-1:9092
  이 명령은 컨슈머가 메시지를 읽기 시작하는 위치에 영향을 미치므로 주의해서 사용하십시오.

5. kafka-log-dirs.sh

이 도구는 Kafka 브로커의 로그 디렉토리를 검사하는 데 도움이 됩니다. 디스크 사용량을 이해하고 토픽 데이터를 찾는 데 유용할 수 있습니다.

일반적인 인수:

• --bootstrap-server <host:port>: 연결할 Kafka 브로커를 지정합니다.
• --topic <topic_name>: 특정 토픽의 디렉토리만 표시하도록 출력을 필터링합니다.

예시:

• 브로커의 로그 디렉토리를 나열합니다:
  bash kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092

• 특정 토픽의 로그 디렉토리를 보여줍니다:
  bash kafka-log-dirs.sh --bootstrap-server kafka-broker-1:9092 --topic my_topic

6. kafka-preferred-replica-election.sh

이 스크립트는 토픽에 대한 선호 복제본 선거를 시작합니다. 선호 복제본은 복제 인자를 기반으로 파티션의 리더로 선택되는 브로커입니다. 브로커가 실패하고 선호되지 않는 복제본이 리더가 되는 경우, 이 도구를 사용하여 리더십을 선호 복제본으로 다시 옮길 수 있습니다.

일반적인 인수:

• --topic <topic_name>: 선호 복제본을 선출할 토픽을 지정합니다.
• --broker-list <broker_id1,broker_id2,...>: 쉼표로 구분된 브로커 ID 목록을 지정합니다.
• --bootstrap-server <host:port>: 연결할 Kafka 브로커를 지정합니다.

예시:

• my_topic에 대한 선호 복제본을 선출합니다:
  bash kafka-preferred-replica-election.sh --topic my_topic --bootstrap-server kafka-broker-1:9092

• 여러 토픽에 대한 선호 복제본을 선출합니다:
  bash kafka-preferred-replica-election.sh --topic topic1,topic2 --bootstrap-server kafka-broker-1:9092

중요한 고려 사항 및 모범 사례

• --bootstrap-server가 핵심: 항상 올바른 --bootstrap-server 인수를 지정하여 Kafka 클러스터에 연결해야 합니다. 일반적으로 이는 브로커의 호스트:포트의 쉼표로 구분된 목록입니다.
• 환경: 이러한 명령은 일반적으로 Kafka 설치의 bin/ 디렉토리에서 찾을 수 있습니다. 이 디렉토리로 이동하거나 Kafka의 bin 디렉토리가 시스템의 PATH에 있는지 확인해야 합니다.
• 권한: 이 명령을 실행하는 사용자가 Kafka 브로커에 도달하는 데 필요한 네트워크 액세스 권한을 가지고 있는지 확인하십시오.
• 구성: 많은 CLI 도구는 --property 또는 --producer-property/--consumer-property 인수를 통해 Kafka 클라이언트 구성을 받아들일 수 있습니다. 이는 기본 직렬화기/역직렬화기를 재정의하거나 다른 특정 클라이언트 구성을 설정하는 데 유용합니다.
• 보안: 보안 Kafka 클러스터(예: SSL/TLS 또는 SASL 인증 포함)의 경우, 이러한 도구에 추가 보안 관련 인수(예: 클라이언트 속성 파일을 가리키는 --command-config)를 전달해야 합니다.
• 토픽 삭제: 토픽 삭제는 중요한 작업이며 Kafka 브로커의 server.properties 파일에서 delete.topic.enable=true를 사용하여 명시적으로 활성화해야 합니다.

결론

Kafka의 명령줄 도구는 Kafka 클러스터를 관리하고 상호 작용하기 위한 강력하고 접근하기 쉬운 인터페이스를 제공합니다. kafka-topics.sh, kafka-console-producer.sh, kafka-console-consumer.sh 및 kafka-consumer-groups.sh와 같은 도구를 마스터하는 것은 효율적인 Kafka 운영, 문제 해결 및 개발에 필수적입니다. 이 도구들의 인수와 사용 사례를 이해함으로써 워크플로우를 크게 간소화하고 이벤트 스트리밍 인프라에 대한 더 깊은 통찰력을 얻을 수 있습니다.

이러한 명령을 정기적으로 참조하면 일상적인 관리 작업을 수행하는 데 도움이 될 뿐만 아니라 문제를 보다 효과적으로 진단하고 해결할 수 있는 역량을 강화할 수 있습니다. Kafka에 더 익숙해짐에 따라 bin/ 디렉토리에 있는 다른 유틸리티 스크립트를 탐색하여 더 고급 작업을 수행할 수 있습니다.