Apache Kafka - Windows 환경에서 KRaft 모드로 카프카 시작하기

이건·2025년 5월 2일
kafka트러블슈팅
0

Kafka

목록 보기
10/18

Zookeeper는 점점 사라지고 있고, 앞으로는 Kafka에서 대체될 예정이다. 따라서 KRaft 모드로 카프카를 시작하려는데 어떤 방식으로 카프카를 시작할 지 고민이 되었다.

많은 공식 문서와 기업, 커뮤니티에서 도커로 카프카를 실행하는 방법과 베스트 프랙티스를 제공하고 있다.
다만, 운영 환경(Production)과 개발/테스트 환경에서의 권장도와 주의점이 다르다.

도커로 카프카를 실행하는 장점

  • 설치와 배포가 쉬움: 복잡한 의존성 없이 컨테이너만 띄우면 바로 카프카 클러스터를 구성할 수 있다.
  • 환경 일관성: 개발, 테스트, 배포 환경 간의 차이를 줄일 수 있다.
  • 확장성과 관리 편의성: 컨테이너 오케스트레이션(Docker Compose, Kubernetes 등)으로 손쉽게 확장·관리할 수 있다.
  • 재현성: 버전과 설정이 고정된 이미지를 사용하므로, 동일한 환경을 쉽게 재현할 수 있다.

도커로 카프카를 실행할 때 주의할 점

  • 성능: 카프카는 디스크 IO에 매우 민감한 서비스다. 컨테이너 환경에서는 호스트의 디스크 성능, 볼륨 마운트 방식, 네트워크 구성에 따라 성능 저하가 발생할 수 있다.
  • 스토리지: 데이터 영속성을 위해 반드시 Docker 볼륨을 사용해야 하며, 호스트 디렉터리 마운트 시 퍼미션/성능 문제에 주의해야 한다.
  • 운영 환경 리소스: 운영 환경에서는 최소 16GB RAM, 4 CPU 코어 등 충분한 리소스를 할당해야 하며, SSD 사용이 권장된다.
  • 네트워크: 컨테이너 네트워크와 외부 접근을 위한 리스너 설정(advertised.listeners)을 신중히 해야 한다.
  • 운영 안정성: 컨테이너 장애, 호스트 장애, 오케스트레이션 환경에 대한 이해가 필요하다.

실제 권장 사항

  • 개발/테스트 환경: 도커로 카프카를 실행하는 것이 매우 권장된다. 빠른 초기화, 손쉬운 클러스터 구성, 실험적 환경 구축에 유리하다.
  • 운영(Production) 환경:
    • 도커로 카프카를 운영하는 것도 가능하며, 실제로 많은 기업이 Kubernetes 등 컨테이너 환경에서 카프카를 운영한다.
    • 단, 디스크 IO, 네트워크, 데이터 영속성, 리소스 할당, 장애 복구 등 운영상의 세밀한 튜닝과 모니터링이 필요하다.
    • 고성능·대규모 환경에서는 VM이나 베어메탈 서버에 직접 설치하는 것도 여전히 많이 사용된다.

결론

  • 개발·테스트에는 도커가 매우 적합하며, 운영 환경에서도 충분한 리소스와 적절한 설정, 모니터링이 있다면 도커/쿠버네티스 기반 운영도 널리 사용되고 있다.
  • 단, 운영 환경에서는 성능·데이터 영속성·장애 복구 등 추가적인 고려가 필요하다.

요약:
도커로 카프카를 실행하는 것은 개발/테스트에는 적극 권장, 운영 환경에서도 충분한 준비와 리소스가 있다면 가능하며, 실제로도 많이 사용되고 있다.

따라서 아래와 같이 docker-compose.yml 파일을 작성하였다.

version: '3.8'

services:
  kafka:
    image: apache/kafka:latest
    container_name: kafka
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LOG_DIRS: /kafka/data
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
    volumes:
    - kafka_data:/kafka/data

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    container_name: kafka-ui
    ports:
    	- "8989:8080"
    depends_on:
    	- kafka
    environment:
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092

volumes:
kafka_data:

하지만 이렇게 코드를 짠 후 docker compose up을 하게 되면

kafka | Formatting metadata directory /kafka/data with metadata.version 4.0-IV3. Error while writing meta.properties file /kafka/data: java.nio.file.AccessDeniedException: /kafka/data/bootstrap.checkpoint.tmp
kafka exited with code 1

