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

Kafka 4.2 를 설치하고 수 분 만에 이벤트 스트리밍을 시작하세요.

Page content

Apache Kafka 4.2.0 는 현재 지원되는 릴리스 라인이며, Kafka 4.x 는 완전한 ZooKeeper-free 구조로 KRaft를 기본으로 구축되어 있어 현대적인 Quickstart 를 위한 가장 이상적인 기준선입니다.

이 가이드는 실용적이고 명령줄 중심의 Quickstart 를 제공합니다: Kafka 설치, 로컬 브로커 시작, 필수 Kafka CLI 도구 학습, 그리고 터미널에 복사하여 바로 실행할 수 있는 두 가지 종단 간(end-to-end) 예제로 마무리합니다.

분산 메시지 처리 인포그래픽 아파치 카프카

Apache Kafka 란 무엇이며 어디에 사용되는가

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

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

Kafka 가 광범위한 데이터 인프라에서 어디에 위치하는지에 대한 맥락을 위해, S3 호환 오브젝트 스토리지, PostgreSQL 아키텍처, Elasticsearch 최적화, AI 네이티브 데이터 레이어를 다루는 AI 시스템용 데이터 인프라: 오브젝트 스토리지, 데이터베이스, 검색 및 AI 데이터 아키텍처 Pilar 를 참조하세요.

AWS 를 기반으로 구축 중이며 관리형 대안이 필요하시다면, Kinesis Data Streams 를 사용하여 이벤트 기반 마이크로서비스를 구현하는 방법을 다루는 AWS Kinesis 를 활용한 이벤트 기반 마이크로서비스 구축 을 참조하세요.

운영 측면에서 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 개선 제안서에서는 이를 실험적이며 프로덕션이 아닌 로컬 개발 및 테스트를 위해 의도된 것으로 설명합니다.

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를 비추천하며 대신 --batch-size를 권장합니다.
  • kafka-console-consumer는 --property(포맷터 속성) 를 비추천하고 --formatter-property를 대신 사용합니다.
  • kafka-console-producer는 --property(메시지 리더 속성) 를 비추천하고 --reader-property를 대신 사용합니다.

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

kafka-consumer-groups.sh 를 이용한 컨슈머 지연 확인

실제 시스템에서 “내 컨슈머가 따라오고 있는가?“는 일일 질문입니다. 운영 가이드에서는 다음을 보여줍니다:

  • 그룹 목록: --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

몇 줄을 입력합니다 (각 줄이 이벤트가 됨), 그런 다음 프로듀서를 실행 상태로 둡니다:

이것이 내 첫 번째 이벤트입니다
이것이 내 두 번째 이벤트입니다

터미널 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 외부 (또는 다른 머신) 에 있다면, 올바른 리스너 광고가 필요할 수 있습니다. 브로커 설정 문서는 advertised.listeners가 클라이언트가 연결해야 하는 주소가 바인드 주소 (listeners) 와 다를 때 사용된다고 설명합니다.

Quickstart 이후 갈 곳

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

  • Kafka 가 어디에 사용되는가 (종단 간 이벤트 스트리밍)
  • 로컬에서 Kafka 를 설치하는 방법 (tarball 또는 Docker)
  • ZooKeeper 가 사라지고 4.x 에서 KRaft 가 기본이 된 이유
  • 일상적으로 중요한 CLI 도구 (토픽, 프로듀서, 컨슈머, 그룹)

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

  • Kafka 의 “소개"를 읽어 토픽, 파티션, 복제에 대한 더 깊은 정신 모델을 구축하세요.
  • 첫 번째 처리 애플리케이션을 원한다면 Kafka Streams Quick Start 를 탐색하세요 (Streams Quickstart 는 WordCount 데모 실행 및 콘솔 컨슈머로 결과 검증 방법을 보여줍니다).