빠른 시작
빠른 시작 (Quick Start)
Kafka를 직접 설치하고 토픽을 만들고, 이벤트를 쓰고 읽고, Connect와 Streams까지 한 번에 경험해 보는 실습 가이드예요. 따라 하다 보면 Kafka가 실제로 어떻게 돌아가는지 손으로 익힐 수 있어요.
출처: 문서
본문
1단계: Kafka 받기
최신 Kafka 릴리스를 다운로드하고 압축을 풀어요.
$ tar -xzf kafka_2.13-4.3.1.tgz
$ cd kafka_2.13-4.3.1
2단계: Kafka 환경 시작하기
참고: 로컬 환경에 Java 17+가 설치되어 있어야 해요.
Kafka는 로컬 스크립트와 다운로드 파일, 또는 Docker 이미지로 실행할 수 있어요.
다운로드한 파일 사용하기
클러스터 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
Kafka 서버가 성공적으로 시작되면, 바로 사용할 수 있는 기본 Kafka 환경이 준비돼요.
JVM 기반 Apache Kafka Docker 이미지 사용하기
Docker 이미지를 받아요.
$ docker pull apache/kafka:4.3.1
Kafka Docker 컨테이너를 시작해요.
$ docker run -p 9092:9092 apache/kafka:4.3.1
GraalVM 기반 네이티브 Apache Kafka Docker 이미지 사용하기
Docker 이미지를 받아요.
$ docker pull apache/kafka-native:4.3.1
Kafka Docker 컨테이너를 시작해요.
$ docker run -p 9092:9092 apache/kafka-native:4.3.1
3단계: 이벤트를 저장할 토픽 만들기
Kafka는 여러 머신에 걸쳐 이벤트를 읽고 쓰고 저장하고 처리할 수 있게 해주는 분산 이벤트 스트리밍 플랫폼이에요. 예시 이벤트로는 결제 거래, 모바일 폰의 지리적 위치 갱신, 배송 주문, IoT 기기나 의료 장비의 센서 측정 등이 있어요. 이 이벤트들은 토픽으로 정리되어 저장돼요. 매우 단순하게 말하면 토픽은 파일시스템의 폴더와 비슷하고, 이벤트는 그 폴더 안의 파일이에요.
그래서 첫 이벤트를 쓰기 전에 먼저 토픽을 만들어야 해요. 다른 터미널 세션을 열고 다음을 실행해요.
$ bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092
Kafka의 모든 커맨드라인 도구에는 추가 옵션이 있어요 — kafka-topics.sh 명령을 인자 없이 실행하면 사용법 정보를 보여줘요. 예를 들어 새 토픽의 파티션 수 같은 세부 사항도 보여줄 수 있어요.
$ bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092
Topic: quickstart-events TopicId: NPmZHyhbR9y00wMglMH2sg PartitionCount: 1 ReplicationFactor: 1 Configs:
Topic: quickstart-events Partition: 0 Leader: 0 Replicas: 0 Isr: 0
4단계: 토픽에 이벤트 쓰기
Kafka 클라이언트는 네트워크를 통해 Kafka 브로커와 통신해 이벤트를 쓰거나 읽어요. 브로커는 받은 이벤트를 필요한 만큼(영원히도) 내구성 있고 장애 허용적으로 저장해요.
콘솔 프로듀서 클라이언트를 실행해 토픽에 몇 개의 이벤트를 써볼게요. 기본적으로 입력하는 각 줄이 토픽에 쓰이는 별도의 이벤트가 돼요.
$ bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092
>This is my first event
>This is my second event
언제든 Ctrl-C로 프로듀서 클라이언트를 중지할 수 있어요.
5단계: 이벤트 읽기
다른 터미널 세션을 열고 콘솔 컨슈머 클라이언트를 실행해 방금 만든 이벤트를 읽어요.
$ bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092
This is my first event
This is my second event
언제든 Ctrl-C로 컨슈머 클라이언트를 중지할 수 있어요. 자유롭게 실험해 보세요 — 예를 들어 프로듀서 터미널(이전 단계)로 돌아가 추가 이벤트를 쓰고, 이벤트가 컨슈머 터미널에 즉시 나타나는지 확인해 보세요. 이벤트는 Kafka에 내구성 있게 저장되므로 원하는 만큼 여러 번, 여러 컨슈머가 읽을 수 있어요. 다른 터미널 세션을 하나 더 열고 이전 명령을 다시 실행해 보면 쉽게 확인할 수 있어요.
6단계: Kafka Connect로 데이터를 이벤트 스트림으로 가져오고 내보내기
관계형 데이터베이스나 전통적인 메시징 시스템 같은 기존 시스템에는 아마 데이터가 많을 거예요. 그 시스템을 이미 쓰는 애플리케이션도 많죠. Kafka Connect는 외부 시스템에서 Kafka로 데이터를 지속적으로 수집하고, 그 반대 방향도 가능하게 해줘요. 커넥터(connector)를 실행하는 확장 가능한 도구로, 커넥터가 외부 시스템과 상호작용하는 커스텀 로직을 구현해요. 그래서 기존 시스템을 Kafka와 통합하기가 매우 쉬워요. 게다가 이 과정을 더 쉽게 하려고 수백 개의 커넥터가 이미 준비되어 있어요.
이 퀵스타트에서는 파일에서 Kafka 토픽으로 데이터를 가져오고, Kafka 토픽에서 파일로 데이터를 내보내는 단순한 커넥터로 Kafka Connect를 실행하는 법을 볼게요.
먼저 Connect 워커 설정의 plugin.path 속성에 connect-file-4.3.1.jar을 추가해요. 이 퀵스타트에서는 상대 경로를 사용하고 커넥터 패키지를 uber jar로 간주하는데, 퀵스타트 명령을 설치 디렉토리에서 실행하면 동작해요. 다만 프로덕션 배포에서는 절대 경로를 쓰는 게 항상 더 낫다는 점을 알아두세요. plugin.path에서 이 config 설정 방법을 자세히 볼 수 있어요.
config/connect-standalone.properties 파일을 편집해 plugin.path 구성 속성을 아래와 같이 추가하거나 변경하고 저장해요.
$ echo "plugin.path=libs/connect-file-4.3.1.jar" >> config/connect-standalone.properties
그 다음 테스트용 시드(seed) 데이터를 만들어요.
$ echo -e "foo
bar" > test.txt
Windows라면:
$ echo foo > test.txt
$ echo bar >> test.txt
이제 standalone 모드로 실행되는 두 커넥터를 시작할게요. standalone 모드는 단일 로컬 전용 프로세스에서 실행된다는 뜻이에요. 매개변수로 설정 파일 3개를 제공해요. 첫 번째는 항상 Kafka Connect 프로세스 설정으로, 연결할 Kafka 브로커와 데이터 직렬화 형식 같은 공통 구성을 담아요. 나머지 설정 파일은 각각 만들 커넥터 하나를 지정해요. 이 파일에는 고유한 커넥터 이름, 인스턴스화할 커넥터 클래스, 커넥터가 필요로 하는 기타 구성이 포함돼요.
$ bin/connect-standalone.sh config/connect-standalone.properties config/connect-file-source.properties config/connect-file-sink.properties
Kafka에 포함된 이 샘플 설정 파일들은 앞서 시작한 기본 로컬 클러스터 구성을 사용하고 커넥터 두 개를 만들어요. 첫 번째는 입력 파일의 줄을 읽어 각각을 Kafka 토픽으로 생산하는 소스 커넥터이고, 두 번째는 Kafka 토픽의 메시지를 읽어 각각을 출력 파일의 한 줄로 쓰는 싱크 커넥터예요.
시작하는 동안 커넥터가 인스턴스화되고 있다는 표시를 포함한 여러 로그 메시지를 볼 수 있어요. Kafka Connect 프로세스가 시작되면 소스 커넥터가 test.txt의 줄을 읽어 토픽 connect-test로 생산하기 시작하고, 싱크 커넥터가 토픽 connect-test의 메시지를 읽어 파일 test.sink.txt에 쓰기 시작해요. 출력 파일의 내용을 확인해 데이터가 파이프라인 전체를 통해 전달됐는지 검증할 수 있어요.
$ more test.sink.txt
foo
bar
데이터가 Kafka 토픽 connect-test에 저장되고 있으니, 콘솔 컨슈머를 실행해 토픽의 데이터를 볼 수도 있어요(또는 커스텀 컨슈머 코드로 처리해도 되고요).
$ bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic connect-test --from-beginning
{"schema":{"type":"string","optional":false},"payload":"foo"}
{"schema":{"type":"string","optional":false},"payload":"bar"}
…
커넥터는 데이터를 계속 처리하므로 파일에 데이터를 추가하면 파이프라인을 따라 이동하는 걸 볼 수 있어요.
$ echo "Another line" >> test.txt
그 줄이 콘솔 컨슈머 출력과 싱크 파일에 나타나는 걸 볼 수 있어요.
7단계: Kafka Streams로 이벤트 처리하기
데이터가 Kafka에 이벤트로 저장되면, Java/Scala용 Kafka Streams 클라이언트 라이브러리로 데이터를 처리할 수 있어요. 입력/출력 데이터가 Kafka 토픽에 저장되는 미션 크리티컬한 실시간 애플리케이션과 마이크로서비스를 구현할 수 있게 해줘요. Kafka Streams는 클라이언트 쪽에서 표준 Java·Scala 애플리케이션을 작성·배포하는 단순함과, Kafka 서버 쪽 클러스터 기술의 이점을 결합해서 그런 애플리케이션을 고도로 확장 가능하고 탄력적이며 장애 허용적이고 분산적으로 만들어요. 이 라이브러리는 정확히 한 번(exactly-once) 처리, 상태 저장 연산과 집계, 윈도잉, 조인, 이벤트 시간 기반 처리 등을 지원해요.
첫 맛을 보려고, 유명한 WordCount 알고리즘을 어떻게 구현하는지 볼게요.
KStream<String, String> textLines = builder.stream("quickstart-events");
KTable<String, Long> wordCounts = textLines
.flatMapValues(line -> Arrays.asList(line.toLowerCase().split(" ")))
.groupBy((keyIgnored, word) -> word)
.count();
wordCounts.toStream().to("output-topic", Produced.with(Serdes.String(), Serdes.Long()));
Kafka Streams 데모와 앱 개발 튜토리얼에서 이런 스트리밍 애플리케이션을 처음부터 끝까지 코딩하고 실행하는 방법을 보여줘요.
8단계: Kafka 환경 종료하기
퀵스타트 끝에 도달했으니 Kafka 환경을 정리해도 되고, 계속 가지고 놀아도 돼요.
- 아직 하지 않았다면
Ctrl-C로 프로듀서·컨슈머 클라이언트를 중지해요. Ctrl-C로 Kafka 브로커를 중지해요.
로컬 Kafka 환경의 데이터(그동안 만든 이벤트 포함)까지 모두 삭제하고 싶다면 다음 명령을 실행해요.
$ rm -rf /tmp/kafka-logs /tmp/kraft-combined-logs
축하합니다!
Apache Kafka 퀵스타트를 성공적으로 마쳤어요. 더 배우려면 다음을 추천해요.
- 간단한 Introduction을 읽고 Kafka가 높은 수준에서 어떻게 동작하는지, 주요 개념과 다른 기술과의 비교를 배워요. Kafka를 더 자세히 이해하려면 Documentation으로 이동해요.
- Use Cases를 둘러보며 전 세계 커뮤니티의 다른 사용자들이 Kafka에서 어떻게 가치를 얻는지 배워요.
- 현지 Kafka 밋업 그룹에 참여하고, Kafka 커뮤니티의 주요 컨퍼런스인 Kafka Summit 발표를 시청해 보세요.
더 알아보기 (Learn more)
- 퀵스타트 전체 흐름: 환경 시작 → 토픽 생성 → 프로듀서로 쓰기 → 컨슈머로 읽기 → Connect로 연동 → Streams로 처리 순서예요.
- 이벤트는 Kafka에서 영구 저장되므로 필요하면 언제든 반복해서 읽을 수 있어요.