이런 에러가 발생하게 되면서 kafka container가 바로 종료된다.

이 에러는 Kafka 컨테이너가 /kafka/data 디렉터리에 쓸 권한이 없어서 발생하는 "퍼미션(권한)" 문제다.
특히 Windows나 Mac에서 Docker를 쓸 때 자주 발생한다.

권한 문제, 이렇게 해결

1. 호스트 디렉터리 마운트가 아닌 named volume만 사용

  • docker-compose에서 아래처럼 named volume만 사용:
    volumes:
  - kafka_data:/kafka/data
  • 절대 ./kafka_data:/kafka/data처럼 호스트 경로를 직접 마운트하지 말자.
    (Windows/Mac에서 권한 문제를 99% 유발한다.)

2. 볼륨 완전 삭제 후 재생성

  • 아래 명령어로 컨테이너와 볼륨을 완전히 삭제하고 새로 시작:

    
docker compose down -v
docker volume prune -f
docker compose up -d

  • 그래도 문제가 반복된다면, 아래 3번을 꼭 확인

3. Windows/Mac은 Docker Desktop의 파일 공유 설정 확인

  • Docker Desktop → Settings → Resources → File Sharing에서
    컨테이너가 접근할 경로가 공유되어 있는지 확인
  • named volume만 쓰면 이 문제는 거의 발생하지 않는다.

4. (리눅스/WSL 한정) 볼륨 권한 직접 수정

  • 컨테이너가 일시적으로라도 살아 있다면,

    
docker exec -it kafka bash
chown -R 1000:1000 /kafka/data
chmod -R 755 /kafka/data

  • 이 방법은 리눅스/WSL에서만 가능하다.

위의 방법들을 모두 시도 했지만 해결되지 않았다.

해결방법

Windows에서 Docker 볼륨은 chown, chmod로 권한 변경이 불가능하다.
그리고 Kafka는 Windows 파일 시스템과 궁합이 매우 나쁘다.

가장 확실한 해결책은 WSL2 리눅스 파일 시스템에서 Kafka를 실행하는 것이다.

운영 환경이 아니라면, WSL2/리눅스에서 실습하는 것이 강력히 권장된다.

1. WSL2 리눅스 파일 시스템에서 Kafka를 실행

(1). WSL2 설치

사전 조건

  • Windows 10(빌드 19041 이상) 또는 Windows 11 필요
  • 관리자 권한의 명령 프롬프트(PowerShell) 사용

설치 절차
1. Windows 버전 확인

  • 명령 프롬프트(관리자 권한)에서 winver 입력
  • 빌드 번호가 19041 이상인지 확인

  1. WSL2 설치

    • PowerShell(관리자 권한)에서 아래 명령 실행:
      wsl --install
    • 설치가 완료되면 시스템을 재부팅

  2. Ubuntu 설치 및 초기 설정

    • 재부팅 후 Ubuntu가 자동 설치됨
    • 사용자 이름과 비밀번호 설정

(2). Java 11 JDK 설치

Kafka는 Java 런타임이 필요하므로, Ubuntu 터미널에서 다음 명령어로 Java 11 JDK를 설치한다.

sudo apt update
sudo apt install openjdk-11-jdk -y

설치 완료 후, 아래 명령어로 정상 설치 여부를 확인한다.

java -version

(3). Kafka 바이너리 다운로드 및 압축 해제

  1. Kafka 공식 사이트에서 최신 버전의 다운로드 링크 복사
    https://kafka.apache.org/downloads

  2. wget으로 다운로드 및 압축 해제

    wget https://downloads.apache.org/kafka/3.1.0/kafka_2.13-3.1.0.tgz
tar xzf kafka_2.13-3.1.0.tgz

  3. Kafka 디렉터리 확인

    ls

(4). Kafka 바이너리 환경변수(PATH) 등록

Kafka 명령어를 어디서나 사용할 수 있도록 환경변수에 등록합니다.

  1. Kafka bin 디렉터리의 전체 경로 확인

    cd kafka_2.13-3.1.0/bin
pwd
    • 예시 출력: /home/사용자명/kafka_2.13-3.1.0/bin

  2. .bashrc 파일 편집

    cd ~
