Helm 업그레이드 가이드

이 가이드는 인라인 템플릿 ClickStack Helm 차트(v1.x)에서 서브차트 기반 아키텍처(v2.x)로 마이그레이션하는 방법을 설명합니다. 이는 호환성이 깨지는 변경 사항으로, MongoDB 및 ClickHouse에 대해 수동으로 구성한 Kubernetes 리소스를 오퍼레이터가 관리하는 사용자 지정 리소스로 대체하고 공식 OpenTelemetry collector Helm 차트를 사용합니다.

중대한 변경 사항

v2.x 차트는 v1.x와 하위 호환되지 않습니다. 인플레이스 helm upgrade는 지원되지 않습니다. 제자리 업그레이드를 시도하기보다는 기존 배포와 함께 새로 설치한 후 데이터를 마이그레이션하는 것을 권장합니다.

사전 요구 사항

업그레이드하기 전에 데이터를 백업하십시오(MongoDB, ClickHouse PVCs)
현재 values.yaml에서 재정의한 설정을 검토하십시오 — 대부분의 키는 위치가 변경되었거나 이름이 바뀌었습니다

2단계 설치

v2.x 차트는 2단계로 설치합니다. 오퍼레이터(Operator, CRD를 등록함)는 메인 차트(CR을 생성함)보다 먼저 설치해야 합니다:

# Phase 1: Install operators and CRDs
helm install clickstack-operators clickstack/clickstack-operators

# Phase 2: Install ClickStack
helm install my-clickstack clickstack/clickstack

설치의 역순으로 제거하십시오:

helm uninstall my-clickstack
helm uninstall clickstack-operators

데이터 지속성

MongoDB 및 ClickHouse 오퍼레이터가 생성한 PersistentVolumeClaim은 helm uninstall을 실행해도 삭제되지 않습니다. 이는 의도된 동작이며, 실수로 데이터가 손실되는 것을 방지하기 위한 설계입니다. 제거 후 PVC를 정리하려면 다음 문서를 참조하십시오.

스토리지 클래스

global.storageClassName 및 global.keepPVC가 제거되었습니다. 이제 스토리지 클래스는 각 오퍼레이터의 CR 사양에서 직접 구성합니다:

mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - spec:
              storageClassName: "fast-ssd"

clickhouse:
  keeper:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"
  cluster:
    spec:
      dataVolumeClaimSpec:
        storageClassName: "fast-ssd"

변경 사항

구성 요소	이전 (v1.x)	이후 (v2.x)
MongoDB	인라인 배포 + 서비스 + PVC	`MongoDBCommunity` CR을 관리하는 MongoDB Kubernetes Operator (MCK)
ClickHouse	인라인 배포 + 서비스 + ConfigMaps + PVCs	`ClickHouseCluster` + `KeeperCluster` CR을 관리하는 ClickHouse Operator
OTel collector	인라인 배포 + 서비스 (`otel.*` 블록)	공식 OpenTelemetry collector Helm 차트 (`otel-collector:` 서브차트)
HyperDX 값	`hyperdx.*` 아래의 플랫 키와 최상위 `tasks:` 및 `appUrl`	`hyperdx.*` 아래에서 K8s 리소스 유형별로 재구성됨(아래 참조)
hdx-oss-v2	사용 중단된 레거시 차트	완전히 제거됨

HyperDX 값 재구성

이제 hyperdx: 블록은 Kubernetes 리소스 유형에 따라 구성됩니다:

hyperdx:
  ports:          # Shared port numbers (Deployment, Service, ConfigMap, Ingress)
    api: 8000
    app: 3000
    opamp: 4320

  frontendUrl: "http://localhost:3000"   # Replaces the removed appUrl

  config:         # → clickstack-config ConfigMap (non-sensitive env vars)
    APP_PORT: "3000"
    HYPERDX_LOG_LEVEL: "info"

  secrets:        # → clickstack-secret Secret (sensitive env vars)
    HYPERDX_API_KEY: "..."
    CLICKHOUSE_PASSWORD: "otelcollectorpass"
    CLICKHOUSE_APP_PASSWORD: "hyperdx"
    MONGODB_PASSWORD: "hyperdx"

  deployment:     # K8s Deployment spec (image, replicas, probes, etc.)
  service:        # K8s Service spec (type, annotations)
  ingress:        # K8s Ingress spec (host, tls, annotations)
  podDisruptionBudget:  # K8s PDB spec
  tasks:          # K8s CronJob specs (previously top-level tasks:)

주요 변경 사항

