Kafka 플러그인

Kafka 플러그인은 Apache Kafka 클러스터를 하나의 Konduo 리소스로 등록하고 브로커, 컨트롤러, 토픽, 파티션, 컨슈머 그룹 상태를 운영 근거로 제공합니다.

특징

• 부트스트랩 서버를 시드로 사용하고 Kafka 메타데이터에서 브로커 리스너와 클러스터 ID를 검증합니다.
• KRaft/컨트롤러 역할, 브로커 인벤토리, 토픽/파티션 상태, 컨슈머 그룹 지연과 오프셋 근거를 관리 화면에 노출합니다.
• Prometheus 매핑팩으로 JMX/익스포터 계열 메트릭을 연결합니다.
• 혼합 수집 모드에서는 브로커 메트릭은 외부 메트릭 소스를 사용하고, 컨슈머 그룹 지연은 Kafka Admin API로 직접 수집할 수 있습니다.

등록 전 확인

• 부트스트랩 서버, 보안 프로토콜, SASL, TLS, 제한 시간 설정을 준비합니다.
• 브로커 advertised listener에 Konduo 백엔드가 접근할 수 있는지 확인합니다.
• 컨슈머 그룹 지연 관리형 수집을 쓰려면 Admin API 접근 권한과 원격 쓰기 대상을 준비합니다.
• 원격 쓰기 대상으로 Prometheus를 사용할 경우 Prometheus를 --web.enable-remote-write-receiver 옵션으로 실행해야 합니다.

운영 팁

• 부트스트랩 브로커가 내려가도 발견된 브로커 엔드포인트가 살아 있으면 일부 운영은 계속 가능할 수 있습니다.
• 컨슈머 지연은 최신 스냅샷 기반 신호이므로 지연 총량, 최대 지연, 멤버 상태, 오프셋 이동을 함께 봅니다.
• 토픽 파티션 변경, 재배치, 처리량 제한, ACL/쿼터 같은 작업은 확인과 권한 경계 안에서 실행합니다.
• 메시지 검색은 토픽 운영 보조 기능입니다. 전체 토픽을 대상으로 스캔할 수 있더라도 전송률 제한과 취소 가능성을 유지하고, 대량 내보내기나 ETL 대체 수단으로 사용하지 않습니다.
• 트랜잭션 메시지를 확인할 때는 read_committed와 전체 표시의 차이를 명확히 구분합니다. read_committed는 커밋 완료된 트랜잭션 레코드와 비트랜잭션 레코드만 보여줍니다.

운영 화면

• 브로커 인벤토리는 노드 ID, 리스너, KRaft 역할, 컨트롤러 여부, 파티션/복제본 수, 데이터 크기, cordon 상태를 함께 보여줍니다.
• 토픽 화면은 파티션 수, 복제 계수, 내부 토픽 여부, 설정, ACL, 메시지 검색/생성 작업을 한 곳에서 확인하게 합니다.
• 재배치 작업 화면은 브로커 비우기, 재균형, 복제본 변경 계획을 사전 점검으로 계산하고 예상 이동량과 대상 브로커를 보여줍니다.
• 컨슈머 그룹 화면은 일반 컨슈머 그룹, 공유 그룹, Connect, Schema Registry 같은 그룹 종류를 구분해 지연과 멤버 상태를 해석하기 쉽게 합니다.
• 보안 화면은 SCRAM 사용자, ACL, 쿼터, 위임 토큰, 트랜잭션 ID 근거를 운영 권한 안에서 확인하고 필요한 변경 작업을 제공합니다.
• 메시지 조회, 스트리밍, 검색은 트랜잭션 표시 옵션을 제공하며 read_committed를 선택하면 중단되었거나 아직 커밋되지 않은 트랜잭션 레코드를 제외합니다. 비트랜잭션 레코드는 계속 표시됩니다.
• 토픽 상세 화면에서는 토픽에 연결된 ACL과 활성 프로듀서 근거를 확인할 수 있습니다. 활성 프로듀서 근거는 프로듀서 ID/세대, 코디네이터 세대, 마지막 시퀀스, 현재 트랜잭션 시작 오프셋을 보고 트랜잭션 장애 범위를 좁히는 데 사용합니다.
• 트랜잭션 ID 화면은 트랜잭션 ID 상태와 코디네이터, 프로듀서 ID를 보여주며 행 상세, 관련 ACL 이동, 활성 트랜잭션 조치 흐름을 제공합니다.
• SCRAM 사용자 화면에서 보안 주체별 ACL 목록으로 이동할 수 있고, 해당 맥락에서 ACL을 추가하면 보안 주체가 자동으로 채워집니다.

