Kafka-UI란? 설치 및 사용법

Apache Kafka를 운영하면서 CLI 명령어만으로 클러스터를 관리하고 모니터링하는 것은 쉽지 않습니다. 토픽의 메시지를 확인하거나, 컨슈머 그룹의 상태를 점검하고, 브로커의 상태를 모니터링하는 일련의 작업들이 번거롭고 시간이 많이 소요되죠.

이런 문제를 해결하기 위해 등장한 것이 바로 Kafka-UI(UI for Apache Kafka)입니다. 이번 글에서는 Kafka-UI가 무엇인지, 어떻게 설치하고 사용하는지 상세히 알아보겠습니다.

Kafka-UI란?

UI for Apache Kafka(일명 Kafka-UI)는 Apache Kafka 클러스터를 모니터링하고 관리하기 위한 무료 오픈소스 웹 UI입니다. Provectus에서 개발하고 커뮤니티가 지원하는 이 도구는 개발자가 데이터 흐름을 관찰 가능하게 만들고, 문제를 더 빠르게 찾아 해결하며, 최적의 성능을 제공하도록 돕습니다.

주요 특징

• GitHub: https://github.com/provectus/kafka-ui
• 라이선스: Apache 2.0
• 비용: 완전 무료
• Stars: 10.3k+ (활발한 커뮤니티)

장점:

• 직관적이고 현대적인 UI
• 다양한 기능 제공
• 경량 대시보드
• 활발한 개발 및 업데이트

단점:

• 일부 엔터프라이즈 기능은 상용 도구에 비해 제한적

Kafka-UI의 주요 기능

1. 멀티 클러스터 관리

한 곳에서 모든 Kafka 클러스터를 모니터링하고 관리할 수 있습니다.

2. 성능 모니터링 대시보드

경량 대시보드로 주요 Kafka 메트릭(브로커, 토픽, 파티션, 프로덕션, 컨슘션)을 추적합니다.

3. Kafka 브로커 조회

토픽 및 파티션 할당, 컨트롤러 상태를 확인할 수 있습니다.

4. Kafka 토픽 관리

• 파티션 개수, 복제 상태, 커스텀 설정 확인
• 동적 설정으로 새 토픽 생성
• 토픽 삭제 및 재구성

5. 컨슈머 그룹 관리

파티션별 오프셋, 전체 및 파티션별 지연(lag)을 확인할 수 있습니다.

6. 메시지 브라우징

JSON, 일반 텍스트, Avro, Protobuf 인코딩으로 메시지를 브라우징하고 검색할 수 있습니다.

7. 보안 기능

• 인증: Github/Gitlab/Google OAuth 2.0 설정 가능
• 권한 관리: 역할 기반 접근 제어(RBAC)
• 데이터 마스킹: 토픽 메시지의 민감한 데이터 난독화

8. 스키마 레지스트리 통합

Avro, JSON Schema, Protobuf 스키마를 지원합니다.

9. 커스텀 직렬화/역직렬화 플러그인

AWS Glue, Smile 등 다양한 Serde를 사용하거나 직접 코딩할 수 있습니다.

Kafka-UI 설치 방법

Kafka-UI를 설치하는 방법은 여러 가지가 있습니다. 가장 간단한 Docker를 이용한 방법부터 알아보겠습니다.

1. Quick Start (데모 실행)

가장 빠르게 Kafka-UI를 체험해볼 수 있는 방법입니다.

docker run -it -p 8080:8080 -e DYNAMIC_CONFIG_ENABLED=true provectuslabs/kafka-ui

명령 실행 후 브라우저에서 http://localhost:8080으로 접속하면 Kafka-UI를 사용할 수 있습니다.

참고: 이 방법은 테스트용이며, 설정이 저장되지 않습니다. 실제 운영 환경에서는 아래의 영구 설치 방법을 사용하세요.

2. Docker Compose를 이용한 영구 설치

Step 1: Kafka 클러스터 구성

먼저 Docker Compose로 멀티 브로커 Kafka 클러스터를 구성합니다.

docker-compose-kafka.yaml:

