ClickStack을 Kubernetes에 올릴 때 MongoDB를 작게 보면 안 되는 이유

Mont Kim2026년 9월 15일#ClickStack#HyperDX#MongoDB#Kubernetes#Helm#ClickHouse

ClickStack의 큰 데이터는 ClickHouse에 들어갑니다.

그러면 MongoDB는 별로 중요하지 않은 작은 설정 저장소처럼 보입니다.

용량만 보면 절반은 맞습니다.

하지만 MongoDB를 잃으면 대시보드와 알림, 연결 설정을 함께 잃습니다.

이벤트는 남아 있는데 화면을 원래대로 쓰지 못하는 이상한 복구가 되는 거죠.

이 글은 2026-09-15의 ClickStack Helm v2.x 문서를 기준으로 합니다.

2026-07에 조사했던 v1.x 인라인 차트와 설정 경로가 다르므로 두 세대를 섞지 않습니다.

먼저 두 저장 경로를 나눈다

브라우저와 서버가 보내는 텔레메트리는 Collector를 거쳐 ClickHouse에 저장됩니다.

HyperDX UI에서 만드는 설정은 API를 거쳐 MongoDB에 저장됩니다.


브라우저·애플리케이션
        │ OTLP/HTTP·OTLP/gRPC
        ▼
OpenTelemetry Collector ───────► ClickHouse
                                  로그·트레이스·메트릭·세션

사용자 브라우저
        │ 대시보드·알림·source 설정
        ▼
HyperDX UI/API ────────────────► MongoDB
                                  앱 상태·메타데이터

RUM 세션 수가 열 배 늘었다고 MongoDB 디스크도 열 배 늘릴 이유는 없습니다.

반대로 ClickHouse에 이벤트가 남아 있다고 MongoDB 백업을 생략할 수도 없습니다.

결론 : ClickHouse와 MongoDB는 크기가 아니라 복구 역할로 나눠 봐야 합니다.

Helm v2.x는 두 단계로 설치한다

현재 공식 Helm 문서 는 v2.x를 프로덕션 권장 배포 방식으로 안내합니다.

먼저 operator와 CRD를 설치하고,

그다음 애플리케이션 차트가 operator 관리 리소스를 만듭니다.


helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo update
 
helm install clickstack-operators clickstack/clickstack-operators
kubectl get pods -l app.kubernetes.io/instance=clickstack-operators
 
helm install observability clickstack/clickstack
kubectl get pods -l app.kubernetes.io/name=clickstack

첫 번째 명령 묶음은 operator와 CRD를 준비합니다.

두 번째 차트는 ClickHouseCluster, KeeperCluster, MongoDBCommunity 같은 CR을 만듭니다.

ClickHouse 쪽 CRD는 Altinity operator의 ClickHouseInstallation과 다른 API입니다.

기존 Altinity CHI를 운영 중이라면 이름이 비슷하다는 이유로 values를 섞으면 안 됩니다.

v1.x 기록을 그대로 따라 하면 안 되는 이유

v2.x는 subchart 기반이고 v1.x는 inline-template 기반입니다.

공식 문서는 v1.x → v2.x를 breaking change로 분류하고 in-place helm upgrade를 지원하지 않는다고 명시합니다.

예전 글의 frontendUrl, resource 경로, secret 구조가 현재 차트와 같은지 먼저 확인해야 합니다.


helm show values clickstack/clickstack > values.yaml
helm search repo clickstack

이 출력이 지금 설치할 차트의 정본입니다.

블로그의 오래된 values보다 먼저 봐야 합니다.

MongoDB에는 무엇이 들어가나

HyperDX 소스에서 확인한 모델은 전부 앱 상태와 설정에 가깝습니다.

종류	예시	잃었을 때 영향
사용자·팀	`user`, `team`, `teamInvite`	로그인·협업 상태 손실
조회 설정	`source`, `connection`, `savedSearch`	ClickHouse 데이터 해석 경로 손실
화면	`dashboard`, `presetDashboardFilter`, `pinnedFilter`	운영 화면 재구성 필요
알림	`alert`, `alertHistory`, `webhook`	탐지 규칙·이력·통지 경로 손실
개인화	`favorite`	사용자 상태 손실

source도 이벤트 본문을 저장하지 않습니다.

어느 컬럼을 timestamp, body, service name으로 읽을지 같은 매핑 설정을 담습니다.

그래서 ClickHouse 테이블을 복원해도 source가 사라지면 UI가 데이터를 예전과 같은 의미로 읽지 못할 수 있습니다.

부하는 텔레메트리 양보다 설정 수에 가깝다

MongoDB의 주요 모델은 계속 쌓이는 원본 이벤트가 아닙니다.

사용자, 대시보드, 저장 검색, 알림 수에 따라 늘어납니다.

시간에 따라 지속해서 누적될 가능성이 큰 것은 alertHistory입니다.

여기에는 TTL 인덱스가 있어도 삭제는 정확히 만료 시각에 즉시 일어나지 않습니다.

MongoDB TTL 문서 는 백그라운드 작업으로 만료 문서를 정리한다고 설명합니다.

따라서 “30일 TTL이니 절대 30일치를 넘지 않는다”를 디스크 상한으로 쓰면 안 됩니다.

알림 수, 평가 주기, 발생 빈도까지 같이 봐야 합니다.

200Mi가 작아 보였던 함정

MongoDB에는 WiredTiger cache가 있습니다.

컨테이너 메모리 limit이 작다고 cache가 그 안에 예쁘게 자동 정렬될 거라 기대하기 어렵습니다.

