솔루션 아키텍처 — 4컴포넌트 조립과 HyperDX Only 분기

이 페이지는 운영 로드맵 1부(솔루션 아키텍처)를 구체화한 것이다. 4컴포넌트의 정체성·배포 6모드·‘HyperDX Only’ 개념 자체의 기준 문서는 HyperDX / ClickStack 심층 분석이고, 포트·의존 방향·MongoDB 최소 배포 CR 전문은 스택 토폴로지가 기준 문서다. 이 페이지는 그 위에서 “왜 표준 경로를 안 쓰고 무엇을 어떻게 조립하나” — 즉 조립 순서와 HyperDX Only 분기의 실무 판단만 압축해서 다룬다. 세부 매니페스트·다운타임 시나리오는 재서술하지 않고 relref로 위임한다.

1. 왜 표준 2-Helm 경로를 그대로 안 쓰나 — operator 2종 공존 회피

표준 경로의 첫 차트 clickstack-operators는 MongoDB Kubernetes Operator(MCK) 와 ClickHouse Inc.의 신규 공식 operator(ClickHouseCluster/KeeperCluster CRD)를 함께 설치한다 ✓. 이 공식 operator는 Altinity operator(ClickHouseInstallation/CHI)가 아니다 ✓. 우리는 이미 범용분석 CH를 Altinity operator로 운영 중이므로, 표준 경로를 그대로 따르면 같은 클러스터에 CH operator가 2종(공식 + Altinity) 공존하게 된다.

# clickstack 차트 values — HyperDX Only 분기의 핵심 스위치
clickhouse:
  enabled: false      # ★ 공식 operator를 쓰지 않음. CH/Keeper는 Altinity CHI/CHK로 외부 운영
otel-collector:
  enabled: true        # 게이트웨이는 차트로 유지

enabled: false로 두면 HyperDX api는 CLICKHOUSE_*·MONGO_URI 시크릿으로 외부 CH/Mongo를 참조만 하고, ClickHouse/Keeper 자체는 Altinity CHI/CHK가 별도로 운영한다 ✓. operator 선택 자체의 근거(7년+ 트랙레코드·범용분석 일원화)는 ClickHouse operator 선택이 기준 문서다.

2. 컴포넌트별 배치 — 4논리 컴포넌트, 5개 실행 단위

“4컴포넌트"는 논리 단위이고 실제 배치 단위는 5개다 — HyperDX(app·api·OpAMP를 한 Deployment에서 함께 기동), Collector, CHI, CHK, MongoDB. HyperDX는 2프로세스지만 배포·스케일 노브는 하나이고, CH가 CHI/CHK 2 스테이트풀로 갈린다.

배치 판단의 요지:

• OTel Collector는 daemonset이 아니라 게이트웨이 deployment만으로 성립한다. RUM-only 워크로드는 브라우저 SDK가 게이트웨이 Service로 직접 OTLP를 쏘는 구조라 노드 로그를 긁는 daemonset agent가 필수가 아니다 ≈. 서버측 앱 트레이스/로그를 내재화하는 시점에 daemonset을 추가하면 된다.
• CH/Keeper 토폴로지는 0.7TB/월 규모의 트리거 기반 결정이다 — 1 shard×RF2(2 AZ)는 이 스케일에서 shard가 부채이기 때문이고, Keeper 3노드는 정족수 1장애 허용의 최소치다 ≈.
• MongoDB members:1은 차트 기본값이지 prod 권고가 아니다. MCK 기본은 단일 멤버(PoC용)이고, prod는 members:3(≈1.2 vCPU/3Gi, 값싼 보험)으로 수동 승급한다 ✓(기본) / ≈(prod 권고).

3. 데이터 흐름 — RUM 인제스트 경로에 MongoDB는 없다

• 브라우저 RUM SDK는 HyperDX api가 아니라 OTel Collector(4318)로 직접 텔레메트리를 보낸다 ✓. 세션 리플레이(rrweb)는 ClickHouse hyperdx_sessions 테이블로 적재되며, “MongoDB에 세션이 저장된다"는 통념은 이미 기각됐다 ✓.
• 즉 RUM 인제스트 경로에 MongoDB는 전혀 없다. MongoDB는 사용자가 UI에서 대시보드/알럿/소스를 만들 때만 쓰인다 — 이것이 MongoDB를 아주 작게 돌려도 되는 구조적 근거다.
• 이 구조적 사실의 실무 함의는 MongoDB 다운은 관측(인제스트) 정지가 아니라 설정·알럿 평가·UI 정지라는 것이다. 컴포넌트별 blast radius·무손실 2트랙 종합은 가용성으로 위임한다.
• 쓰기 경로(Collector → CH)와 읽기 경로(api → CH)는 분리돼 있지만 같은 CH 클러스터를 공유한다. 대시보드 쿼리 폭주가 인제스트를 밀어낼 수 있다는 캐파 이슈는 아키텍처 밖 주제라 스택 토폴로지·규모 산정으로 넘긴다.