메시지 조회와 생성

• 메시지 조회/스트리밍/검색은 키/값 역직렬화와 트랜잭션 표시 방식을 분리해서 설정합니다.
• __consumer_offsets의 classic offset commit/group metadata와 __transaction_state 메시지는 키/값을 자동 파싱해 그룹, 토픽/파티션, 커밋 오프셋, 멤버 subscription/assignment, 트랜잭션 상태와 프로듀서 정보를 구조화해서 보여줍니다.
• 내부 토픽의 tombstone은 빈 바이트 값과 구분되며, 알 수 없는 Kafka coordinator 레코드 유형이나 손상된 메시지는 디코드 상태와 원본 키/값의 hex 근거를 함께 표시합니다. 파싱된 키/값은 바이너리를 String으로 강제 변환하지 않고 전체 JSON으로 표시합니다.
• read_committed는 중단되었거나 아직 커밋되지 않은 트랜잭션 레코드를 숨깁니다. 장애 분석에서 “프로듀서는 썼다고 했는데 컨슈머가 못 본다”는 상황을 확인할 때 유용합니다.
• 커스텀 단건 발행은 키, 값, 헤더를 운영자가 직접 입력하는 기능입니다. 헤더는 한 줄에 하나씩 key=value 형태로 입력하며, 값은 입력 그대로 발행됩니다.
• 템플릿 발행은 내장 스키마 또는 확장 기여로 제공된 스키마를 반복 렌더링합니다. JSON/YAML 형식, 키 전략, 메시지 수, 초당 전송량, 사전 점검을 함께 설정합니다.
• 완료된 메시지 생성 작업은 작업 큐에서 일괄 정리할 수 있습니다. 이 작업은 Konduo 작업 이력 정리이며 Kafka 토픽 데이터를 삭제하지 않습니다.
• 메시지 검색 결과 페이로드는 가벼운 작업 상태보다 먼저 만료될 수 있습니다. result_available=false, result_expired=true이면 작업 자체는 확인되지만 메모리의 매치 결과가 보관 시간 또는 전체 바이트 한도로 정리된 상태이며, Kafka 메시지가 삭제되었다는 의미가 아닙니다.
• 성공한 메시지 생성 작업은 실제 결과가 Kafka 토픽에 남으므로 짧은 확인 시간만 유지하고, 실패/취소 진단은 더 오래 보관합니다. 모든 작업 이력은 프로세스 메모리에만 있으므로 플러그인을 재시작하면 사라집니다.

진단과 알림 관점

• 진단은 브로커/컨트롤러 상태, 파티션 안전성, 복제 부족/오프라인 파티션, 컨슈머 지연, 재배치 상태, 메트릭 수집 범위를 분리해서 보여줍니다.
• min.insync.replicas 같은 클러스터 공통 기본값은 Kafka 클러스터당 한 번만 평가합니다. 브로커가 서로 다른 값을 반환하면 클러스터 일관성 경고 한 건으로 표시하고, 토픽별 override는 각 토픽 단위로 계속 평가합니다.
• Kafka 자체 가용성은 메타데이터와 advertised listener 접근성으로 판단하고, JMX/익스포터 메트릭은 용량과 부하 위험을 보조하는 근거로 사용합니다.
• 알림 규칙은 오프라인 파티션, 복제 부족 파티션, 컨트롤러 이상, 요청 처리기 압박, 컨슈머 지연 같은 Kafka 도메인 위험을 다룹니다.
• 메트릭 소스가 없거나 매핑팩이 맞지 않으면 정상으로 추정하지 않고 사용 불가 또는 부분 근거로 표시하는 것이 올바른 상태입니다.

관리 경계