조사한 MongoDB 문서의 기본 계산은 대략 다음 형태였습니다.


max(0.5 × (RAM - 1GB), 256MB)

최소 cache만 256MB라면 limits.memory: 200Mi는 시작부터 맞지 않습니다.

여기에 mongod 프로세스, 연결, 인덱스, MongoDB Kubernetes Operator agent 사이드카가 더해집니다.

따라서 작은 배포도 프로세스 하나만 보고 requests와 limits를 정하면 안 됩니다.

예시 시작점은 다음처럼 분리해서 생각할 수 있습니다.

항목	작은 시험 환경의 출발점	반드시 다시 잴 것
`mongod` CPU	250m 수준	알림·대시보드 사용 중 CPU
`mongod` 메모리	512Mi 이상	WiredTiger cache + working set
agent 여유	별도 확보	사이드카 RSS·재시작 여부
디스크	소형 persistent volume	백업 크기·alert history 증가

이 표는 권장 사양이 아닙니다.

OOM 없이 시작해 실제 사용량을 관찰하기 위한 출발선입니다.

`members: 1`은 ReplicaSet이라는 이름만 남는다

MongoDBCommunity 리소스의 타입이 ReplicaSet이라고 한 대 장애를 견디는 것은 아닙니다.

members: 1이면 그 한 대가 멈추는 동안 설정 읽기와 쓰기도 멈춥니다.

프로덕션에서는 세 멤버를 직접 운영할지,

MongoDB Atlas 같은 관리형에 넘길지 판단해야 합니다.


apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
  name: clickstack-mongodb
spec:
  members: 3
  type: ReplicaSet
  security:
    authentication:
      modes: ["SCRAM"]
  statefulSet:
    spec:
      template:
        spec:
          affinity:
            podAntiAffinity:
              requiredDuringSchedulingIgnoredDuringExecution:
                - labelSelector:
                    matchLabels:
                      app: clickstack-mongodb
                  topologyKey: topology.kubernetes.io/zone

이 예시는 구조를 보여주기 위한 뼈대입니다.

사용할 MCK 버전의 CRD 스키마와 차트가 생성하는 labels를 확인한 뒤 적용해야 합니다.

세 멤버도 같은 AZ와 같은 노드에 몰리면 기대한 장애 격리가 나오지 않습니다.

인증은 입구에서 끝나지 않는다

Compose 예제는 개발 편의를 위해 MongoDB를 단순하게 띄울 수 있습니다.

그 구성을 외부 네트워크에 그대로 노출하면 사용자와 팀, 대시보드, webhook 설정이 공격 대상이 됩니다.

Ingress 앞에 SSO proxy를 붙이는 것과 MongoDB 내부 인증은 다른 경계입니다.

최소한 다음을 따로 확인합니다.

MongoDB가 ClusterIP 또는 더 좁은 네트워크에만 노출되는가
SCRAM 자격증명이 예제 비밀번호에서 교체됐는가
HyperDX session secret과 API key가 별도 secret으로 관리되는가
NetworkPolicy가 HyperDX API와 운영 경로만 허용하는가
백업 계정이 필요한 권한만 가지는가

현재 Helm v2.x는 secret과 ingress/TLS 구성을 공식 문서에서 따로 안내합니다.

차트가 secret을 만든다는 사실이 외부 secret 저장소와 회전 정책까지 해결해주는 것은 아닙니다.

백업은 두 저장소를 한 세트로 본다

복원 목표는 “데이터베이스 프로세스가 뜬다”가 아닙니다.

사용자가 원래 대시보드를 열고,

같은 source로 로그를 검색하고,

알림이 다시 평가되는 상태까지 가야 합니다.

복원 대상	확인 방법
ClickHouse 텔레메트리	기준 시간대의 로그·트레이스·세션 조회
MongoDB 설정	사용자·source·dashboard·alert 개수 대조
연결 secret	UI에서 실제 ClickHouse query 성공
notification	격리된 테스트 alert 전송 성공

MCK 리소스를 사용한다고 백업이 자동으로 생기는 것도 아닙니다.

사용 버전이 제공하는 백업 기능과 mongodump 같은 별도 절차를 확인해야 합니다.

삭제할 때는 역순이다

공식 Helm 문서는 애플리케이션 차트를 먼저,

operator 차트를 나중에 제거하도록 안내합니다.


helm uninstall observability
helm uninstall clickstack-operators

현재 ClickStack Helm v2.x 문서는 operator가 만든 ClickHouse·MongoDB PVC가 helm uninstall에서 제거되지 않는다고 안내합니다.

다만 실제 잔존 여부는 사용하는 chart·operator 버전, CR 삭제 정책, StorageClass의 reclaim policy에 따라 재확인해야 합니다.

PVC 정리는 백업과 복원 확인 뒤에 별도 작업으로 다룹니다.

확인한 것과 남은 것

현재 문서에서 확인할 수 있는 것은 배포 구조와 저장 역할입니다.

v2.x는 두 단계 Helm 설치이며 ClickHouse·Keeper·MongoDB를 operator 관리 CR로 만듭니다.

MongoDB는 텔레메트리 본문 대신 UI를 다시 쓰게 해주는 상태를 저장합니다.

그래서 작게 시작할 수는 있어도 가볍게 잃어도 되는 컴포넌트는 아닙니다.

결론 : ClickStack 복구는 ClickHouse 데이터와 MongoDB 설정을 함께 되살렸을 때 끝납니다.

확인 시점: 2026-09-15, ClickStack Helm v2.x 문서 기준.