4. OpAMP(:4320) — Collector 설정 원격 관리

HyperDX api가 OpAMP 서버로 동작해 Collector 파이프라인 설정을 원격 관리한다 ✓. Collector는 OPAMP_SERVER_URL 환경변수로 api의 /v1/opamp 엔드포인트에 붙어 설정을 받는다. 이 경로가 있기 때문에 §3 다이어그램에서 api↔Collector 사이에 별도 화살표(OpAMP)가 존재한다 — 데이터가 흐르는 방향(Collector→CH)과 제어가 흐르는 방향(api→Collector)이 반대라는 점이 이 아키텍처의 특징이다.

커스텀 Collector config는 CUSTOM_OTELCOL_CONFIG_FILE로 지정하면 베이스 config에 병합된다 ✓. 단 이 병합은 신규 receiver/processor 추가에 한정되고 기존 컴포넌트를 오버라이드하지는 못한다 ✓. 실무 함의: 베이스 파이프라인 자체(예: 기본 batch/memory_limiter 파라미터)를 바꾸려면 OpAMP 병합 경로가 아니라 Helm values 레벨에서 손을 대야 한다.

5. 컴포넌트별 Helm values 핵심 스위치

HyperDX Only 조립을 실제 values로 옮기면 아래 세 축으로 정리된다 — CH/Keeper 끄기, Collector 게이트웨이 사이징, HyperDX가 외부 CH/Mongo를 참조하는 시크릿 배선.

# clickstack 차트 — HyperDX Only 조립 values 요지
clickhouse:
  enabled: false                 # §1 — Altinity CHI/CHK로 외부 운영

otel-collector:
  enabled: true
  replicaCount: 2                 # 게이트웨이 HA (§2)
  # exporter 연결문자열에 async_insert=1(+wait_for_async_insert=1) 권장 (저볼륨)
  # file_storage extension으로 퍼시스턴트 큐 구성 — 상세: 스택 토폴로지 §5

hyperdx:
  api:
    envFrom:
      - secretRef: { name: clickhouse-creds }   # CLICKHOUSE_HOST/USER/PASSWORD 등
      - secretRef: { name: mongo-creds }        # MONGO_URI

CH/Keeper 자체(CHI/CHK CR)는 이 차트 values가 아니라 별도 매니페스트로 관리한다 — 필드·다운타임 시나리오는 operator 토폴로지·다운타임·Altinity 운영이 기준 문서다. MongoDB MongoDBCommunity CR(members:3·SCRAM·WiredTiger 캐시 고정 전문)은 스택 토폴로지 §6.3으로 위임한다. 정확한 values 키 경로(예: otel-collector.replicaCount vs 중첩된 deployment.replicas)는 차트 버전마다 달라질 수 있어 배포 시 helm show values clickstack/clickstack로 재확인한다 ?.

우리 케이스에서는

조립: 표준 2-차트를 그대로 쓰지 않는다. clickhouse.enabled: false로 ClickHouse/Keeper를 차트 밖 Altinity CHI/CHK로 분리해 범용분석 CH와 운영 체계를 일원화하고, HyperDX app/api·OTel Collector·MongoDB만 차트/operator 경로에 남긴다. 이 분기 하나가 뒤따르는 모든 매니페스트·다운타임 판단의 전제다.

배치: OTel Collector는 daemonset 없이 게이트웨이 deployment ×2 + file_storage 큐, HyperDX app/api는 무상태 2+ replica, CH는 1 shard×RF2(2 AZ), Keeper는 3노드(3 AZ), MongoDB는 members:3(prod) 또는 Atlas로 시작한다. RUM 인제스트 경로에 MongoDB가 없다는 구조적 사실이 MongoDB를 최소 규모로 유지해도 되는 근거이자, MongoDB 장애를 “관측 정지"가 아니라 “설정·알럿·UI 정지"로 격리해 판단하게 한다. 시점 기준 2026-07.