15. Apache Kafka UI 관리도구 AKHQ 설치 및 설정 하기: 사용자 인증

 

반응형

 

Apache Apache Kafka를 웹 UI로 관리할 수 있는 도구인 AKHQ 설치 및 설정 방법을 소개합니다.
Docker 및 Standalone 방식 설치부터 application.yml 설정과 사용자 인증 구성, 서비스 등록까지 자세히 정리했습니다.

 

Apache Kafka UI 관리도구 AKHQ 설치 및 설정 하기: 사용자 인증

 

목차

1. AKHQ란?

2. AKHQ 설치 방법: Docker

3. AKHQ 설치 방법: Standalone

4. AKHQ 환경 설정: application.yml

5. AKHQ 접속 확인

6. AKHQ 서비스 등록하기

관련 글 링크

 

 

1. AKHQ란?

AKHQ는 Apache Kafka를 시각적으로 관리할 수 있는 웹 UI 도구입니다.
프로듀서, 컨슈머, 토픽, 파티션, ACL 등을 브라우저에서 손쉽게 확인하고 제어할 수 있습니다.

특징

• Kafka 클러스터 정보 시각화
• 토픽 생성 및 삭제 기능
• 메시지 확인 및 검색
• 컨슈머 그룹 상태 추적
• ACL 관리 기능 (선택)

관리도구 비교문서

https://towardsdatascience.com/overview-of-ui-tools-for-monitoring-and-management-of-apache-kafka-clusters-8c383f897e80/

Overview of UI Tools for Monitoring and Management of Apache Kafka Clusters | Towards Data Science

 

 

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

 

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에서 안전하고 효율적으로 관리할 수 있습니다.

 

 

반응형

 

관련 글 링크

• https://akhq.io/

Home | AKHQ

• https://akhq.io/docs/

Quick preview | AKHQ

• 3.Ubuntu에 Docker 설치 및 sudo 없이 사용하기

3.Ubuntu에 Docker 설치 및 sudo 없이 사용하기

• 5.실무에서 자주 쓰는 Docker 명령어 정리(예제 + 설명)

5.실무에서 자주 쓰는 Docker 명령어 정리(예제 + 설명)

• 7. systemctl 명령어 요약 정리(서비스 등록 및 관리)

7. systemctl 명령어 요약 정리(서비스 등록 및 관리)