버전 호환성·업그레이드 — 스택 전 구성요소 매트릭스와 EBS 롤백

operator 운영이 CH 서버 롤링 업그레이드 런북(shard 내 1 replica씩·shard 간 병렬·혼합버전 창)·operator 자체 minor 단계별 업그레이드·CRD 삭제 절대금지·안전장치 3층·Keeper(CHK) 업그레이드를 이미 깊게 다뤘습니다. operator 토폴로지·다운타임은 롤링 중 다운타임·EBS reattach 물리 역학을 다뤘습니다. 이 페이지는 그 일반 메커니즘을 반복하지 않습니다. HyperDX 스택 전체를 한 매트릭스로 묶었을 때 무엇이 무엇과 붙는가, 그리고 EBS-first에서 업그레이드를 어떻게 되돌리는가만 봅니다. 새로 깊게 파는 것은 (1) 6개 구성요소 상호 버전 호환 매트릭스, (2) CH compatibility 서버 설정, (3) 다운그레이드 비지원과 그 실질 롤백 경로, (4) EBS 스냅샷 기반 롤백입니다. 일반 롤링 런북은 전부 위 두 페이지로 위임합니다.

1. 버전 호환성 매트릭스 — 스택 전 구성요소

우리는 ClickStack 표준 차트를 그대로 쓰지 않고 clickhouse.enabled: false(HyperDX Only)로 CH/Keeper를 Altinity CHI/CHK로 분리 운영합니다. 그래서 차트가 배포하는 기본 이미지와 우리가 실제로 핀하는 이미지는 별개입니다. 아래 매트릭스가 그 경계를 정리합니다.

1.1 마스터 매트릭스 (2026-07 확인)

표 4열로는 근거 주석까지 담을 폭이 안 나오므로 항목별 불릿으로 풉니다. 각 항목은 A ↔ B — 요구/권장 (근거) 순서입니다.

• ① ClickStack/HyperDX ↔ ClickHouse — 최소 24.8 LTS 이상(24.8·25.x 지원). self-host에서 외부 CH 참조 시 24.8+ 필수 (✓⁽ClickStack docs⁾).
• ② ClickStack 차트 기본 CH 이미지 — clickhouse/clickhouse-server:25.7-alpine(차트가 실제 배포하는 태그) (✓⁽values.yaml⁾ — 최소요구(24.8)와 차트기본(25.7)은 다른 숫자).
• ③ HyperDX app ↔ CH 스키마/기능 — LowCardinality·Map·bloom filter 2차 인덱스·TTL ... ttl_only_drop_parts 등 MergeTree 표준 기능만 씁니다 → 하한이 24.8 LTS로 낮게 유지됨(신규 JSON 타입 강제 아님) (✓/≈).
• ④ MongoDB ↔ HyperDX — 5.0.32(차트 기본), ReplicaSet(차트 기본 members:1). 메타데이터 전용이라 버전 민감도가 낮음 (✓⁽values.yaml⁾ — 부하 프로파일은 /rum/07-hyperdx-mongodb/).
• ⑤ OTel Collector ↔ ClickStack — docker.clickhouse.com/clickstack-otel-collector:2.29.0, mode: deployment. ClickStack 배포판(표준 upstream 아님) (✓⁽values.yaml⁾ — persistent queue 확장 포함 여부는 /hyperdx/05-keeper/ §옵션A로 재확인).
• ⑥ HyperDX 이미지 ↔ 차트 — docker.hyperdx.io/hyperdx/hyperdx, 태그 미지정 시 차트 appVersion 추종. 명시 오버라이드하면 appVersion과 어긋날 수 있음 (✓⁽values.yaml⁾).
• ⑦ Altinity operator 0.27.1 ↔ CH / K8s — operator 0.27.1 → CH 21.11+, K8s 1.25+. 더 오래된 CH는 operator 0.23.7 이하 필요 (✓⁽Artifact Hub / release notes⁾ — 우리 CH(24.8~25.x)는 여유롭게 범위 안).
• ⑧ Altinity operator ↔ CRD apiVersion — CHI=clickhouse.altinity.com/v1, CHK=clickhouse-keeper.altinity.com/v1. operator가 CRD를 소유(Helm이 기존 CRD 미수정) (✓⁽CRD 원문·Helm README⁾).
• ⑨ operator 0.27.0+ 기본값 ↔ Keeper 버전 — operator 0.27.0+가 async_replication/use_xid_64를 기본 활성화 → Keeper 25.3+ 필요 (✓⁽release notes⁾ — 매트릭스 함정, §1.4).

