아키텍처

Kubetail은 소수의 목적이 분명한 도구와 서비스로 구성됩니다. 어떤 것은 필수이고, 어떤 것은 선택 사항이며 추가 기능을 열어 줍니다. 이 페이지에서는 배포 토폴로지, 로그 전달 파이프라인, 그리고 개별 구성 요소를 자세히 설명합니다.

배포 토폴로지

Kubetail은 환경과 접근 요구 사항에 따라 세 가지 방식으로 배포할 수 있습니다. 각 토폴로지는 동일한 기본 구성 요소를 사용하지만, 설치 방식과 접근 방식, 설정 방식이 다릅니다.

데스크톱

가장 일반적인 토폴로지에서는 kubetail CLI가 로컬 머신에 설치되어 있고, kubeconfig 파일을 사용해 클러스터에 인증합니다. 이는 kubetail이 kubectl과 동일한 RBAC 권한을 상속받기 때문에 편리하며, 추가 변경 없이 로그에 접근할 수 있습니다.

데스크톱에서 kubetail serve를 실행하면 Dashboard Server가 로컬에서 시작되고, Dashboard UI를 제공하며, 사용자를 대신해 로그 요청을 클러스터의 Kubernetes API로 프록시합니다. kubetail logs를 사용해 로그를 터미널로 직접 스트리밍할 수도 있습니다. 시작하는 데 클러스터 측 설치는 필요 없지만, 클러스터에 Kubetail API를 설치하면 kubetail이 이를 자동으로 사용해 검색 같은 고급 기능을 활성화합니다.

설치 방법은 데스크톱 설치 가이드를 참고하세요.

클러스터

Kubetail 전체 스택은 Helm 또는 YAML 매니페스트를 사용해 클러스터 내부의 Kubernetes 리소스로 설치할 수 있습니다. 이 토폴로지에서는 Dashboard Server가 kubetail-system namespace의 Deployment로 실행되며, 브라우저에서 kubectl port-forward, kubectl proxy, 또는 ingress 리소스를 통해 접근합니다. 이는 팀이 공유하는 환경이나, 로컬 CLI에 의존하지 않고 항상 켜져 있는 지속적인 접근이 필요한 경우에 선호되는 방식입니다.

설치 방법은 클러스터 설치 가이드를 참고하세요.

Docker

kubetail CLI는 Docker 이미지(kubetail/kubetail-cli)로 패키징되어 있으므로, 로컬 설치 없이 컨테이너 안에서 실행할 수 있습니다. 로컬에서는 .kube/config 파일을 컨테이너에 마운트하고 docker run 또는 docker-compose를 사용해 대시보드를 시작할 수 있습니다. 이 이미지는 클러스터 내부의 Pod로도 배포할 수 있으며, 이 경우 --in-cluster 플래그를 사용해 kubeconfig 파일 대신 Pod의 service account 자격 증명으로 인증합니다.

Docker 배포 옵션에 대한 자세한 내용은 Docker 소개를 참고하세요.

로그 전달 파이프라인

기본적으로 Kubetail은 Kubernetes API를 사용해 로그를 가져옵니다. 마지막 이벤트 타임스탬프와 검색 같은 고급 기능을 활성화하려면 Kubetail Cluster API와 Kubetail Cluster Agent(통칭 “Kubetail API”)를 설치할 수 있습니다. 아래에서는 각 모드를 좀 더 자세히 설명합니다.

Kubernetes API (기본값)

Cluster API가 설정되어 있지 않으면 로그는 Kubernetes API를 통해 전달됩니다. 예를 들어, 웹 대시보드에서 디스크의 파일까지 Kubernetes API를 사용하는 요청 경로는 다음과 같습니다.

+---------------------------------+
| Kubetail Dashboard UI (Browser) |
+---------------------------------+
          │
          │ GraphQL over WebSocket
          ▼
+---------------------------------+
| Kubetail Dashboard Server       |
+---------------------------------+
          │
          │ HTTP GET /api/v1/namespaces/{ns}/pods/{pod}/log
          ▼
+---------------------------------+
| kube-apiserver                  |
+---------------------------------+
          │
          │ HTTP → kubelet /containerLogs
          ▼
+---------------------------------+
| kubelet (node)                  |
+---------------------------------+
          │
          │ file read
          ▼
+---------------------------------+
| Pod log file (disk)             |
+---------------------------------+

이 경로는 어떤 Kubernetes 클러스터에서도 기본적으로 동작합니다. 열려 있는 각 로그 뷰는 tail 중인 각 컨테이너마다 Dashboard Server와 kube-apiserver 사이에 하나의 장기 HTTP 연결을 유지합니다. 텍스트 필터링은 로그 스트림이 도착할 때 Kubetail Dashboard Server에서 적용됩니다.

Kubetail API (선택 사항)

Cluster API와 Cluster Agent가 배포되면 Kubetail Dashboard Server는 요청을 “Kubetail API” 스택을 통해 라우팅합니다. 예를 들어, 웹 대시보드에서 디스크의 파일까지 Kubetail API를 사용하는 요청 경로는 다음과 같습니다.

+---------------------------------+
| Kubetail Dashboard UI (Browser) |
+---------------------------------+
          │
          │ GraphQL over WebSocket
          ▼
