아키텍처

Skuber+ Observability는 3-Tier 분산 아키텍처로 설계되어 멀티클러스터 환경에서 효율적으로 관측성 데이터를 수집하고 분석합니다.

개요

3-Tier 구성

Tier	구성 요소	역할
Tier 1	Agent Clusters (N개)	메트릭, 로그, 트레이스 수집
Tier 2	Host Cluster	데이터 수신, UI 제공, API 서비스
Tier 3	External ClickHouse	데이터 저장 및 쿼리 처리

ClickHouse를 별도 VM으로 분리하는 이유:

성능 격리: 대용량 쿼리가 Kubernetes 클러스터 리소스에 영향을 주지 않음
확장성: ClickHouse만 독립적으로 스케일 아웃 가능
운영 안정성: 클러스터 장애 시에도 데이터 보존
백업 용이성: VM 스냅샷으로 간편한 백업/복구

Host Cluster

Host Cluster는 중앙 수집 서버로, Agent Cluster에서 전송된 텔레메트리 데이터를 수신하고 External ClickHouse로 전달합니다.

주요 컴포넌트

컴포넌트	포트	역할
Nginx Proxy	:80 (내부), :8080 (외부)	요청 라우팅, Same-Origin 정책 해결
UI & Backend	:3000 (Frontend), :8080 (Backend)	메트릭/로그/트레이스 대시보드 UI 및 API
OTel Collector Gateway	:4317 (LoadBalancer)	OTLP 데이터 수신 및 ClickHouse로 전송
o11y-core API	:3001 (ClusterIP)	Service Map API, 과금 정보 집계

Nginx 라우팅

Nginx Proxy는 경로 기반으로 요청을 라우팅합니다:

경로 패턴	대상	용도
`/api/v1/servicemap/*`	o11y-core (:3001)	Service Map API
`/*` (그 외)	UI & Backend (:8080)	대시보드 UI 및 기본 API

External ClickHouse

ClickHouse는 Host Cluster 외부의 별도 VM에 배포됩니다. 환경에 따라 두 가지 구성을 선택할 수 있습니다.

옵션 1: 단일 VM (Standalone)

소규모 환경 또는 개발/테스트 환경에 적합합니다.

구성:

항목	값
VM 수	1대
권장 사양	8+ cores, 32GB+ RAM, SSD 500GB+
포트	9000 (TCP Native), 8123 (HTTP)
데이터 경로	`/var/lib/clickhouse`

장점:

간단한 설치 및 운영
비용 효율적

단점:

단일 장애점 (SPOF)
수평 확장 불가

옵션 2: 클러스터 구성 (High Availability)

프로덕션 환경에 권장됩니다.

구성:

구성 요소	VM 수	역할
ClickHouse Shard	2+	데이터 분산 저장
ClickHouse Replica	샤드당 2+	데이터 복제 (HA)
ClickHouse Keeper	3 (별도 VM 권장)	메타데이터 관리, 리더 선출

샤드 VM 권장 사양:

항목	값
CPU	16+ cores
RAM	64GB+
스토리지	NVMe SSD 1TB+
네트워크	10Gbps+

Keeper VM 권장 사양:

항목	값
CPU	4+ cores
RAM	8GB+
스토리지	SSD 50GB+
VM 수	3대 (별도 VM 권장)

장점:

고가용성 (노드 장애 시 자동 복구)
수평 확장 가능 (샤드 추가)
읽기 성능 향상 (복제본 분산 읽기)

단점:

복잡한 설치 및 운영
더 많은 리소스 필요

ClickHouse 데이터베이스 구조

데이터베이스	용도
`signoz_metrics`	메트릭 시계열 데이터
`signoz_logs`	로그 데이터
`signoz_traces`	분산 트레이스 데이터

주요 테이블 (signoz_traces):

테이블	용도
`signoz_index_v3`	트레이스 인덱스
`network_map_connections`	서비스 간 연결 정보 (Service Map)
`pod_workload_map_dict`	Pod IP → Workload 매핑
`cluster_service_dict`	Service IP → Service 매핑
`cluster_nodes_dict`	클러스터 → 노드 매핑

Agent Cluster

Agent Cluster는 모니터링 대상 Kubernetes 클러스터입니다. 각 Agent Cluster에 다음 컴포넌트가 설치됩니다:

컴포넌트	배포 형태	역할
OTel Collector	DaemonSet + Deployment	메트릭/로그/트레이스 수집 및 Host Cluster로 전송
APM Agent	DaemonSet	eBPF 기반 제로 코드 자동 계측, 네트워크 플로우 수집
kube-state-metrics	Deployment	Kubernetes 리소스 상태 메트릭 노출
OpenTelemetry Operator	Deployment	자동 계측 관리

OTel Collector 구성

DaemonSet (각 노드에서 실행):

hostmetrics: 시스템 메트릭 (CPU, 메모리, 디스크, 네트워크)
kubeletstats: 노드/파드/컨테이너 메트릭
filelog: 파드 로그 수집

Deployment (클러스터당 1개):

kube-state-metrics: Kubernetes 리소스 상태 수집
k8s_cluster: 노드 allocatable, conditions 수집
k8sEvents: Kubernetes 이벤트 수집

데이터 플로우

수집 경로

네트워크 요구사항

필수 포트

구분	소스	대상	포트	프로토콜	용도
Agent → Host	Agent Cluster	OTel Gateway	4317	gRPC	OTLP 데이터 전송
Host → ClickHouse	Host Cluster	ClickHouse VM	9000	TCP	데이터 저장 (Native)
Host → ClickHouse	Host Cluster	ClickHouse VM	8123	HTTP	데이터 쿼리
User → UI	사용자	Nginx Proxy	8080	HTTP	UI 접근

클러스터 구성 시 추가 포트

구분	소스	대상	포트	프로토콜	용도
CH 간 복제	ClickHouse	ClickHouse	9009	TCP	데이터 복제
Keeper 통신	ClickHouse	Keeper	9181	TCP	메타데이터 동기화
Keeper 간	Keeper	Keeper	9234	TCP	Raft 합의

보안 권장사항

Agent → Host 간 OTLP 통신에 TLS 적용 권장
ClickHouse 접근은 Host Cluster IP로 제한 (방화벽)
ClickHouse 기본 포트(9000, 8123) 변경 권장
LoadBalancer 앞에 방화벽 또는 인그레스 컨트롤러 구성

Skuber+ Client 연동

Skuber+ Client는 데스크톱 애플리케이션으로, Observability 플러그인을 통해 UI에 접근합니다:

배포 시나리오별 권장 구성

환경	Agent 클러스터	ClickHouse	Keeper
개발/테스트	1-2개	단일 VM	불필요
스테이징	2-5개	단일 VM 또는 2 Shard	3대 (선택)
프로덕션	5개 이상	2+ Shard, 복제 구성	3대 (별도 VM)

다음 단계

주요 기능 - 제공되는 기능 상세 확인
Host 클러스터 설치 - Host 클러스터 설치 가이드
Agent 클러스터 설치 - Agent 클러스터 설치 가이드
ClickHouse 설정 - ClickHouse 구성 상세