Apache Kafka 빠른 시작 - CLI 및 로컬 예제를 사용하여 Kafka 4.2 설치

Kafka 4.2 를 설치하고 몇 분 안에 이벤트를 스트리밍하세요.

Page content

Apache Kafka 4.2.0 는 현재 지원되는 릴리스 라인이며, Kafka 4.x 는 완전히 ZooKeeper 가 필요 없고 기본적으로 KRaft 를 기반으로 구축되어 있으므로 현대적인 빠른 시작 (Quickstart) 을 위한 최적의 기준선입니다.

이 가이드는 Kafka 설치, 로컬 브로커 시작, 필수 Kafka CLI 도구 학습, 그리고 터미널에 붙여넣어 실행할 수 있는 두 가지 엔드투엔드 예제를 완료하는 실용적이고 명령어 중심의 빠른 시작 가이드입니다.

분산 메시지 처리 인포그래픽 apache kafka

Apache Kafka 란 무엇이며 어디에 사용되나요?

Apache Kafka 는 이벤트 스트리밍 플랫폼입니다. 실용적인 측면에서 이벤트 스트리밍은 소스 (데이터베이스, 센서, 앱) 에서 실시간으로 이벤트 데이터를 수집하고, 결과 스트림을 내구성 있게 저장하며, 실시간 (또는 나중에) 처리하거나 라우팅하는 것을 의미합니다.

Kafka 는 하나의 플랫폼에서 세 가지 핵심 기능을 제공합니다: 이벤트 스트림에 대한 발행 및 구독, 필요한 만큼 스트림을 내구성 있게 저장, 그리고 스트림이 발생하는 대로 또는 사후에 처리하는 것입니다. 이러한 조합은 Kafka 가 실시간 데이터 파이프라인, 통합, 메시징 및 스트리밍 분석에 사용되는 이유입니다.

Kafka 가 더 넓은 데이터 인프라에서 어디에 위치하는지에 대한 맥락은 S3 호환 객체 저장소, PostgreSQL 아키텍처, Elasticsearch 최적화 및 AI 네이티브 데이터 레이어를 다루는 AI 시스템용 데이터 인프라: 객체 저장소, 데이터베이스, 검색 및 AI 데이터 아키텍처 pilar 를 참조하세요.

AWS 를 기반으로 구축 중이며 관리형 대안이 필요한 경우, AWS Kinesis 를 활용한 이벤트 기반 마이크로서비스 구축 를 통해 Kinesis Data Streams 를 활용한 이벤트 기반 마이크로서비스 구현에 대해 확인하세요.

Kafka 와의 상태 있는 스트림 처리에 대해서는 K8s 와 Kafka 상의 Apache Flink: PyFlink, Go, 운영 및 관리형 가격 정책 을 참조하세요.

운영 측면에서 Kafka 는 고성능 TCP 프로토콜을 통해 통신하는 서버와 클라이언트로 구성된 분산 시스템입니다: 브로커는 데이터를 저장하고 제공하며, 클라이언트 (생산자와 소비자) 는 대규규모로 내결함성을 보장하며 이벤트를 쓰고 읽습니다.

CLI 에서 반복적으로 보게 될 몇 가지 개념:

  • **토픽 (Topics)**은 이벤트를 조직합니다. 토픽은 다중 생산자와 다중 구독자를 지원하며, 보존 기간이 오래된 데이터를 언제 폐기할지 제어하기 때문에 이벤트가 여러 번 읽힐 수 있습니다.
  • **파티션 (Partitions)**은 확장성을 위해 토픽을 브로커에 걸쳐 샤딩하며, 파티션별로 순서가 보장됩니다.
  • **복제 계수 (Replication factor)**는 내결함성을 제어합니다. 문서 예시에서는 프로덕션 환경에서 일반적으로 복제 계수 2 또는 3 을 권장하며, 단일 노드 개발 Quickstart 는 일반적으로 1 을 사용합니다.

