Skip to Content
BlogClickStack을 Kubernetes에 올리기 — operator부터 고르기
ClickHouse / HyperDX

ClickStack을 Kubernetes에 올리기 — operator부터 고르기

#ClickHouse#ClickStack#Kubernetes#Operator

ClickHouse 컨테이너 하나를 띄우는 일은 어렵지 않습니다.

어려운 일은 사본과 샤드가 늘어난 뒤부터 시작합니다.

새 사본에 스키마를 만들고, 분산 테이블의 주소를 갱신하고, 같은 샤드의 사본을 동시에 재시작하지 않도록 순서를 지켜야 합니다.

그래서 operator를 쓸지 묻기 전에 먼저 어떤 변경을 반복하게 될지를 적는 편이 낫습니다.

이 글은 2026년 9월 공개 문서와 릴리스 상태를 기준으로 ClickStack의 ClickHouse를 Kubernetes에서 운영할 때의 선택지를 정리합니다.

StatefulSet으로 시작해도 되는 범위

단일 노드 검증 환경이라면 StatefulSet 직접 관리도 충분합니다.

백업에서 새 클러스터를 만드는 절차가 있고 변경 빈도가 낮다면, operator의 CRD와 렌더링 규칙을 먼저 익힐 이유가 적습니다.

하지만 다음 작업이 등장하면 관리 대상이 달라집니다.

반복 작업직접 관리할 때 필요한 일
replica 추가스키마 생성, Keeper 경로와 remote_servers 정합성 확인
shard 추가분산 테이블 갱신, 과거 데이터 재배치 판단
이미지 변경같은 shard의 replica를 한 대씩 교체
설정 변경ConfigMap 반영 순서와 재시작 범위 통제
볼륨 확장PVC와 StatefulSet 템플릿의 소유권 처리
장애 복구잃은 replica 등록을 정리하고 새 replica를 재수화

한 shard에 replica를 두 벌 두는 순간부터 operator의 이득이 눈에 보이기 시작합니다.

선언에서 replicasCount를 바꾸면 끝난다는 뜻은 아닙니다.

operator가 리소스를 만드는 순서와 실패 뒤 재개 방법을 이해해야 하지만, 적어도 반복되는 변경 절차를 한곳에 모을 수 있습니다.

선택지는 네 가지다

선택지맞는 범위가장 큰 부담
순수 StatefulSet단일 노드 PoC, 재구축 가능한 작은 환경토폴로지와 롤링을 직접 구현
Altinity clickhouse-operator여러 replica와 shard를 운영하는 셀프호스팅CHI/CHK와 설정 렌더링 학습
ClickHouse 공식 operatorAPI 변화와 운영 범위를 검증할 수 있는 환경조사 시점의 API 안정성 확인 필요
범용 DB operator이미 해당 플랫폼을 표준으로 쓰는 조직ClickHouse 고유 기능의 지원 깊이 확인

Altinity operator는 ClickHouseInstallation(CHI)과 ClickHouseKeeperInstallation(CHK)을 중심으로 오랫동안 운영 기능을 쌓아왔습니다.

공식 ClickHouse operator는 ClickHouseCluster와 KeeperCluster라는 다른 CRD를 사용합니다.

둘은 API 그룹이 다르므로 Kubernetes 안에서 기술적으로 공존할 수 있습니다.

문제는 충돌보다 운영 표면입니다.

롤링, 볼륨, 백업, 장애 복구를 두 방식으로 익혀야 하고 알림과 런북도 둘로 갈립니다.

공식 operator의 현재 API와 지원 범위는 공식 저장소 를 배포 시점에 다시 확인해야 합니다.

Altinity 쪽도 버전별 동작이 바뀌므로 릴리스 목록 과 업그레이드 노트를 함께 봐야 합니다.

ClickStack이 설치하는 것부터 확인한다

ClickStack 차트가 ClickHouse와 operator까지 관리하게 둘지, 외부 ClickHouse에 연결할지는 첫 배포 전에 정해야 합니다.

내장 구성을 쓰면 설치는 간단하지만 그 차트가 선택한 operator와 토폴로지를 따라가게 됩니다.

이미 Altinity CHI를 운영한다면 내장 ClickHouse를 끄고 외부 클러스터를 연결하는 방식이 운영 모델을 하나로 유지하기 쉽습니다.

반대로 ClickStack 전용의 작은 클러스터를 빠르게 검증하려는 목적이라면 차트 기본 구성이 더 짧은 경로일 수 있습니다.

결정할 때는 다음 네 질문이면 충분합니다.

  1. ClickHouse를 ClickStack과 별개로 업그레이드해야 하는가?
  2. 같은 클러스터에서 다른 분석 워크로드도 운영하는가?
  3. 볼륨과 replica 복구를 어느 operator의 런북으로 통일할 것인가?
  4. 차트 세대가 바뀔 때 기존 PVC와 CR의 소유권은 누구에게 남는가?

operator가 자동화해도 남는 일

operator는 스토리지의 물리적 성질을 바꾸지 못합니다.

