Keeper HTTP API 및 대시보드

ClickHouse Keeper HTTP API 및 내장 웹 대시보드 문서

ClickHouse Keeper는 모니터링, 상태 확인, 스토리지 관리를 위한 HTTP API와 내장 웹 대시보드를 제공합니다. 이 인터페이스를 통해 운영자는 웹 브라우저 또는 HTTP 클라이언트에서 클러스터 상태를 확인하고, 명령을 실행하며, Keeper 스토리지를 관리할 수 있습니다.

​

구성

HTTP API를 활성화하려면 keeper_server 구성에 http_control 섹션을 추가하세요:

<keeper_server>
    <!-- 다른 keeper_server 구성 -->

    <http_control>
        <port>9182</port>
        <!-- <secure_port>9443</secure_port> -->
    </http_control>
</keeper_server>

​

구성 옵션

설정	기본값	설명
http_control.port	-	대시보드 및 API용 HTTP 포트
http_control.secure_port	-	HTTPS 포트(SSL 구성 필요)
http_control.readiness.endpoint	/ready	준비 상태 프로브의 사용자 지정 경로
http_control.storage.session_timeout_ms	30000	스토리지 API 작업의 세션 시간 초과 값

​

엔드포인트

​

대시보드

• 경로: /dashboard
• 메서드: GET
• 설명: Keeper를 모니터링하고 관리할 수 있는 내장 웹 대시보드를 제공합니다

대시보드에서 다음 기능을 제공합니다:

• 실시간 클러스터 상태 시각화
• 노드 모니터링(역할, 지연 시간, 연결)
• 스토리지 브라우저
• 명령 실행 인터페이스

​

클러스터 탭

클러스터 탭은 Raft 멤버십을 토폴로지 그래프와 테이블로 표시합니다. 각 멤버는 상태에 따라 색상으로 표시됩니다.

• 녹색 — 정상 상태이며 리더와 동기화됨
• 노란색 — 정상 상태이나 리더보다 stale_log_gap개의 로그 항목 이상 뒤처짐
• 빨간색 — 연결할 수 없음(하트비트 만료 시간 내에 성공적인 Raft 응답이 없음)
• 회색 — 알 수 없음(피어 상태는 리더에서만 확인할 수 있으며, 팔로워에서는 피어 상태가 알 수 없음으로 표시됨)

테이블에는 각 멤버의 역할(리더, 팔로워 또는 옵저버), Raft 우선순위, 마지막 로그 인덱스, 리더 대비 복제 지연, 마지막으로 성공한 Raft 응답 이후 경과 시간도 표시됩니다. 현재 노드가 리더가 아닌 경우, 탭에서 전체 피어 상태를 확인할 수 있는 리더의 대시보드를 여는 딥 링크를 제공합니다. /dashboard?tab=cluster를 사용하여 탭을 직접 열 수 있습니다.

​

준비 상태 프로브

• 경로: /ready (구성 가능)
• 메서드: GET
• 설명: 상태 확인 엔드포인트

성공 응답(HTTP 200):

{
  "status": "ok",
  "details": {
    "role": "leader",
    "hasLeader": true
  }
}

​

Commands API

• 경로: /api/v1/commands/{command}
• 메서드: GET, POST
• 설명: Four-Letter Word 명령 또는 ClickHouse Keeper Client CLI 명령을 실행합니다

쿼리 매개변수:

• command - 실행할 명령
• cwd - 경로 기반 명령에 대한 현재 작업 디렉터리 (기본값: /)

예시:

# Four-Letter Word 명령어
curl http://localhost:9182/api/v1/commands/stat

# ZooKeeper CLI 명령어
curl "http://localhost:9182/api/v1/commands/ls?command=ls%20'/'&cwd=/"

​

Storage API

• 기본 경로: /api/v1/storage
• 설명: Keeper 스토리지 작업을 위한 REST API

Storage API는 HTTP 메서드로 작업 유형을 나타내는 REST 규약을 따릅니다:

작업	경로	메서드	상태 코드	설명
가져오기	/api/v1/storage/{path}	GET	200	노드 데이터 가져오기
목록	/api/v1/storage/{path}?children=true	GET	200	하위 노드 나열
존재 확인	/api/v1/storage/{path}	HEAD	200	노드 존재 여부 확인
생성	/api/v1/storage/{path}	POST	201	새 노드 생성
업데이트	/api/v1/storage/{path}?version={v}	PUT	200	노드 데이터 업데이트
삭제	/api/v1/storage/{path}?version={v}	DELETE	204	노드 삭제