• 브로커 비우기와 재균형은 오프라인 브로커와 cordon된 브로커를 새 복제본 배치 대상에서 제외해야 합니다.
• 트래픽 기반 재배치 계획은 현재 Kafka 리소스 범위로 확인된 메트릭 근거만 사용합니다. 범위가 확인된 토픽 또는 브로커 근거가 없으면 전역 메트릭을 대신 사용하지 않고 계획을 거부합니다.
• Kafka 4.3 이상에서 cordoned.log.dirs=*를 지원하면 브로커 비우기 전에 대상 브로커를 cordon할 수 있지만, 비우기 완료 후 cordon 해제는 운영자가 명시적으로 실행합니다.
• Kafka 4.3.1 기준으로 수동 재배치가 cordon된 브로커를 완전히 회피하지 못하는 동작이 관측될 수 있습니다. Konduo의 브로커 비우기/재균형 계획은 cordon된 브로커를 새 대상으로 제외하지만, Kafka 자체 수동 계획을 외부에서 제출할 때는 별도 검토가 필요합니다.
• 브로커가 비어 있으면 비우기 작업은 더 이상 의미가 없고, cordon 상태이면 비우기 대신 cordon 복구를 먼저 검토합니다.
• cordoned.log.dirs처럼 기본값이 null인 브로커 설정은 값을 비우는 것이 아니라 동적 설정 삭제/reset으로 복구합니다.
• 메시지 검색/생성 작업은 토픽 운영 보조 기능이며, 대량 데이터 복구나 스트림 처리 대체 수단으로 사용하지 않습니다.
• ACL, 쿼터, SCRAM, 위임 토큰 변경은 Kafka 보안 모델에 직접 영향을 주므로 RBAC, 확인 문구, 감사 로그 경계를 유지해야 합니다.

보안과 트랜잭션 분석

• 토픽, 컨슈머 그룹, 트랜잭션 ID의 ACL 목록은 Kafka 권한 부여 API가 사용 가능할 때만 표시됩니다. 권한 부족이나 권한 부여 기능 비활성 상태는 빈 목록과 구분해서 해석해야 합니다.
• ACL 행의 리소스 이름, 패턴 타입, 보안 주체, 호스트, 작업, 권한을 함께 보고, 접두어/와일드카드 ACL이 실제 리소스에 영향을 주는지 확인합니다.
• 트랜잭션 ID 상세는 현재 상태가 활성/열림 계열인지, 이미 커밋 완료/중단 완료 상태인지에 따라 조치 가능성이 달라집니다. 이미 완료된 트랜잭션은 중단 대상이 아닙니다.
• 프로듀서 fencing은 같은 트랜잭션 ID를 사용하는 프로듀서 세대를 밀어내는 강한 조치입니다. 애플리케이션 재시작, 중복 프로듀서, 트랜잭션 멈춤 근거를 확인한 뒤 사용합니다.

대표 시나리오

• 브로커 교체 전에는 브로커 인벤토리에서 파티션/복제본 수와 데이터 크기를 확인하고, 브로커 비우기 사전 점검으로 이동 계획을 검토합니다.
• 컨슈머 지연이 발생하면 그룹 상태, 멤버 수, 파티션별 지연, 최대 지연, 최근 오프셋 이동을 함께 확인합니다.
• 토픽 증설 전에는 파티션 수 변경, 복제 계수, 브로커별 분포, 트래픽 근거를 비교해 불균형을 만들지 않는지 확인합니다.
• 인증/권한 장애가 의심되면 보안 주체별 ACL, SCRAM 상태, 쿼터, 트랜잭션 ID 사용 흔적을 순서대로 확인합니다.
• 트랜잭션 멈춤이 의심되면 트랜잭션 ID 목록에서 상태와 프로듀서 ID를 확인하고, 토픽의 활성 프로듀서 근거와 ACL을 함께 본 뒤 중단/세대 밀어내기 여부를 결정합니다.

---

Kafka Enterprise 확장

Kafka Enterprise 확장은 Community Kafka 플러그인 위에 MCP 설명자와 이상 징후 규칙 메타데이터를 추가합니다.

특징

• MCP 카탈로그에서 모니터링 개요, 진단, 컨슈머 그룹, 보안 작업, 메트릭 매핑, 이상 징후 규칙을 조회합니다.
• 이상 징후 규칙은 declarative_metric 방식으로 Kafka 논리 메트릭을 메트릭 소스 매핑에 연결합니다.
• 재배치, 브로커 비우기, 복제본 변경, 토픽 변경, 메시지 작업 같은 변경성 업무 흐름은 기존 Konduo API, RBAC, 감사 경계를 따릅니다.
• 부트스트랩 주소는 시드로만 보고, 브로커 인벤토리와 advertised listener 근거를 함께 해석합니다.
• Community 기반 화면의 브로커 cordon, 메시지 조회/생성, 트랜잭션 ID, 활성 프로듀서, 토픽/그룹 ACL 근거를 MCP와 장애 분석 맥락에서 참조합니다.