이전 (v1.x)	이후 (v2.x)
`appUrl`	제거되었습니다. `hyperdx.frontendUrl`을 사용하세요(기본값: `http://localhost:3000`)
`tasks.*` (최상위)	`hyperdx.tasks.*`
`mongodb.password`	`hyperdx.secrets.MONGODB_PASSWORD`
`clickhouse.config.users.appUserPassword`	`hyperdx.secrets.CLICKHOUSE_APP_PASSWORD`
`clickhouse.config.users.otelUserPassword`	`hyperdx.secrets.CLICKHOUSE_PASSWORD`
`otel.*` 환경 변수 재정의	`hyperdx.config.` (비민감 정보) 및 `hyperdx.secrets.` (민감 정보)

통합 ConfigMap 및 Secret

이제 모든 환경 변수는 envFrom을 통해 HyperDX 배포 및 OTel collector가 함께 사용하는, 고정된 이름의 두 리소스를 통해 전달됩니다:

clickstack-config ConfigMap — hyperdx.config로 채워집니다
clickstack-secret Secret — hyperdx.secrets로 채워집니다

이제 더 이상 OTel 전용 ConfigMap은 따로 없습니다. 두 워크로드는 모두 동일한 소스에서 값을 읽습니다.

MongoDB 마이그레이션

삭제된 값

다음 mongodb.* 값은 더 이상 존재하지 않습니다:

# REMOVED — do not use
mongodb:
  image: "..."
  port: 27017
  strategy: ...
  nodeSelector: {}
  tolerations: []
  livenessProbe: ...
  readinessProbe: ...
  persistence:
    enabled: true
    dataSize: 10Gi

새 값

MongoDB는 이제 MongoDBCommunity 사용자 지정 리소스를 통해 MCK operator에서 관리됩니다. CR 사양은 mongodb.spec 내용이 그대로 반영됩니다:

mongodb:
  enabled: true
  spec:
    members: 1
    type: ReplicaSet
    version: "5.0.32"
    security:
      authentication:
        modes: ["SCRAM"]
    users:
      - name: hyperdx
        db: hyperdx
        passwordSecretRef:
          name: '{{ include "clickstack.mongodb.fullname" . }}-password'
        roles:
          - name: dbOwner
            db: hyperdx
          - name: clusterMonitor
            db: admin
        scramCredentialsSecretName: '{{ include "clickstack.mongodb.fullname" . }}-scram'
    additionalMongodConfig:
      storage.wiredTiger.engineConfig.journalCompressor: zlib

MongoDB 비밀번호는 hyperdx.secrets.MONGODB_PASSWORD에 설정합니다(mongodb.password가 아님). 이 값은 password Secret과 mongoUri 템플릿에서 자동으로 참조됩니다.

영구 스토리지를 추가하려면 mongodb.spec 내부에 statefulSet 블록을 추가하십시오:

mongodb:
  spec:
    statefulSet:
      spec:
        volumeClaimTemplates:
          - metadata:
              name: data-volume
            spec:
              accessModes: ["ReadWriteOnce"]
              storageClassName: "your-storage-class"
              resources:
                requests:
                  storage: 10Gi

MCK operator 서브차트는 mongodb-operator: 아래에서 구성됩니다(mongodb-kubernetes:가 아님). 사용 가능한 모든 CRD 필드는 MCK 문서를 참조하십시오.

ClickHouse 마이그레이션

삭제된 값

다음 clickhouse.* 값은 더 이상 존재하지 않습니다:

# REMOVED — do not use
clickhouse:
  image: "..."
  terminationGracePeriodSeconds: 90
  resources: {}
  livenessProbe: ...
  readinessProbe: ...
  startupProbe: ...
  nodeSelector: {}
  tolerations: []
  service:
    type: ClusterIP
    annotations: {}
  persistence:
    enabled: true
    dataSize: 10Gi
    logSize: 5Gi
  config:
    clusterCidrs: [...]
    users:
      appUserPassword: "..."
      otelUserPassword: "..."
      otelUserName: "..."

새 값

이제 ClickHouse는 ClickHouseCluster 및 KeeperCluster 사용자 지정 리소스를 통해 ClickHouse Operator가 관리합니다. 두 CR 사양은 모두 값에 정의된 내용이 그대로 렌더링됩니다:

clickhouse:
  enabled: true
  port: 8123
  nativePort: 9000
  prometheus:
    enabled: true
    port: 9363
  keeper:
    spec:
      replicas: 1
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
  cluster:
    spec:
      replicas: 1
      shards: 1
      keeperClusterRef:
        name: '{{ include "clickstack.clickhouse.keeper" . }}'
      dataVolumeClaimSpec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 10Gi
      settings:
        extraUsersConfig:
          users:
            app:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_APP_PASSWORD }}'
            otelcollector:
              password: '{{ .Values.hyperdx.secrets.CLICKHOUSE_PASSWORD }}'
        extraConfig:
          max_connections: 4096
          keep_alive_timeout: 64
          max_concurrent_queries: 100

ClickHouse 사용자 인증 정보는 이제 clickhouse.config.users가 아니라 hyperdx.secrets에서 가져옵니다. 클러스터 사양에서는 템플릿 표현식으로 이를 참조합니다.

