로컬 카프카 설치부터 메시지 전송/수신

 

 

Kafka를 로컬에서 돌려 보려면 자바 17 ↑, Kafka 바이너리 또는 Docker 이미지, 그리고 몇 개의 CLI 스크립트만 준비하면 됩니다. 이 글에서는 Windows·macOS·Linux 별 네이티브 설치와 Docker Compose 기반 설치를 모두 다루고, 마지막에 kafka-console-producer.sh·kafka-console-consumer.sh를 이용해 토픽 생성 → 메시지 발행 → 구독까지 한 번에 실습합니다. 최신 Kafka 3.7.0 기준이며, KRaft 모드·MSK 업그레이드 동향도 간단히 짚어 보았습니다.

---

공통 준비 사항

• Java 17 이상이 필수입니다. OpenJDK 17이나 Amazon Corretto 17을 설치해 두십시오.
• Kafka 3.7.0 TGZ/ZIP 파일을 받아 둘 수 있는 네트워크 권한 또는 Docker 설치 권한이 있어야 합니다.
• 포트 9092(브로커)·2181(ZooKeeper, KRaft 모드가 아니면)·19092(외부 접근용 등)를 방화벽에서 허용해 두면 편합니다.

---

Windows 10 / 11 설치

1) ZIP 다운로드 + PowerShell 실행

1. 공식 다운로드 페이지에서 Binary downloads → Scala 2.13 → 3.7.0 ZIP을 내려받아 C:\kafka에 압축 해제합니다. 
2. PowerShell에서 이동이 스크립트는 별도 서비스 설치 없이 단일 노드 브로커를 실행합니다. 
3. cd C:\kafka .\bin\windows\kafka-server-start.bat .\config\server.properties

2) WSL2 이용(추천)

• Windows Home Edition 사용자이거나 Linux-like 툴 체인이 필요하다면 WSL2 + Ubuntu에 tarball을 설치하는 방식이 더 간편합니다. 
• 절차는 “Linux 설치” 단락과 동일하되 디렉터리는 /usr/local/kafka 등을 사용하면 됩니다.

---

macOS (Apple Silicon·Intel)

1) Homebrew 한 줄 설치

brew install kafka

Homebrew Formula 저장소에 Kafka 4.0.0까지만 올라와 있더라도 brew는 자동으로 Java17을 의존성으로 설치하고, kafka-server-start 및 CLI 스크립트를 /opt/homebrew/bin(Apple Silicon) 아래에 배치합니다. 

2) 수동 TGZ 설치

• tarball을 /usr/local/kafka에 풀고,로 기동합니다. macOS도 Linux 스크립트를 그대로 씁니다. 
• bin/kafka-server-start.sh config/server.properties

---

Linux (Ubuntu·Debian·RHEL 계열)

1) TGZ 설치(가장 보편적)

wget https://dlcdn.apache.org/kafka/3.7.0/kafka_2.13-3.7.0.tgz
tar -xzf kafka_2.13-3.7.0.tgz
cd kafka_2.13-3.7.0
bin/kafka-server-start.sh config/server.properties

운영 서버에서도 tarball 설치가 권장됩니다.

2) 패키지 매니저

• Debian/Ubuntu:
  apt-get install kafka(Confluent APT repo) → /etc/kafka에 설정 파일 배치.
• CentOS/RHEL:
  yum install confluent-kafka 등 RPM 패키지 사용.
  (패키지 이름과 버전은 배포판 저장소에 따라 다르므로 공식 문서를 확인하십시오.) 

---

Docker Compose로 한 방 배포

docker-compose.yml 예시

version: "3"
services:
  kafka:
    image: bitnami/kafka:3.7
    environment:
      - KAFKA_CFG_NODE_ID=1
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka:9093
      - ALLOW_PLAINTEXT_LISTENER=yes
    ports:
      - "9092:9092"

process.roles 옵션으로 KRaft 단일 노드를 구성했습니다(3.7부터 안정). 

실행

docker compose up -d
docker compose logs -f kafka

[KafkaServer id=1] started 로그가 보이면 기동 완료입니다. 

---

CLI 기반 메시지 실습

실습 전제: 터미널 3개를 열어 Kafka 브로커, Producer, Consumer를 각각 실행합니다.

1) 토픽 생성

bin/kafka-topics.sh --create \
  --topic quickstart \
  --partitions 3 --replication-factor 1 \
  --bootstrap-server localhost:9092

--describe 서브커맨드로 리더·ISR 정보를 확인할 수 있습니다. 

2) 메시지 발행(Producer)

bin/kafka-console-producer.sh --topic quickstart \
  --bootstrap-server localhost:9092
>첫 번째 메시지
>두 번째 메시지

acks=all·client.id 등 고급 옵션은 환경 변수 또는 --producer-property로 전달할 수 있습니다.

3) 메시지 구독(Consumer)

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

Ctrl+C 로 종료 시 자동 오프셋 커밋이 수행됩니다; --group 옵션으로 컨슈머 그룹을 지정하면 병렬 소비를 테스트할 수 있습니다. 

---

자주 만나는 문제 & 해결

증상 원인 해결책

java.lang.UnsupportedClassVersionError	JDK 8/11 사용	JAVA_HOME을 17+로 교체
Listener Not Found	브로커가 외부 IP 광고 안 함	advertised.listeners 설정 추가
Connection to node -1 (broker) failed	Docker → 호스트 네트워크 매핑 오류	ports: "29092:9092" & KAFKA_CFG_ADVERTISED_LISTENERS 지정