주요 용도

1. Kafka 운영 상태를 MCP 리소스와 도구로 조회
2. 브로커, 파티션, 컨슈머 그룹 상태를 읽기 중심으로 탐색
3. Enterprise 이상 징후 규칙 카탈로그 확인
4. 운영 대시보드와 진단 결과를 에이전트 워크플로우에 연결

등록 전 확인

• Kafka 기본 연결과 권한은 Community Kafka 플러그인 설정을 따릅니다.
• MCP 게이트웨이와 관련 권한 프로필이 활성화되어 있어야 MCP 설명자를 사용할 수 있습니다.
• 이상 징후 규칙은 Enterprise 분석 엔진이 활성화된 환경에서 운영됩니다.

운영 팁

• MCP 도구는 운영 조회와 분석 보조 용도로 사용하고, 설정 변경은 Konduo 화면과 승인된 운영 절차를 따릅니다.
• 이상 징후 규칙은 알림 규칙을 대체하지 않으며, 상관관계 분석과 장애 분석의 보조 신호로 다룹니다.
• 컨슈머 지연 분석은 지연 총량, 최대 지연, 멤버 상태, 오프셋 이동, 컨트롤러 상태를 함께 봅니다.
• 메시지 조회/검색에서 read_committed는 중단되었거나 아직 커밋되지 않은 트랜잭션 레코드를 제외하므로, 프로듀서와 컨슈머 관측 차이를 분석할 때 유용합니다.
• __consumer_offsets의 classic offset commit/group metadata와 __transaction_state 메시지는 키/값을 자동 파싱해 그룹, 토픽/파티션, 커밋 오프셋, 멤버 subscription/assignment, 트랜잭션 상태와 프로듀서 정보를 구조화해서 보여줍니다.
• 내부 토픽의 tombstone은 빈 바이트 값과 구분되며, 알 수 없는 Kafka coordinator 레코드 유형이나 손상된 메시지는 디코드 상태와 원본 키/값의 hex 근거를 함께 표시합니다. 파싱된 키/값은 바이너리를 String으로 강제 변환하지 않고 전체 JSON으로 표시합니다.
• 커스텀 단건 발행은 키, 값, 헤더를 운영자가 직접 입력하는 기능입니다. 헤더는 한 줄에 하나씩 key=value 형태로 입력하며, 값은 입력 그대로 발행됩니다.
• 템플릿 발행은 내장 스키마 또는 확장 기여로 제공된 스키마를 반복 렌더링합니다. JSON/YAML 형식, 키 전략, 메시지 수, 초당 전송량, 사전 점검을 함께 설정합니다.
• 완료된 메시지 생성 작업은 작업 큐에서 일괄 정리할 수 있습니다. 이 작업은 Konduo 작업 이력 정리이며 Kafka 토픽 데이터를 삭제하지 않습니다.
• 메시지 검색 결과 페이로드는 가벼운 작업 상태보다 먼저 만료될 수 있습니다. result_available=false, result_expired=true이면 작업 자체는 확인되지만 메모리의 매치 결과가 보관 시간 또는 전체 바이트 한도로 정리된 상태이며, Kafka 메시지가 삭제되었다는 의미가 아닙니다.
• 성공한 메시지 생성 작업은 실제 결과가 Kafka 토픽에 남으므로 짧은 확인 시간만 유지하고, 실패/취소 진단은 더 오래 보관합니다. 모든 작업 이력은 프로세스 메모리에만 있으므로 플러그인을 재시작하면 사라집니다.
• Kafka 4.3 이상에서 cordoned.log.dirs=*를 사용하는 브로커 비우기는 배치 안전성을 높이지만, cordon 해제는 브로커가 비워진 뒤 명시적으로 복구합니다.

진단과 알림 관점

