15. Apache Kafka UI 관리도구 AKHQ 설치 및 설정 하기: 사용자 인증
Apache Apache Kafka를 웹 UI로 관리할 수 있는 도구인 AKHQ 설치 및 설정 방법을 소개합니다.
Docker 및 Standalone 방식 설치부터 application.yml 설정과 사용자 인증 구성, 서비스 등록까지 자세히 정리했습니다.
Apache Kafka UI 관리도구 AKHQ 설치 및 설정 하기: 사용자 인증
목차
1. AKHQ란?
AKHQ는 Apache Kafka를 시각적으로 관리할 수 있는 웹 UI 도구입니다.
프로듀서, 컨슈머, 토픽, 파티션, ACL 등을 브라우저에서 손쉽게 확인하고 제어할 수 있습니다.
특징
- Kafka 클러스터 정보 시각화
- 토픽 생성 및 삭제 기능
- 메시지 확인 및 검색
- 컨슈머 그룹 상태 추적
- ACL 관리 기능 (선택)
관리도구 비교문서
Overview of UI Tools for Monitoring and Management of Apache Kafka Clusters | Towards Data Science
What are the best tools engineers can use to observe data flows, track key metrics, and troubleshoot issues in Apache Kafka?
towardsdatascience.com
2. AKHQ 설치 방법: Docker
1. Docker 설치 확인
만약 설치자 안되었다면 "관련 글 링크"를 참고하여 설치를 수행합니다.
docker --version
Docker version 28.0.4, build b8034c0
2. AKHQ 이미지 검색 및 다운로드
sudo docker search akhq
sudo docker pull tchiotludo/akhq
3. AKHQ 이미지 확인 및 Docker 실행
1. Docker 이미지 확인
sudo docker images
2. Docker 실행
sudo docker run -d -p 9090:9090 \
-v /home/kafka/akhq-docker/application.yml:/app/application.yml
tchiotludo/akhq
- -p 8080:8080 → 호스트의 8080 포트를 컨테이너의 8080 포트에 연결
- -v /home/kafka/akhq-docker/application.yml:/app/application.yml → 설정 파일 바인딩
(/home/kafka/akhq-docker/application.yml 경로는 절대경로여야 함) - tchiotludo/akhq → AKHQ Docker 이미지 사용
application.yml은 AKHQ 실행 설정 파일로 "4.AKHQ 환경 설정: application.yml" 에서 자세하게 설명하겠습니다.
3. AKHQ 설치 방법 : Standalone
1. Java 17 설치 확인
kafka@osboxes:~/akhq$ java -version
openjdk version "17.0.14" 2025-01-21
OpenJDK Runtime Environment (build 17.0.14+7-Ubuntu-124.04)
OpenJDK 64-Bit Server VM (build 17.0.14+7-Ubuntu-124.04, mixed mode, sharing)
2. Jar 파일 다운로드: https://github.com/tchiotludo/akhq/releases
Releases · tchiotludo/akhq
Kafka GUI for Apache Kafka to manage topics, topics data, consumers group, schema registry, connect and more... - tchiotludo/akhq
github.com
3. 실행
java -Dmicronaut.config.files=/home/kafka/akhq/application.yml -jar akhq-0.25.1-all.jar
application.yml은 AKHQ 실행 설정 파일로 " 4.AKHQ 환경 설정: application.yml "에서 자세하게 설명하겠습니다.
4. AKHQ 환경 설정: application.yml
설정은 모두 application.yml 파일에 작성하며, 서버 포트, Kafka 연결, 인증, 권한 등을 제어할 수 있습니다.
아래는 basic-auth만 사용하도록 작성된 application.yml 예시와 함께 항목별로 설명한 내용입니다.
# Micronaut는 AKHQ 내부에서 사용하는 경량 웹 프레임워크입니다.
# 보안 설정을 Micronaut 기반으로 제어합니다.
micronaut:
security:
enabled: true # 보안 기능 활성화 (로그인 기능 사용)
basic-auth:
enabled: true # 기본 인증 방식(ID/비밀번호) 사용 활성화
ldap:
default:
enabled: false # LDAP 인증 비활성화 (사용하지 않음)
oauth2:
enabled: false # OAuth2 인증 비활성화 (사용하지 않음)
token:
jwt:
signatures:
secret:
generator:
secret: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
# JWT 서명용 시크릿 키 (로그인 후 토큰 생성 시 사용됨)
# 주의: 외부에 노출되지 않도록 관리해야 함
server:
port: 9090 # AKHQ가 실행될 포트 (기본값 8080 → 여기선 9090으로 변경)
context-path: "" # 루트 경로에서 실행 (http://localhost:9090 으로 접속 가능)
# AKHQ 설정 영역
akhq:
connections:
my-kafka-cluster: # 클러스터 이름 (AKHQ UI에서 보여질 이름)
properties:
bootstrap.servers: "192.168.56.101:9092,192.168.56.102:9092,192.168.56.103:9092"
# Kafka 클러스터의 브로커 리스트 (쉼표로 구분)
# AKHQ 컨테이너 또는 실행 머신이 접근 가능한 IP/포트여야 함
security:
default-group: admin # 로그인 사용자가 기본으로 속할 그룹 (생략 시 오류 가능)
basic-auth:
- username: admin # 로그인 사용자 ID
password: e4abae53cc1cebe5fe89ea93882c699a5e71ab0bbf42a83b7d833975b61c4a41
# SHA-256 해시된 비밀번호 (예: "adminpass123"을 해시한 값)
groups:
- admin # 이 사용자가 속한 그룹 (권한은 아래 roles에서 정의)
roles:
admin:
- resources: # admin 그룹이 접근 가능한 리소스 종류
- NODE # 클러스터 노드 정보
- TOPIC # 토픽 생성/삭제
- TOPIC_DATA # 토픽 메시지 보기
- SCHEMA # 스키마 레지스트리
- CONNECTOR # Kafka Connect
- CONSUMER_GROUP # 컨슈머 그룹
- CONNECT_CLUSTER # 커넥트 클러스터
- KSQLDB # KSQLDB (선택적 사용)
actions: # 해당 리소스에 대해 수행 가능한 액션
- READ # 조회 권한
- CREATE # 생성 권한
- DELETE # 삭제 권한
- UPDATE # 수정 권한
- READ_CONFIG # 구성 읽기
- ALTER_CONFIG # 구성 수정
- EXECUTE # 실행 권한 (KSQL 쿼리 등)
- UPDATE_STATE # 상태 업데이트 (예: connector 상태 변경)
- DELETE_VERSION # 스키마 버전 삭제
AKHQ에서 사용하는 basic-auth 비밀번호는 평문이 아닌 SHA-256 해시 값으로 저장해야 합니다.
echo -n "adminpass123" | sha256sum
e4abae53cc1cebe5fe89ea93882c699a5e71ab0bbf42a83b7d833975b61c4a41 -
여기서 앞의 64자리 해시 값만 복사해서 application.yml에 입력하면 됩니다.
5. AKHQ 접속 확인
http://192.168.56.102:9090
6. AKHQ 서비스 등록하기
1. Systemd 서비스 파일 작
sudo vi /etc/systemd/system/akhq.service[Unit]
Description=AKHQ Kafka Web UI
After=network.target
[Service]
Type=simple
User=kafka
WorkingDirectory=/home/kafka/akhq
ExecStart=/usr/bin/java -Dmicronaut.config.files=/home/kafka/akhq/application.yml -jar /home/kafka/akhq/akhq-0.25.1-all.jar
SuccessExitStatus=143
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
2. 서비스 등록 및 실행
1. systemd가 새로 만든 서비스 파일을 인식
sudo systemctl daemon-reload
2. 서버가 부팅될 때 AKHQ 서비스가 자동으로 실행되도록 설정
sudo systemctl enable akhq.service
Created symlink /etc/systemd/system/multi-user.target.wants/akhq.service → /etc/systemd/system/akhq.service.
3.AKHQ 서비스를 지금 바로 실행
sudo systemctl start akhq.service
3. 서비스 실행 확인
ps aux | grep akhq
http://192.168.56.102:9090 접속하여 동작을 확인합니다.
AKHQ 설치 및 설정 방법을 Docker와 Standalone 방식으로 알아보았습니다.
application.yml을 통한 사용자 인증 구성과 서비스 등록까지 완료하면, Kafka 클러스터를 웹 UI에서 안전하고 효율적으로 관리할 수 있습니다.
관련 글 링크
Home | AKHQ
Manage Allowing to manage your topics, consumer groups, cluster configurations, users and ACLs.
akhq.io
Quick preview | AKHQ
It will start a Kafka node, a Zookeeper node, a Schema Registry, a Kafka Connect, fill with some sample data, start a consumer group and a kafka stream & start AKHQ. More standard installation can be found here
akhq.io
3.Ubuntu에 Docker 설치 및 sudo 없이 사용하기
Ubuntu에서 Docker를 설치하고, sudo 없이 편리하게 사용하는 방법까지 단계별로 안내합니다. 기존 패키지 제거, GPG 키 등록, 저장소 설정, 서비스 실행 등 핵심 과정을 모두 포함합니다. Ubuntu에 Dock
quadcube.tistory.com
5.실무에서 자주 쓰는 Docker 명령어 정리(예제 + 설명)
Docker를 활용해 실무에서 자주 수행하는 작업들을 중심으로 명령어 예제들을 구성했습니다. 개발, 테스트, 배포 환경에서 많이 사용하는 실전 위주의 예제를 소개합니다. 실무에서 자주 쓰는 D
quadcube.tistory.com
7. systemctl 명령어 요약 정리(서비스 등록 및 관리)
Linux 시스템의 서비스 관리에 필수적인 systemctl 명령어를 정리했습니다. 서비스 시작, 자동 실행 설정, 로그 확인 등 systemd 기반 시스템 운영에 꼭 필요한 명령어를 실용 예시와 함께 설명합니다.
quadcube.tistory.com