ClickHouse Operator 서브차트는 clickhouse-operator: 아래에서 구성합니다. Webhooks와 cert-manager는 기본적으로 비활성화되어 있습니다. 사용 가능한 모든 CRD 필드는 operator configuration guide를 참조하십시오.

OTel collector 마이그레이션

삭제된 값

otel: 블록 전체가 더 이상 존재하지 않습니다:

# REMOVED — do not use
otel:
  enabled: true
  image: ...
  replicas: 1
  resources: {}
  clickhouseEndpoint: ...
  clickhouseUser: ...
  clickhousePassword: ...
  clickhouseDatabase: "default"
  opampServerUrl: ...
  port: 13133
  nativePort: 24225
  grpcPort: 4317
  httpPort: 4318
  healthPort: 8888
  env: []
  customConfig: ...

새 값

이제 OTel collector는 공식 OpenTelemetry Collector Helm 차트의 otel-collector: 서브차트를 통해 배포됩니다. 상위 차트 otel: 래퍼는 없으므로 서브차트를 직접 구성하십시오.

환경 변수(ClickHouse 엔드포인트, OpAMP URL 등)는 통합된 clickstack-config ConfigMap과 clickstack-secret Secret을 통해 공유됩니다. 서브차트의 extraEnvsFrom은 미리 연결되어 있습니다:

otel-collector:
  enabled: true
  mode: deployment
  image:
    repository: docker.clickhouse.com/clickhouse/clickstack-otel-collector
    tag: ""
  extraEnvsFrom:
    - configMapRef:
        name: clickstack-config
    - secretRef:
        name: clickstack-secret
  ports:
    otlp:
      enabled: true
      containerPort: 4317
      servicePort: 4317
    otlp-http:
      enabled: true
      containerPort: 4318
      servicePort: 4318

리소스를 설정하려면(이전에는 otel.resources를 사용):

otel-collector:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"

레플리카를 설정하려면 (이전에는 otel.replicas):

otel-collector:
  replicaCount: 3

nodeSelector/tolerations를 설정하려면(이전 otel.nodeSelector/otel.tolerations):

otel-collector:
  nodeSelector:
    node-role: monitoring
  tolerations:
    - key: monitoring
      operator: Equal
      value: otel
      effect: NoSchedule

OpenTelemetry Collector Helm 차트에서 사용 가능한 모든 서브차트 값을 확인하십시오.

변경되지 않는 값

다음 섹션은 이 마이그레이션의 영향을 받지 않습니다:

global.* (imageRegistry, imagePullSecrets)

신규 설치 vs. 인플레이스 업그레이드

신규 설치의 경우 별도의 특별한 단계가 필요하지 않습니다. 기본값만으로 바로 사용할 수 있습니다.

기존 릴리스에 대해 인플레이스 업그레이드를 수행하는 경우, 다음 사항에 유의하십시오.

오퍼레이터(MCK, ClickHouse Operator)는 네임스페이스에 새로운 배포로 설치됩니다
기존 MongoDB 배포와 ClickHouse 배포는 Helm에 의해 삭제됩니다(더 이상 차트의 템플릿에 포함되지 않음)
오퍼레이터는 MongoDB와 ClickHouse를 관리하기 위해 새로운 StatefulSet을 생성합니다
이전 차트의 PVC는 오퍼레이터가 관리하는 StatefulSet에서 자동으로 재사용되지 않습니다

인플레이스 업그레이드보다는 기존 배포와 나란히 신규 설치를 수행한 후 데이터를 마이그레이션하는 방식을 권장합니다.

다음 단계

기본 Helm 가이드 - v2.x를 사용한 기본 설치
구성 가이드 - API 키, 시크릿 및 인그레스
추가 매니페스트 - 사용자 지정 Kubernetes 객체
ClickStack Helm 차트 저장소 - 차트 소스 코드 및 값 참조

사전 요구 사항​

2단계 설치​

데이터 지속성​

스토리지 클래스​

변경 사항​

HyperDX 값 재구성​

주요 변경 사항​

통합 ConfigMap 및 Secret​

MongoDB 마이그레이션​

삭제된 값​

새 값​

ClickHouse 마이그레이션​

삭제된 값​

새 값​

OTel collector 마이그레이션​

삭제된 값​

새 값​

변경되지 않는 값​

신규 설치 vs. 인플레이스 업그레이드​

다음 단계​

사전 요구 사항

2단계 설치

데이터 지속성

스토리지 클래스

변경 사항

HyperDX 값 재구성

주요 변경 사항

통합 ConfigMap 및 Secret

MongoDB 마이그레이션

삭제된 값

새 값

ClickHouse 마이그레이션

삭제된 값

새 값

OTel collector 마이그레이션

삭제된 값

새 값

변경되지 않는 값

신규 설치 vs. 인플레이스 업그레이드

다음 단계