+---------------------------------+
| Kubetail Dashboard Server       |
+---------------------------------+
          │
          │ GraphQL over WebSocket
          ▼
+---------------------------------+
| Cluster API                     |
+---------------------------------+
          │
          │ gRPC - one stream per log file
          ▼
+---------------------------------+
| Cluster Agent (one per node)    |
+---------------------------------+
          │
          │ file read + inotify watches
          ▼
+---------------------------------+
| Pod log file (disk)             |
+---------------------------------+

이 파이프라인에서는 로그 데이터가 kube-apiserver를 전혀 거치지 않으며, 텍스트 필터링은 전송 전에 각 Node에서 수행됩니다. kube-apiserver는 워크로드 메타데이터 요청과 권한 확인에만 사용됩니다.

구성 요소

Kubetail CLI

kubetail CLI는 데스크톱에서 Kubetail을 사용하는 기본 진입점입니다. 이 도구는 Go로 작성되었고, 웹 UI를 로컬에서 실행할 수 있도록 Dashboard를 함께 포함하고 있습니다. 주요 명령은 kubetail serve와 kubetail logs이며, 전자는 Dashboard Server를 시작하고 웹 UI를 열고, 후자는 로그를 터미널로 직접 스트리밍합니다. kubetail cluster 하위 명령은 내장 Helm 클라이언트를 사용해 선택적인 클러스터 측 리소스를 관리합니다.

전체 명령 및 플래그 목록은 CLI 레퍼런스를 참고하세요.

Kubetail Dashboard

Kubetail Dashboard는 함께 배포되는 두 부분으로 구성됩니다.

Dashboard UI — Vite로 빌드된 React 기반 싱글 페이지 애플리케이션으로, Dashboard Server가 정적 자산으로 제공합니다. 브라우저는 Dashboard Server와 GraphQL로만 통신합니다. queries와 mutations는 HTTP로, 실시간 로그 subscriptions은 지속적인 WebSocket 연결로 처리합니다. Kubernetes API 또는 클러스터 측 Kubetail 서비스로 향하는 모든 요청은 이 서버를 통해 프록시됩니다.
Dashboard Server — 정적 UI 자산을 제공하고, 인증과 세션 관리를 처리하며, 브라우저를 대신해 로그 데이터를 가져오는 Go 기반 HTTP 서버입니다. 두 가지 로그 백엔드를 지원합니다. Kubernetes API(기본값, 추가 설치 불필요)와 Kubetail API(클러스터 측 리소스가 설치된 경우 선택 사항)입니다.

설정 옵션은 Dashboard 레퍼런스를 참고하세요.

Kubetail Cluster API

Cluster API는 클러스터 내부에서 단일 Deployment로 실행되는 Go 기반 HTTP 서버입니다. Dashboard Server에 GraphQL API를 제공하고, 각 Node의 Cluster Agent에 대한 gRPC 디스패처 역할도 합니다.

로그 요청이 도착하면 Cluster API는 관련 Cluster Agent들에게 요청을 팬아웃하고, 스트리밍된 응답을 수집한 뒤 Dashboard Server로 하나의 스트림으로 합쳐 돌려줍니다. 로그 데이터는 전적으로 클러스터 내부 네트워크를 통해 흐르므로 kube-apiserver를 거치지 않습니다. Cluster API는 검색과 로그 파일 메타데이터(크기, 타임스탬프)처럼 Kubernetes API 모드에서는 사용할 수 없는 기능도 제공합니다.

설정 옵션은 Cluster API 레퍼런스를 참고하세요.

Kubetail Cluster Agent

Cluster Agent는 DaemonSet으로 실행되는 Rust 기반 gRPC 서버입니다 — 즉, Node당 하나의 Pod입니다. 이 컴포넌트는 Kubetail에서 유일하게 파일 시스템에 직접 접근하며, Node의 /var/log/containers에서 컨테이너 로그 파일을 읽습니다. 이 컴포넌트는:

운영체제 수준의 파일 시스템 알림(Linux에서는 inotify)을 사용해 Pod 로그 파일을 감시하므로, polling 없이도 새 줄을 감지합니다
새 로그 줄이 기록되는 즉시 gRPC를 통해 Cluster API로 스트리밍합니다
데이터가 Node를 떠나기 전에 ripgrep 기반 텍스트 필터링을 적용해, 일치하는 줄만 전송합니다
반복적인 API 호출 없이 요청을 인가할 수 있도록 Kubernetes SubjectAccessReview 결과를 캐시합니다

설정 옵션은 Cluster Agent 레퍼런스를 참고하세요.

통신 프로토콜

링크	프로토콜	비고
Browser ↔ Dashboard Server	GraphQL over WebSocket (graphql-ws) + HTTPS	하나의 연결에서 queries와 실시간 subscriptions 처리
Dashboard Server ↔ kube-apiserver	HTTP/HTTPS (client-go)	Kubernetes API 모드에서만 사용; 컨테이너당 하나의 스트림
Dashboard Server ↔ Cluster API	gRPC over HTTP/2	Cluster API 모드에서만 사용; TLS 선택 사항
Cluster API ↔ Cluster Agent	gRPC over HTTP/2	mTLS 선택 사항; grpc-dispatcher-go로 디스패치
Cluster Agent ↔ node disk	로컬 파일 I/O + inotify	네트워크 없음; `/var/log/containers/` 직접 읽기