Apache Kafka 설치

Kafka 의 공식 Quickstart 는 바이너리 릴리스 (tarball) 또는 공식 Docker 이미지를 사용합니다. 둘 다 로컬 개발에 유효합니다.

생략하면 안 되는 필수 요건

Kafka 4.x 는 최신 Java 가 필요합니다: 서버와 도구의 경우 로컬 실행을 위한 기준선은 **Java 17+**이며, Kafka 4.0 은 Java 8 지원을 제거했습니다.

Kafka 를 배우기 위해 설치하는 것이라면, Java 17 또는 21 과 같은 지원되는 JDK 를 목표로 하세요. Kafka 의 Java 지원 페이지에는 Java 17, 21, 25 가 완전히 지원되며, Java 11 은 클라이언트와 스트림과 같은 일부 모듈에만 지원된다고 명시되어 있습니다.

공식 바이너리 릴리스에서 설치

Kafka 4.2.0 의 공식 Quickstart 는 바이너리 배포판을 다운로드하고 압축을 푸는 것에서 시작합니다:

tar -xzf kafka_2.13-4.2.0.tgz
cd kafka_2.13-4.2.0

고급 독자를 위한 참고사항:

  • 파일명의 “2.13"은 Scala 빌드 라인을 반영합니다. Kafka 4.x 바이너리의 경우 Scala 2.13 이 주요 배포 라인이며, Kafka 4.0 은 Scala 2.12 지원을 제거했습니다.
  • 공급망 무결성이 중요하다면, 다운로드 페이지에는 Apache 의 게시된 절차와 KEYS 를 사용하여 다운로드를 검증할 수 있다고 명시되어 있습니다.

Docker 로 설치

Kafka 는 Docker Hub 에서 공식 Docker 이미지를 제공합니다. Quickstart 에서는 Kafka 4.2.0 을 다음과 같이 풀러 실행할 수 있음을 보여줍니다:

docker pull apache/kafka:4.2.0
docker run -p 9092:9092 apache/kafka:4.2.0

또한 “네이티브” 이미지 라인 (GraalVM 네이티브 이미지 기반) 도 있습니다. Kafka 문서와 이 이미지 라인을 위한 Kafka 개선 제안서 (KIP) 는 이를 실험적으로 설명하며, 프로덕션이 아닌 로컬 개발과 테스트를 위해 의도된 것이라고 명시합니다.

Windows 사용자를 위한 플랫폼 참고사항

Kafka 배포판에는 Windows 스크립트 (배치 파일) 가 포함되어 있습니다. Kafka 문서는 역사적으로 Windows 에서 Unix bin/ .sh 스크립트 대신 bin\windows\와 .bat 스크립트를 사용한다고 명시합니다.

KRaft 로 로컬 Kafka 시작

“Apache Kafka 를 실행하려면 ZooKeeper 가 필요한가?“라고 묻는다면, 현대적인 답변은 아닙니다. Kafka 4.0 은 ZooKeeper 없이 완전히 작동하도록 설계된 첫 번째 주요 릴리스이며, 로컬 및 프로덕션 사용에 운영 오버헤드를 줄이기 위해 기본적으로 KRaft 모드로 실행됩니다.

추출된 tarball 에서 단일 노드 로컬 브로커 시작

Kafka 4.2 Quickstart 는 세 가지 명령을 사용합니다:

  1. 클러스터 UUID 생성
  2. 로그 디렉토리 포맷팅
  3. 서버 시작
# 클러스터 UUID 생성
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"

# 로그 디렉토리 포맷팅 (독립 로컬 포맷)
bin/kafka-storage.sh format --standalone -t "$KAFKA_CLUSTER_ID" -c config/server.properties

# Kafka 브로커 시작
bin/kafka-server-start.sh config/server.properties