---
version: '3.8'
services:
  zookeeper-1:
    image: confluentinc/cp-zookeeper:5.5.1
    ports:
      - '32181:32181'
    environment:
      ZOOKEEPER_CLIENT_PORT: 32181
      ZOOKEEPER_TICK_TIME: 2000

  kafka-1:
    image: confluentinc/cp-kafka:5.5.1
    ports:
      - '9092:9092'
    depends_on:
      - zookeeper-1
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper-1:32181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
      KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka-1:29092,EXTERNAL://localhost:9092
      KAFKA_DEFAULT_REPLICATION_FACTOR: 3
      KAFKA_NUM_PARTITIONS: 3

  kafka-2:
    image: confluentinc/cp-kafka:5.5.1
    ports:
      - '9093:9093'
    depends_on:
      - zookeeper-1
    environment:
      KAFKA_BROKER_ID: 2
      KAFKA_ZOOKEEPER_CONNECT: zookeeper-1:32181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
      KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka-2:29093,EXTERNAL://localhost:9093
      KAFKA_DEFAULT_REPLICATION_FACTOR: 3
      KAFKA_NUM_PARTITIONS: 3

  kafka-3:
    image: confluentinc/cp-kafka:5.5.1
    ports:
      - '9094:9094'
    depends_on:
      - zookeeper-1
    environment:
      KAFKA_BROKER_ID: 3
      KAFKA_ZOOKEEPER_CONNECT: zookeeper-1:32181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
      KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka-3:29094,EXTERNAL://localhost:9094
      KAFKA_DEFAULT_REPLICATION_FACTOR: 3
      KAFKA_NUM_PARTITIONS: 3

Kafka 클러스터 실행:

docker-compose -f docker-compose-kafka.yaml up -d

Step 2: Kafka-UI 실행

docker-compose-kafka-ui.yaml:

version: '3.8'
services:
  kafka-ui:
    container_name: kafka-ui
    image: provectuslabs/kafka-ui:latest
    ports:
      - "8989:8080"
    restart: always
    environment:
      - KAFKA_CLUSTERS_0_NAME=local
      - KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka-1:29092,kafka-2:29093,kafka-3:29094
      - KAFKA_CLUSTERS_0_ZOOKEEPER=zookeeper-1:32181
      - DYNAMIC_CONFIG_ENABLED=true
    volumes:
      - ~/kui/config.yml:/etc/kafkaui/dynamic_config.yaml

Kafka-UI 실행:

docker-compose -f docker-compose-kafka-ui.yaml up -d

브라우저에서 http://localhost:8989로 접속하면 Kafka-UI를 사용할 수 있습니다.

3. 통합 Docker Compose 설정

Kafka와 Kafka-UI를 하나의 파일로 구성할 수도 있습니다:

version: '3.8'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:latest
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:latest
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    depends_on:
      - kafka
    ports:
      - "8080:8080"
    environment:
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
      DYNAMIC_CONFIG_ENABLED: 'true'

실행:

docker-compose up -d

Kafka-UI 화면 둘러보기

1. 메인 대시보드

접속하면 가장 먼저 보이는 메인 대시보드입니다.

주요 정보:

• Online: 현재 연결된 클러스터 개수
• Cluster name: 클러스터 이름
• Version: Kafka 버전
• Brokers count: 브로커 개수
• Partitions: 파티션 개수
• Topics: 토픽 개수
• Production: 발행한 메시지 용량
• Consumption: 수신한 메시지 용량

2. Brokers 화면

브로커 목록과 상세 정보를 확인할 수 있습니다.

표시 정보:

• Total Brokers: 총 브로커 개수
• Active Controllers: 활성 컨트롤러
• Online Partitions: 온라인 파티션 개수
• URP: 복제가 덜 된 파티션 수
• In Sync Replicas: 동기화된 복제본 개수
• Segment Size/Count: 세그먼트 크기 및 개수

3. Topics 화면

현재 생성된 모든 토픽을 확인하고 관리할 수 있습니다.

토픽 정보:

• Topic Name: 토픽 이름
• Total Partitions: 총 파티션 개수
• Out of sync replicas: 동기화되지 않은 복제본
• Replication Factor: 복제 계수
• Number of messages: 메시지 수
• Size: 메시지 총 크기

토픽 생성하기

'Add a Topic' 버튼을 클릭하면 토픽 생성 화면이 나타납니다.

설정 항목:

• Topic Name: 토픽 이름
• Number of partitions: 파티션 개수
• Replication Factor: 복제 계수
• Min in Sync Replicas: 최소 동기화 복제본 수
• Cleanup Policy: 클린업 정책
  • Delete: 보관 기간 경과 후 삭제
  • Compact: 압축
  • Compact, Delete: 압축 후 삭제
• Time to retain data: 데이터 보관 기간 (밀리초)
• Max size on disk: 디스크 최대 크기 (GB)
• Maximum message size: 최대 메시지 크기 (바이트)

4. Messages 화면

토픽 내부의 메시지를 확인하고 생성할 수 있습니다.

기능:

• Produce Message: 새 메시지 생성
• 메시지 검색: 내용으로 메시지 검색
• 메시지 목록:
  • Offset: 메시지 오프셋
  • Partition: 파티션 번호
  • Timestamp: 타임스탬프
  • Key: 메시지 키
  • Content: 메시지 내용

메시지 생성 시 다음을 설정할 수 있습니다:

• 메시지 키
• 메시지 내용
• 헤더 정보
• 파티션 지정

5. Consumers 화면

클러스터에 연결된 컨슈머 그룹을 확인할 수 있습니다.