로컬 PV는 여전히 노드에 묶이고, EBS는 여전히 가용 영역에 묶입니다.

노드가 사라진 로컬 NVMe replica는 다른 사본에서 데이터를 다시 받아야 합니다.

EBS replica는 같은 가용 영역에서 기존 볼륨을 다시 붙일 수 있지만, detach와 attach, 파트 로딩, 복제 지연 해소가 끝날 때까지 서비스 가능한 사본 수가 줄어듭니다.

PDB도 모든 장애를 막아주지 않습니다.

PDB는 Eviction API를 사용하는 자발적 중단을 제한할 뿐, 노드 급사와 모든 operator의 직접 삭제 경로를 직렬화하지 않습니다.

따라서 operator 선택과 별개로 다음 배치를 명시해야 합니다.

apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
  name: observability
spec:
  defaults:
    templates:
      podTemplate: clickhouse
  configuration:
    clusters:
      - name: observability
        pdbManaged: "yes"
        pdbMaxUnavailable: 1
        layout:
          shardsCount: 1
          replicasCount: 3
  templates:
    podTemplates:
      - name: clickhouse
        podDistribution:
          - type: ShardAntiAffinity
            topologyKey: kubernetes.io/hostname
          - type: ShardAntiAffinity
            topologyKey: topology.kubernetes.io/zone
        spec:
          containers:
            - name: clickhouse
              image: clickhouse/clickhouse-server:<pinned-version>

필드 이름과 지원 여부는 사용하는 operator 버전에 맞춰 검증해야 합니다.

예제의 목적은 replicasCount 하나가 HA를 완성하지 않는다는 점을 보여주는 데 있습니다.

로컬 디스크를 쓰면 복구가 배포 기능이 된다

로컬 NVMe의 노드가 사라지면 StatefulSet 파드만 다시 만드는 것으로 끝나지 않습니다.

새 노드와 새 PV를 마련하고, 사라진 replica의 Keeper 등록을 정리한 뒤, 살아 있는 replica에서 파트를 다시 받아야 합니다.

Altinity issue #1859 에는 StatefulSet과 PVC를 정리하고 CHI의 taskID를 바꿔 reconcile을 다시 일으키는 절차가 논의돼 있습니다.

이 절차를 배포판 전체의 영구 보장으로 읽으면 안 됩니다.

적용 버전, reclaim policy, 남은 replica의 상태를 확인한 뒤 비어 있는 검증 클러스터에서 먼저 재현해야 합니다.

특히 실사용 CHI를 삭제 명령의 시험 대상으로 삼으면 안 됩니다.

성숙도는 기능 목록보다 실패 이력으로 본다

operator를 비교할 때 CRD 개수나 별 개수만 세면 실제 운영 차이가 잘 보이지 않습니다.

다음 질문이 더 유용합니다.

  • 롤링 도중 replica를 분산 쿼리에서 어떻게 다루는가?
  • 실패한 reconcile을 어디서 다시 시작하는가?
  • 활성 replica를 제거하지 않는 안전장치가 있는가?
  • PVC 확장을 재시작 없이 처리할 수 있는가?
  • Keeper를 별도 CR로 관리하고 정족수를 지키는가?
  • 이미지와 설정이 함께 바뀔 때 적용 순서는 무엇인가?

이 질문에 릴리스 노트와 이슈로 답할 수 있어야 합니다.

v1alpha1 같은 API 단계도 신호지만, 실제로 필요한 기능이 구현됐는지와 업그레이드 호환성은 따로 확인해야 합니다.

배포 전에 적어둘 경계

운영 구성을 문서 한 장으로 고정해두면 operator 교체나 차트 업그레이드 때 판단이 쉬워집니다.

ClickHouse 소유자        : ClickStack chart / 별도 operator
CRD와 operator 버전      : 실제 배포 버전
ClickHouse / Keeper 버전 : 실제 이미지 digest
스토리지                 : local PV / EBS / object storage
shard × replica          : 예) 1 × 3
백업 복원 단위           : table / replica / cluster
노드 소실 성공 조건      : 재수화 완료와 lag 0
operator 교체 방식       : in-place / 새 클러스터 복원

이 표가 비어 있다면 아직 operator를 고른 것이 아니라 설치 명령만 고른 상태입니다.

결론

단일 노드 검증은 StatefulSet으로도 충분합니다.

replica를 두 벌 이상 유지하고 롤링, 볼륨 확장, 복구를 반복한다면 operator가 관리 비용을 줄입니다.

ClickStack에서는 차트가 선택한 operator를 그대로 받을지, 외부 ClickHouse로 운영 모델을 통일할지를 먼저 결정해야 합니다.

그리고 어떤 선택을 하든 스토리지 복구, Keeper 정족수, 배치 제약은 operator 밖의 문제로 남습니다.

기능과 릴리스 상태는 2026-09-15 스냅샷입니다.

ClickStack 셀프호스팅 구조 잡기 — 작게 시작해서 복구 가능한 구성으로rollbackWindow는 왜 그 안전장치를 깨는가