KRaft 에서 “포맷” 단계가 중요한 이유: Kafka 의 KRaft 운영 문서는 kafka-storage.sh random-uuid가 클러스터 ID 를 생성하고 각 서버가 kafka-storage.sh format으로 포맷되어야 한다고 설명합니다. 제시된 이유 중 하나는 자동 포맷팅이 특히 메타데이터 로그와 관련된 오류를 숨길 수 있으므로 명시적인 포맷팅이 선호된다는 것입니다.

이 Quickstart 에서 실행 중인 것

로컬 개발을 위해 Kafka 는 간소화된 “통합” 설정 (컨트롤러와 브로커가 함께) 으로 실행할 수 있습니다. Kafka 의 KRaft 문서에서는 통합 서버를 개발에는 간단하지만 중요한 배포 환경 (컨트롤러를 격리하고 독립적으로 확장하고 싶은 경우) 에는 권장하지 않는다고 명시합니다.

“실제"클러스터의 경우 KRaft 컨트롤러와 브로커는 별도의 역할 (process.roles) 이며, 컨트롤러는 일반적으로 3 개 또는 5 개의 노드 쿼럼으로 배포됩니다 (가용성은 다수가 살아있는지에 따라 달라짐).

Kafka CLI 필수 사항 및 주요 명령줄 매개변수

Kafka 는 bin/ 아래에 많은 CLI 도구를 함께 제공합니다. 공식 운영 문서는 두 가지 유용한 속성을 강조합니다:

  • 공통 도구는 배포판의 bin/ 디렉토리 아래에 있습니다.
  • 각 도구는 인자가 없을 때 실행하면 전체 명령줄 사용법을 출력합니다.

또한 Kafka 4.x 에 중요합니다: AdminClient 명령은 더 이상 --zookeeper를 받지 않습니다. Kafka 의 호환성 문서는 Kafka 4.0 부터 클러스터와 상호작용하려면 --bootstrap-server를 사용해야 한다고 명시합니다.

자주 사용할 Kafka 연결 플래그

대부분의 도구는 클러스터 진입점이 필요합니다:

  • --bootstrap-server host:port
    토픽 작업, 소비자 그룹 및 대부분의 브로커 명령에 사용합니다. Kafka 4.x 에서 ZooKeeper 기반 관리 워크플로우의 표준 대체 수단입니다.

KRaft 는 일부 도구의 경우 브로커와 컨트롤러 엔드포인트를 소개합니다. 예를 들어, kafka-features.sh와 메타데이터 도구의 일부는 컨트롤러 엔드포인트를 사용할 수 있는 반면, 많은 관리 작업은 브로커 엔드포인트를 사용합니다. KRaft 운영 페이지는 예시에서 두 스타일을 모두 보여줍니다.

kafka-topics.sh 로 토픽 관리

핵수명주기를 위해 kafka-topics.sh를 사용합니다:

  • 토픽 생성, 설명, 목록 (Quickstart 는 --create, --describe, --topic을 보여줍니다).
  • 파티션과 복제 계수를 통해 규모와 내구성을 지정합니다. 운영 가이드는 --partitions와 --replication-factor를 보여주며 이들이 확장성과 내결함성에 미치는 영향을 설명합니다.
  • 생성 시 --config key=value로 토픽별 오버라이드를 추가합니다 (토픽 설정 문서에 구체적인 예시가 있음).

생산적인 “프로덕션 마인드” 생성 명령은 다음과 같습니다 (이 정확한 형태는 공식 운영 문서에서 사용됨):

bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --create --topic my_topic_name \
  --partitions 20 --replication-factor 3 \
  --config x=y

콘솔 클라이언트를 이용한 생산 및 소비

Quickstart 는 검증과 스모크 테스트에 빠르기 때문에 콘솔 생산자와 소비자를 사용합니다:

  • kafka-console-producer.sh --topic ... --bootstrap-server ...
  • kafka-console-consumer.sh --topic ... --from-beginning --bootstrap-server ...