• 진단은 브로커/컨트롤러 상태, 파티션 안전성, 복제 부족/오프라인 파티션, 컨슈머 지연, 재배치 상태, 메트릭 수집 범위를 분리해서 보여줍니다.
• min.insync.replicas 같은 클러스터 공통 기본값은 Kafka 클러스터당 한 번만 평가합니다. 브로커가 서로 다른 값을 반환하면 클러스터 일관성 경고 한 건으로 표시하고, 토픽별 override는 각 토픽 단위로 계속 평가합니다.
• Kafka 자체 가용성은 메타데이터와 advertised listener 접근성으로 판단하고, JMX/익스포터 메트릭은 용량과 부하 위험을 보조하는 근거로 사용합니다.
• 알림 규칙은 오프라인 파티션, 복제 부족 파티션, 컨트롤러 이상, 요청 처리기 압박, 컨슈머 지연 같은 Kafka 도메인 위험을 다룹니다.
• 메트릭 소스가 없거나 매핑팩이 맞지 않으면 정상으로 추정하지 않고 사용 불가 또는 부분 근거로 표시하는 것이 올바른 상태입니다.

관리 경계

• 브로커 비우기와 재균형은 오프라인 브로커와 cordon된 브로커를 새 복제본 배치 대상에서 제외해야 합니다.
• 트래픽 기반 재배치 계획은 현재 Kafka 리소스 범위로 확인된 메트릭 근거만 사용합니다. 범위가 확인된 토픽 또는 브로커 근거가 없으면 전역 메트릭을 대신 사용하지 않고 계획을 거부합니다.
• Kafka 4.3 이상에서 cordoned.log.dirs=*를 지원하면 브로커 비우기 전에 대상 브로커를 cordon할 수 있지만, 비우기 완료 후 cordon 해제는 운영자가 명시적으로 실행합니다.
• Kafka 4.3.1 기준으로 수동 재배치가 cordon된 브로커를 완전히 회피하지 못하는 동작이 관측될 수 있습니다. Konduo의 브로커 비우기/재균형 계획은 cordon된 브로커를 새 대상으로 제외하지만, Kafka 자체 수동 계획을 외부에서 제출할 때는 별도 검토가 필요합니다.
• 브로커가 비어 있으면 비우기 작업은 더 이상 의미가 없고, cordon 상태이면 비우기 대신 cordon 복구를 먼저 검토합니다.
• cordoned.log.dirs처럼 기본값이 null인 브로커 설정은 값을 비우는 것이 아니라 동적 설정 삭제/reset으로 복구합니다.
• 메시지 검색/생성 작업은 토픽 운영 보조 기능이며, 대량 데이터 복구나 스트림 처리 대체 수단으로 사용하지 않습니다.
• ACL, 쿼터, SCRAM, 위임 토큰 변경은 Kafka 보안 모델에 직접 영향을 주므로 RBAC, 확인 문구, 감사 로그 경계를 유지해야 합니다.

운영 시나리오

• 브로커 비우기나 재균형 전후에는 MCP/진단 경로로 브로커 인벤토리, 컨트롤러 상태, 파티션 분포, 메트릭 수집 범위를 빠르게 비교합니다.
• 비우기/재균형 분석에서는 오프라인 브로커와 cordon된 브로커가 새 복제본 대상에서 제외되는지 확인하고, 외부에서 제출한 수동 재배치 계획은 별도 검토합니다.
• 컨슈머 그룹 장애 분석에서는 일반 그룹, 공유 그룹, Kafka Connect, Schema Registry 성격을 구분해 지연과 멤버 상태를 해석합니다.
• 보안 장애가 의심되면 SCRAM, ACL, 쿼터, 위임 토큰, 트랜잭션 ID 근거를 순서대로 확인하고 변경은 감사되는 작업 경로로 처리합니다.
• 트랜잭션 멈춤이 의심되면 트랜잭션 ID 상태, 토픽별 활성 프로듀서 근거, 관련 ACL을 함께 확인한 뒤 중단 또는 프로듀서 세대 밀어내기 여부를 판단합니다.
• 메트릭 매핑팩이 환경별 익스포터 라벨 차이로 맞지 않을 때는 EE 매핑팩 가져오기/내보내기를 통해 고객 사이트 기준으로 조정합니다.

경계

• Kafka 토픽, ACL, 재배치, 메시지 발행 같은 상태 변경은 MCP 설명자로 우회하지 않고 기존 Konduo API, RBAC, 확인 문구, 감사 경계를 유지합니다.
• Kafka 4.3 이상 cordon 보조 정보와 비우기/재균형 판단은 운영 안전성 신호로 사용하되, Kafka 자체 재배치 동작의 한계는 플러그인에서 무리하게 숨기지 않습니다.
• ACL, SCRAM, 쿼터, 위임 토큰, 트랜잭션 ID 관련 변경은 Enterprise 분석 자동화가 아니라 승인된 작업 경로와 감사 로그를 통해 수행합니다.