1.2 매트릭스에서 나오는 실전 결정 3가지

1. CH 이미지 = 24.8 LTS 핀 vs 25.x 추종. ClickStack 최소요구는 24.8 LTS, 차트 기본은 25.7입니다. self-host(Altinity CHI)에서는 podTemplate 이미지 태그를 우리가 직접 정합니다 — 관측성 워크로드는 안정성이 우선이므로 LTS(24.8) 또는 검증된 최근 안정판을 핀하고 25.x 최신 추종은 하지 않는 게 기본 ≈.
2. Keeper 이미지 = CH 이미지와 정렬. CHK clickhouse/clickhouse-keeper 태그를 CH 서버와 같은 메이저.마이너로 맞춥니다(둘 다 24.8). ClickStack 차트는 Keeper를 별도 이미지 없이 CH 서버 이미지로 돌리지만 우리는 Altinity CHK로 분리하므로 태그를 명시 정렬합니다 ✓/≈.
3. 컴포넌트별 업그레이드는 독립 관심사. CH·operator·Keeper·HyperDX·OTel·MongoDB는 각각 별도 케이던스로 올립니다. 한 reconcile에 여러 변화를 몰면 원인을 추적할 수 없고 이미지+설정 동시변경 crash(#1926)와 같은 결의 위험이 생깁니다 ≈⁽corpus 원칙 연장⁾.

1.3 정정 — “최소 24.8"과 “차트 기본 25.7"은 모순이 아니다 ✓

1.4 매트릭스 함정 — operator 0.27+ 기본값 ↔ Keeper 25.3+ ?

⑨는 배포 전 반드시 실측해야 합니다. operator 0.27.0+는 async_replication과 use_xid_64를 기본 활성화합니다. 이 기능들은 Keeper 25.3+를 요구합니다 ✓⁽release notes⁾. 우리가 CH/Keeper를 24.8 LTS로 핀하면(§1.2-2) operator가 이 기본값을 켠 상태에서 Keeper 24.8과 충돌할 수 있습니다.

• 검증 항목: 24.8 CH + 24.8 Keeper + operator 0.27.x 조합에서 operator가 이 두 기본값을 (a) 그대로 켜서 오류를 내는지, (b) Keeper 버전을 감지해 자동 무효화하는지 ?.
• 핀 vs 기본값: 필요하면 CHK/CHI 설정에서 async_replication을 명시적으로 끄거나 Keeper만 25.3+로 올리는 결정을 스테이징에서 확정합니다. “operator 최신 = 무조건 안전"이 아닙니다. operator 기본값이 우리 핀 버전보다 최신 Keeper를 전제할 수 있다는 게 이 함정입니다.

1.5 문서에 있지만 아직 못 쓰는 것 ?

버전 게이트에 걸리는 건 “우리 버전에 없는 기능"만이 아닙니다. 문서에는 실려 있는데 OSS 어느 출시본에서도 아직 집을 수 없는 것이 따로 있습니다. 이쪽이 더 자주 사람을 헛돌게 합니다. 지금 확인된 항목을 미확정으로 세워 둡니다.

• Packed storage (min_level_for_full_part_storage, 25.10) — 기본값이 0 = Full storage라 켜지 않으면 동작이 바뀌지 않습니다. 가용성 진술은 문서마다 다릅니다 — 공식 표는 Availability를 “Open source and Cloud"로 적는데 별도 조회에서는 “Cloud 전용"이라는 상충 진술이 나옵니다 → OSS 실제 동작 미확정 ?. 문서가 드는 효과(insert당 PUT 31.3 → 2.22)가 사실이면 S3 요청 비용 구조가 바뀌므로 켤지 말지는 지금 정하지 않고 실측 대상으로만 남깁니다.
• system.parts.part_storage_type은 OSS 26.9부터 노출 예정이고 2026-08 기준 최신 출시는 26.7입니다. 지금은 어떤 출시본에도 없어서 part가 어느 저장 형태로 쓰였는지를 이 컬럼으로 확인할 수 없습니다 ?. 위 Packed storage 검증이 여기서 막힙니다.

두 항목은 §1.4의 함정과 성격이 다릅니다. §1.4는 우리가 핀한 버전이 operator 기본값보다 낮아서 생기는 충돌이라 스테이징 실측으로 닫힙니다. 여기는 출시본에 코드가 아직 없어서 생기는 공백이라 버전이 올라올 때까지 닫히지 않습니다. 후자를 배포 전 실측 항목에 넣으면 닫히지 않는 항목이 체크리스트에 남으므로 재검토 트리거(26.9 출시)로만 걸어 둡니다 ≈.

2. compatibility 서버 설정 — 업그레이드 안전 노브

2.1 무엇인가 ✓

compatibility 설정은 지정한 이전 버전의 기본 설정값(default settings)을 그대로 쓰게 합니다. 값은 버전 문자열('24.8' 등), 빈 값이 기본입니다(비활성).

• 명시적으로 바꾸지 않은 설정만 영향받습니다 — 사용자가 이미 override한 설정은 존중됩니다. 바이너리는 신버전으로 올렸지만 동작 기본값은 옛 버전에 고정하는 노브입니다.
• 업그레이드로 CH 바이너리가 올라가도 compatibility='24.8'이면 24.8 시절 기본값으로 동작합니다. 신규 기본값 변화가 겉으로 드러나지 않게 부르는 회귀(silent regression), 곧 쿼리 결과·성능·리소스 사용 변화를 막습니다.

2.2 어디에 넣나 ✓

Altinity 운영이면 평문 XML 직접 주입을 피하고 CHI의 configuration.profiles로 넣습니다 — operator가 이를 users.xml 프로파일로 렌더합니다 ≈⁽profiles→users.xml 렌더는 corpus 사실의 귀결. 렌더된 users.xml은 도입 시 확인⁾.

apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
  name: hyperdx-ch
  namespace: clickhouse
spec:
  configuration:
    profiles:
      # 업그레이드 직후 이 프로파일을 쓰는 모든 세션이 24.8 기본값으로 동작한다.
      # 스테이징에서 새 기본값을 하나씩 검증한 뒤 이 핀을 제거/상향한다.
      default/compatibility: "24.8"

2.3 언제 쓰나 ≈

1. 메이저 버전 업그레이드 직후: 새 기본값이 쿼리 결과·성능·리소스 사용을 바꾸는 것을 유예합니다. compatibility를 옛 버전으로 핀한 채 올리고 스테이징에서 새 기본값을 하나씩 검증한 뒤 핀을 제거하거나 상향합니다.
2. 혼합버전 창 중: 롤링 도중 노드마다 버전이 다를 때 동작 편차를 줄이는 보조 수단입니다(혼합버전 창 자체의 규칙은 operator 운영).

3. 다운그레이드 정책 — CH는 함부로 못 내린다

3.1 핵심 명제 ✓

ClickHouse는 온디스크 데이터 포맷이 바뀌지 않은 경우, 곧 “새 버전 포맷으로 파트를 다시 쓰는 작업을 하지 않은 상태"에서만 이전 버전으로 롤백(다운그레이드)할 수 있습니다.

바이너리를 내리는 것 자체는 쉽지만 디스크의 파트를 옛 버전이 못 읽으면 그 노드는 startup에서 죽거나 파트가 detached/broken-on-start_*로 떨어집니다.

3.2 다운그레이드가 불가능해지는 트리거 (2026 확인) — 차단 버전의 단일 정본

아래 표가 이 스택에서 다운그레이드 차단 버전의 단일 정본입니다. 각 행은 포맷을 바꾼 도입 버전과 그 뒤로 불가능해지는 롤백 하한을 함께 적습니다 — 이 둘은 같은 숫자가 아니고 한 숫자로 눌러 요약하면 “25.8이 도입 버전인지 하한인지"가 뒤섞입니다. 다른 장과 운영 트랙은 이 숫자를 재기재하지 않고 이 표를 가리킵니다.

¹ getMarksTypeFromFilesystem 함수에서 fatal 발생.

3.3 롤백 창을 여는 규칙 & 실질 롤백 경로 ✓

• 업그레이드 관찰 창(24~48h) 동안 롤백 창을 열어두려면: (a) OPTIMIZE ... FINAL 금지, (b) 새 컬럼 타입/신규 기능 사용 금지, (c) 새 시스템 테이블/컬럼을 MV에서 참조 금지. 이 규칙을 지키면 온디스크 포맷이 그대로라 바이너리만 되돌려도 롤백됩니다.
• 그 창을 넘겼거나 포맷이 바뀌면 실질 롤백은 복구뿐입니다:
  • 사전 백업: 업그레이드 직전 BACKUP DATABASE ... TO ... 또는 clickhouse-backup create_remote(FREEZE PARTITION 래핑 + S3 업로드).
  • 스키마 스냅샷: SELECT database, name, create_table_query FROM system.tables를 사전에 저장.
  • 복구: 서버 stop → clickhouse-backup restore_remote <pre_upgrade> → 패키지 다운그레이드 → start.

-- 업그레이드 직전 스키마 스냅샷 (롤백 시 대조용)
SELECT database, name, create_table_query
FROM system.tables
WHERE database NOT IN ('system','INFORMATION_SCHEMA','information_schema')
FORMAT TSVRaw;

# 업그레이드 직전 백업 (clickhouse-backup: FREEZE + S3 업로드)
clickhouse-backup create_remote pre-upgrade-$(date +%Y%m%d)
# 실패 시 복구: 서버 stop → restore → 패키지 다운그레이드 → start
clickhouse-backup restore_remote pre-upgrade-YYYYMMDD

4. EBS/블록 온리 특유 업그레이드 안전

CH 다운그레이드는 포맷 때문에 막힐 수 있습니다(§3). EBS-first에서는 업그레이드 직전 데이터 볼륨의 EBS 스냅샷을 롤백 지점으로 삼는 게 가장 확실합니다. EBS-first라서 추가로 얻는 롤백 축입니다.

4.1 EBS 스냅샷 → 롤백 경로 ✓⁽AWS⁾

• EBS 스냅샷은 시점(point-in-time) 증분 백업입니다(첫 스냅샷만 full, 이후 델타). “위험한 배포 직전 스냅샷 = 깨끗한 롤백 지점"입니다.
• 정합성: 스냅샷은 비동기입니다(생성 즉시 시작, pending 동안 S3로 전송). AWS는 완전 정합 스냅샷을 원하면 스냅샷 전 볼륨 쓰기를 멈추라고 권고합니다. CH는 롤링 중 해당 replica를 어차피 순차 정지하므로 그 replica가 stop된 상태에서 스냅샷을 뜨면 정합성이 좋습니다 ≈.
• 복원: 스냅샷에서 새 gp3 볼륨을 만들고(create-volume --snapshot-id <id> --volume-type gp3) PV/PVC를 교체해 그 시점 상태로 되돌립니다.
• replica 병렬성 활용: RF2/RF3라 한 replica씩 업그레이드하므로 “한 replica 스냅샷 → 업그레이드 → 실패 시 그 replica만 스냅샷 복원 → 나머지 healthy replica에서 델타 catch-up“이 성립합니다 ≈.

# 실패 시: 업그레이드 전 스냅샷에서 gp3 볼륨 복원
aws ec2 create-volume \
  --snapshot-id snap-0abc... \
  --volume-type gp3 \
  --availability-zone ap-northeast-2a   # 원 볼륨과 같은 AZ (EBS는 AZ-bound)
# → 새 volume-id를 PV의 volumeHandle로 교체하고 PVC를 재바인딩

EBS는 AZ-bound라 복원 볼륨은 반드시 원 볼륨과 같은 AZ에 만듭니다 — AZ 종속·reattach 전제는 operator 토폴로지·다운타임이 기준 문서입니다.

4.2 allowVolumeExpansion ↔ 업그레이드 순서 상호작용 ≈

• gp3 온라인 확장(allowVolumeExpansion: true)과 CH 버전 업그레이드는 별도 reconcile로 분리합니다 — 이미지+설정 동시변경 crash(#1926)와 같은 결의 위험입니다. 볼륨 확장 중 롤링을 겹치면 STS 업데이트 경합이 생길 수 있습니다.
• 확장 경로의 데이터손실 주의(issue #1385)와 온라인 확장 상세는 블록 온리 튜닝.

4.3 PVC Retain으로 실수 삭제 방어 ✓/≈

• reclaimPolicy: Retain(operator·StorageClass 이중)이면 CHI/STS 재생성이나 helm uninstall에도 EBS PVC가 잔존합니다. 업그레이드 중 실수로 리소스를 지워도 데이터 볼륨은 살아납니다. operator/Helm이 만든 PVC는 애초에 helm uninstall로 안 지워집니다. reclaimPolicy 미준수 버그(#1619)와 이중 방어는 hot 스토리지·EBS.

4.4 블록 온리(무 S3)의 업그레이드 단순성 ≈

S3 cold 티어가 없으면 업그레이드 중 티어 간 정합(로컬 파트 메타 ↔ S3 오브젝트) 우려가 아예 없습니다. storage_policy가 내장 default 하나뿐이라 disk 설정·IRSA·endpoint 이슈가 업그레이드 표면에서 빠집니다 — 블록 온리는 업그레이드 롤백 추론이 “EBS 스냅샷 하나"로 단순해집니다. 전량 EBS 사이징·operator 볼륨 튜닝은 블록 온리 튜닝, S3 티어링 시의 정합 고려는 S3 cold 티어링.

5. ClickStack/HyperDX 업그레이드 경로

5.1 ClickStack Helm v1 → v2 = 파괴적 변경 ✓⁽UPGRADE.md⁾

• 2단계 설치: helm install clickstack-operators ... → helm install my-clickstack .... uninstall은 역순입니다.
• in-place 업그레이드 금지 권고: 문서는 “기존 MongoDB/ClickHouse Deployment가 Helm에 의해 삭제된다"며 기존 배포 옆에 fresh install 후 데이터 마이그레이션을 권합니다(in-place 아님).
• PVC 보호: MongoDB/ClickHouse operator가 만든 PVC는 helm uninstall로 삭제되지 않으므로 수동 정리가 필요합니다. 사전에 PVC를 백업합니다.
• values 재구성: hyperdx.*가 resource-type 구조로 이동합니다(config→ConfigMap, secrets→Secret, frontendUrl→appUrl, tasks가 hyperdx.tasks). mongodb.image/port/persistence.*·clickhouse.image/persistence.*·otel: 블록은 제거됐으므로 오버라이드를 다시 써야 합니다.

5.2 우리 배포에 주는 함의 ≈

우리는 이미 clickhouse.enabled: false(HyperDX Only)로 CH/Keeper를 Altinity CHI/CHK로 분리해 운영합니다(스택 토폴로지). 그래서 v2의 “내장 CH를 공식 operator CR로 관리"라는 파괴적 변경의 상당 부분이 우리에겐 적용되지 않습니다 — 업그레이드 표면이 다음처럼 좁아집니다:

¹ MergeTree 표준 기능만 쓰므로 CH 24.8+ 유지 시 앱 업그레이드가 CH 하한을 새로 요구하는 경우는 드뭅니다 ≈.

HyperDX Only 구조가 ClickStack v1→v2의 가장 파괴적인 부분(내장 CH 삭제·재설치)을 비켜갑니다 — 우리 ClickStack 차트 업그레이드는 사실상 HyperDX + OTel + 외부 CH 참조 설정 표면에 그칩니다.

6. 일반 업그레이드 런북 (relref 위임)

아래는 이미 corpus에 기준 문서가 있으므로 여기서 재서술하지 않습니다. 요지 한 줄 + 링크로만 둡니다.

• CH 서버 롤링: shard 내 1 replica씩·shard 간 병렬·혼합버전 창 ~1년/2 LTS·중간 LTS 징검다리·podTemplate 이미지 태그 변경으로 트리거 → operator 운영.
• operator 자체: minor 단계별(0.26→0.27)·CRD 삭제 절대금지·이미지+설정 분리 reconcile·안전장치 3층(STS recreate 정책·aborted reconcile 자동 재개·pre/post SQL 훅) → operator 운영.
• Keeper(CHK): 0.26→0.27 무마이그레이션·0.23.x 수동 PV·4LW 라이브니스 전환 → operator 운영.
• 롤링 다운타임·EBS reattach 물리 역학·reconcile.statefulSet.update.timeout → operator 토폴로지·다운타임.

우리 케이스에서는

• 버전 핀 정책을 배포 문서에 표로 고정합니다: CH 24.8 LTS(또는 검증된 안정판) / Keeper=CH 태그 정렬(둘 다 24.8) / operator 0.27.1(CH 21.11+·K8s 1.25+) / MongoDB 5.0.32 / OTel 2.29.0 / HyperDX=appVersion. 최신 추종은 하지 않고 ClickStack 최소요구(24.8)를 항상 상회하도록만 관리합니다. operator 0.27+의 async_replication 기본값 ↔ Keeper 25.3+ 상호작용(§1.4)은 24.8 핀 시 스테이징 실측 항목으로 명시합니다.
• 업그레이드 3규칙: ① 이미지·설정·볼륨확장은 각각 별도 reconcile(동시변경 crash 회피), ② 업그레이드 직전 EBS 스냅샷 + clickhouse-backup 이중 안전, ③ 관찰 24~48h 동안 OPTIMIZE FINAL·신규 타입 사용 금지로 롤백 창 유지. RF2/RF3라 replica 단위로 “스냅샷 → 업그레이드 → 실패 시 그 replica만 스냅샷 복원 → 나머지에서 델타 catch-up"이 성립합니다.
• 다운그레이드는 없다고 가정합니다: 포맷이 한 번 바뀌면 그 아래로는 스냅샷/백업 복구가 유일한 롤백이고 어느 버전 쌍이 막히는지는 §3.2 표로만 판정합니다 — 도입 버전과 롤백 하한을 한 숫자로 외우는 순간 틀립니다. compatibility 설정은 “동작 회귀 방지"용이지 롤백이 아니다 — 이것을 팀 룰로 명문화합니다.
• 문서에 있지만 못 쓰는 것은 실측 항목이 아니라 재검토 트리거로 겁니다: Packed storage와 system.parts.part_storage_type(§1.5)은 스테이징에서 닫을 수 없으므로 배포 전 체크리스트에 넣지 않고 26.9 출시 시점에 다시 봅니다.
• 블록 온리라 롤백 추론이 단순합니다: S3 티어 정합 우려가 없어 “EBS 스냅샷 하나"로 시점 복원이 닫힙니다. 전량 EBS 사이징·볼륨 튜닝은 블록 온리 튜닝으로 이어집니다.
• 시점 기준 2026-08(§1 매트릭스는 2026-07 확인, §1.5는 2026-08 조회).