Kafka 4.2 는 또한 CLI 일관성 개선사항을 포함합니다. 업그레이드 노트에서:

  • kafka-console-producer는 --max-partition-memory-bytes를 비추천 (deprecate) 하고 대신 --batch-size를 권장합니다.
  • kafka-console-consumer는 --property(포맷터 속성) 를 비추천하고 대신 --formatter-property를 사용합니다.
  • kafka-console-producer는 --property(메시지 리더 속성) 를 비추천하고 대신 --reader-property를 사용합니다.

내부 런북 (runbooks) 을 관리 중이라면, Kafka 5.0 이 비추천 플래그를 제거하기 전에 이제 이 노트를 업데이트하는 것이 좋습니다.

kafka-consumer-groups.sh 로 소비자 지연 (lag) 검사

실제 시스템에서 “내 소비자가 따라오나요?“는 일일 질문입니다. 운영 가이드는 다음을 시연합니다:

  • 그룹 목록: --list
  • 오프셋과 지연을 포함한 그룹 설명: --describe --group ...
  • 멤버 및 할당 설명: --members와 --verbose
  • 그룹 삭제: --delete
  • 오프셋 안전하게 초기화: --reset-offsets

예시:

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group my-group

로컬 Docker 와 원격 클라이언트를 위한 하나의 설정 주의사항

컨테이너에서 Kafka 를 실행하거나 로드 밸런서 뒤에 있다면, 결국 리스너를 올바르게 설정해야 하는 필요성에 부딪힙니다. Kafka 의 브로커 설정 문서는 advertised.listeners를 클라이언트와 다른 브로커에 브로커가 광고하는 주소로 설명하며, 특히 바인드 주소가 클라이언트가 사용해야 하는 주소와 다를 때 중요합니다.

지금 바로 실행할 수 있는 Quickstart 예제

아래 예제는 의도적으로 CLI 기반이므로 어떤 애플리케이션 코드도 작성하기 전에 로컬 Kafka 설정을 검증할 수 있습니다.

예제: 토픽 실행 및 엔드투엔드 메시지 스트리밍

이는 Kafka 4.2 Quickstart 의 표준 “생성, 생산, 소비” 흐름입니다.

터미널 A 를 열고 토픽을 생성합니다:

bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092

이제 설명합니다 (선택 사항이지만 파티션과 복제 계수를 배울 때 유용함):

bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

터미널 B 를 열고 생산자를 시작합니다:

bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092

몇 줄을 입력합니다 (각 줄은 이벤트가 됨), 그리고 생산자를 실행 중으로 둡니다:

This is my first event
This is my second event

터미널 C 를 열고 처음부터 소비자를 시작합니다:

bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092

동일한 줄이 출력되는 것을 보게 될 것입니다.

이것이 “작동한다"보다 더 많은 것을 검증하는 이유: Kafka 의 Quickstart 는 브로커가 이벤트를 내구성 있게 저장하며, 이벤트가 여러 번 그리고 여러 소비자에 의해 읽힐 수 있음을 설명합니다. 이러한 내구성은 설치나 업그레이드 후에 가장 먼저 해야 할 일이 이 Quickstart 패턴인 이유입니다.

예제: 파일에서 토픽으로 파일로 간단한 Kafka Connect 파이프라인 실행

Kafka Connect 는 “모든 것에 대한 커스텀 생산자와 소비자를 작성하지 않고 Kafka 로 데이터를 어떻게 주고받을 수 있는가"라는 반복되는 질문에 답합니다. Kafka Connect 개요는 이를 커넥터를 통해 Kafka 와 다른 시스템 간 확장 가능하고 신뢰할 수 있는 스트리밍을 위한 도구로 설명합니다.

Kafka 4.2 Quickstart 는 파일 소스와 싱크 커넥터를 사용한 최소한의 로컬 Connect 데모를 포함합니다.