표시 정보:

• Consumer Group ID: 컨슈머 그룹 아이디
• Number Of Members: 그룹 내 멤버 수
• Num Of Topics: 구독 중인 토픽 수
• Message Behind: 지연된 메시지 수 (lag)
• Coordinator: 코디네이터 브로커
• State: 컨슈머 그룹 상태 (Empty, Stable, Dead 등)

6. Schema Registry

Avro, JSON Schema, Protobuf 스키마를 생성하고 관리할 수 있습니다.

지원 기능:

• 스키마 생성 및 수정
• 스키마 버전 관리
• 스키마와 토픽 연결
• 스키마 호환성 검사

실전 사용 팁

1. 메시지 모니터링

실시간으로 메시지 흐름을 확인하려면:
1. Topics 메뉴에서 토픽 선택
2. Messages 탭 클릭
3. 'Live mode' 옵션으로 실시간 메시지 확인

2. 컨슈머 Lag 모니터링

컨슈머가 제대로 메시지를 소비하고 있는지 확인:
1. Consumers 메뉴 선택
2. Message Behind 컬럼에서 지연 확인
3. 특정 컨슈머 그룹 클릭하여 파티션별 상세 정보 확인

3. 토픽 성능 최적화

토픽 설정 조정:
1. Topics 메뉴에서 토픽 선택
2. Settings 탭에서 파라미터 확인 및 수정
3. 주요 설정:

• retention.ms: 메시지 보관 기간
• segment.bytes: 세그먼트 크기
• compression.type: 압축 타입

4. 브로커 상태 점검

정기적인 브로커 상태 확인:
1. Brokers 메뉈 선택
2. URP(Under Replicated Partitions) 확인
3. 세그먼트 크기 증가 추이 모니터링

보안 설정

OAuth 2.0 인증 설정

config.yml:

auth:
  type: OAUTH2
  oauth2:
    client:
      github:
        clientId: your-client-id
        clientSecret: your-client-secret
        scope: read:org
        user-name-attribute: login

RBAC 설정

역할 기반 접근 제어 설정:

rbac:
  roles:
    - name: admin
      clusters:
        - local
      permissions:
        - resource: topic
          actions: [create, edit, delete, view]
    - name: viewer
      clusters:
        - local
      permissions:
        - resource: topic
          actions: [view]

문제 해결

1. 클러스터 연결 실패

증상: 브로커가 표시되지 않음

해결 방법:

• Bootstrap servers 주소 확인
• 네트워크 연결 상태 점검
• Docker 네트워크 설정 확인

# Docker 네트워크 확인
docker network inspect bridge

# Kafka 브로커 로그 확인
docker logs kafka-1

2. 메시지가 표시되지 않음

증상: 토픽에 메시지가 있지만 UI에 표시되지 않음

해결 방법:

• Deserialization 설정 확인
• 메시지 포맷이 지원되는지 확인
• 브라우저 캐시 삭제 후 새로고침

3. 성능 이슈

증상: UI가 느리게 반응함

해결 방법:

• 메시지 개수가 많은 토픽의 경우 필터 사용
• 페이지네이션 크기 조정
• 불필요한 클러스터 연결 제거

Helm을 이용한 Kubernetes 배포

Kubernetes 환경에서 Kafka-UI를 배포하려면:

# Helm 레포지토리 추가
helm repo add kafka-ui https://provectus.github.io/kafka-ui-charts

# Kafka-UI 설치
helm install kafka-ui kafka-ui/kafka-ui \
  --set envs.config.KAFKA_CLUSTERS_0_NAME=local \
  --set envs.config.KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092

결론

Kafka-UI는 Apache Kafka를 훨씬 쉽게 관리하고 모니터링할 수 있게 해주는 강력한 도구입니다. 무료 오픈소스이면서도 상용 솔루션 못지않은 기능을 제공하여, 개발 환경뿐만 아니라 프로덕션 환경에서도 충분히 활용할 수 있습니다.

Kafka-UI의 핵심 장점:

• ✅ 설치 및 설정이 간단함 (Docker 한 줄로 시작 가능)
• ✅ 직관적이고 현대적인 UI
• ✅ 멀티 클러스터 관리 지원
• ✅ 실시간 메시지 모니터링
• ✅ 완전 무료 오픈소스
• ✅ 활발한 커뮤니티와 지속적인 업데이트

Kafka를 사용하고 있다면, Kafka-UI를 도입하여 운영 효율성을 크게 높일 수 있습니다. 특히 개발 단계에서 디버깅이나 테스트를 할 때 그 진가를 발휘합니다.

참고 자료

• Kafka-UI GitHub Repository
• Kafka-UI 공식 문서
• Kafka-UI Tool을 이용하여 Kafka 관리하기 - SK Devocean
• Docker 공식 가이드 - Kafka