nano .bashrc
    • 파일 맨 아래에 다음 라인 추가:
      export PATH="$PATH:/home/사용자명/kafka_2.13-3.1.0/bin"
    • 저장 후 nano 종료(Ctrl + X, Y, Enter)

  3. 변경 사항 적용

    source ~/.bashrc

  4. 적용 확인

    echo $PATH
kafka-topics.sh --help
    • 정상적으로 명령어가 동작하면 성공

하지만...

나는 곧 죽어도 도커로 실행하고 싶다.

2. Bitnami Kafka 이미지 사용

Bitnami Kafka 이미지는 KRaft 모드를 지원한다. 실제로 최근 버전(3.4.0 이상)부터는 Bitnami 공식 이미지와 Helm 차트 모두에서 KRaft 모드가 기본 지원 및 활성화되어 있다.
즉, Bitnami로 Kafka를 실행할 때도 Zookeeper 없이 KRaft 모드로 동작할 수 있다.

(1). Bitnami의 권한 처리 방식

  • Bitnami Kafka 이미지는 기본적으로 비root 사용자(UID 1001)로 실행되지만,
    컨테이너가 시작될 때 데이터 디렉터리(/bitnami/kafka)의 권한을 자동으로 맞춰주는 로직이 내장되어 있다.
  • 만약 호스트 볼륨을 마운트할 때 권한이 맞지 않으면, Bitnami 이미지는 경고를 띄우고,
    가능한 한 내부적으로 권한을 맞추려고 시도한다.
  • 이 덕분에 Windows, Mac, Linux 등 다양한 환경에서 권한 문제로 인한 에러가 적게 발생한다.

(2). Bitnami의 KRaft 모드 지원

  • Bitnami Kafka는 환경변수(KAFKA_CFG_PROCESS_ROLES, KAFKA_CFG_NODE_ID 등)만 맞게 설정하면
    KRaft 모드로 정상 동작한다.
  • 실제로 여러 실습 블로그, 공식 README, Helm 차트 등에서
    Bitnami Kafka가 Zookeeper 없이 KRaft 모드로 잘 동작하는 예제가 많다.

(3). 컨테이너 내부 경로와 권한 정책

  • Bitnami 이미지는 데이터 경로가 /bitnami/kafka로 고정되어 있고,
    권한을 맞추는 스크립트가 컨테이너 시작 시 항상 실행된다.
  • 반면, 공식 Apache Kafka 이미지는 권한 처리 로직이 단순하거나,
    root가 아닌 사용자로 실행할 때 Windows/NTFS 환경에서 퍼미션 문제가 더 쉽게 발생한다.

참고: Bitnami로 KRaft 모드 실행 예시

version: '3.8'

services:
  kafka:
    image: bitnami/kafka:latest
    container_name: kafka
    ports:
      - "9092:9092"
    environment:
      - KAFKA_ENABLE_KRAFT=yes
      - KAFKA_CFG_NODE_ID=1
      - KAFKA_CFG_PROCESS_ROLES=broker,controller
      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka:9093
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
      - KAFKA_CFG_LOG_DIRS=/bitnami/kafka/data
      - ALLOW_PLAINTEXT_LISTENER=yes
    volumes:
      - kafka_data:/bitnami/kafka/data

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    container_name: kafka-ui
    ports:
      - "8989:8080"
    depends_on:
      - kafka
    environment:
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092

volumes:
  kafka_data:
  • 위와 같이 설정하면 KRaft 모드로 정상 동작한다.

결론

  • Bitnami Kafka 이미지는 KRaft 모드를 공식적으로 지원하며,
    권한 처리 로직이 잘 짜여 있어 Windows 등 다양한 환경에서 실행이 비교적 원활하다.
  • 반면, 공식 Apache Kafka 이미지는 Windows/NTFS 환경에서 권한 문제가 더 쉽게 발생할 수 있다.
  • Bitnami로 정상 실행된 이유는 내장된 권한 처리 스크립트와 KRaft 공식 지원 덕분이다.
  • I love docker,,,
profile
이건
이전 포스트

Apache Kafka 이론 - Zookeeper & Kafka KRaft

다음 포스트

Apache Kafka - Kafka 컨슈머 그룹과 파티션 리밸런싱 전략 이해하기

0개의 댓글