Kafka 디렉토리에서 먼저 워커 플러그인 경로를 제공된 파일 커넥터 JAR 를 포함하도록 설정합니다:

echo "plugin.path=libs/connect-file-4.2.0.jar" >> config/connect-standalone.properties

작은 입력 파일을 생성합니다:

echo -e "foo\nbar" > test.txt

소스와 싱크 커넥터 설정 모두를 사용하여 스탠드론 모드로 Connect 워커를 시작합니다:

bin/connect-standalone.sh \
  config/connect-standalone.properties \
  config/connect-file-source.properties \
  config/connect-file-sink.properties

무엇이 일어나는지 (그리고 왜 유용한지):

  • 소스 커넥터는 test.txt에서 줄을 읽고 토픽 connect-test로 생산합니다.
  • 싱크 커넥터는 connect-test에서 읽고 test.sink.txt에 씁니다.

싱크 파일을 확인합니다:

more test.sink.txt

다음과 같이 보일 것입니다:

foo
bar

토픽을 직접 확인할 수도 있습니다:

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning

이 두 번째 예제는 Connect 설정이 어디에 위치하는지 (워커 설정 및 커넥터 설정) 를 가르치고 최소한의 “수집, 저장, 내보내기” 루프를 보여주기 때문에 훌륭한 근육 기억 훈련이 됩니다.

문제 해결 및 다음 단계

대부분의 “Kafka Quickstart 가 시작되지 않음” 문제는 소수의 근본 원인으로 귀결됩니다.

브로커 시작 실패

공식 요구사항부터 시작합니다:

  • Kafka 4.2 Quickstart 는 명시적으로 **Java 17+**를 요구합니다. 오래된 JDK 를 사용 중이라면 먼저 이를 해결하세요.
  • KRaft 모드에서 저장소 포맷팅은 필요한 명시적인 단계입니다. kafka-storage.sh format을 건너뛰면 시작 실패 또는 메타데이터 오류를 볼 가능성이 높습니다.

실험을 해보고 이제 깨끗한 상태로 다시 시작하고 싶다면, Kafka 의 Quickstart 는 데모에서 사용한 로컬 데이터 디렉토리를 삭제하는 방법을 보여줍니다:

rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs

브로커가 실행 중인데 CLI 명령이 실패

Kafka 4.x 에서 --bootstrap-server(아님 --zookeeper) 를 사용중인지 확인하세요. Kafka 의 호환성 문서는 Kafka 4.0 부터 AdminClient 명령에서 --zookeeper가 제거되었음을 명시적으로 지적합니다.

Docker 네트워킹 놀라움

Kafka 가 Docker 안에 있고 클라이언트 도구가 Docker 밖 (또는 다른 머신) 에 있다면 올바른 리스너 광고가 필요할 수 있습니다. 브로커 설정 문서는 클라이언트가 연결해야 하는 주소가 바인드 주소 (listeners) 와 다를 때 advertised.listeners가 사용됨을 설명합니다.

Quickstart 이후 갈 곳

이 게시물의 예제를 완료했다면, 이미 가장 흔한 첫 검색에 답했습니다:

  • Kafka 의 용도 (엔드투엔드 이벤트 스트리밍)
  • 로컬 Kafka 설치 방법 (tarball 또는 Docker)
  • ZooKeeper 가 사라지고 4.x 에서 KRaft 가 기본이 된 이유
  • 일상적으로 중요한 CLI 도구 (토픽, 생산자, 소비자, 그룹)

여기서부터 가장 가치 있는 다음 단계는 일반적으로 다음과 같습니다:

  • 토픽, 파티션, 복제에 대한 더 깊은 정신 모델을 위해 Kafka 의 “소개"를 읽어보세요.
  • 첫 번째 처리 애플리케이션을 원한다면 Kafka Streams 빠른 시작을 탐색하세요 (Streams Quickstart 는 WordCount 데모 실행과 콘솔 소비자로 결과 검사를 시연합니다).