Helm - ClickHouse Documentation

차트 버전 2.x이 페이지는 v2.x 서브차트 기반 Helm 차트를 설명합니다. 아직 v1.x 인라인 템플릿 차트를 사용 중이라면 v1.x Helm 가이드를 참조하십시오. 마이그레이션 절차는 업그레이드 가이드를 참조하십시오.

ClickStack용 Helm 차트는 여기에서 확인할 수 있으며, 프로덕션 배포에 권장되는 방법입니다. v2.x 차트는 2단계 설치 방식을 사용합니다. 먼저 clickstack-operators 차트를 통해 오퍼레이터와 CRD를 설치한 다음, 메인 clickstack 차트를 설치하여 ClickHouse, MongoDB, OpenTelemetry Collector에 대한 오퍼레이터 관리 사용자 지정 리소스를 생성합니다. 기본적으로 Helm 차트는 다음을 포함한 모든 핵심 구성 요소를 프로비저닝합니다.

ClickHouse — ClickHouseCluster 및 KeeperCluster 사용자 지정 리소스를 통해 ClickHouse Operator가 관리
HyperDX — 관측성 UI 및 API
OpenTelemetry (OTel) collector — 공식 OpenTelemetry Collector Helm chart를 서브차트로 사용해 배포
MongoDB — MongoDBCommunity 사용자 지정 리소스를 통해 MongoDB Kubernetes Operator (MCK)가 관리

하지만 기존 ClickHouse 배포와 통합하도록 쉽게 사용자 지정할 수 있습니다. 예를 들어 ClickHouse Cloud에서 호스팅되는 배포를 연동할 수 있습니다. 이 차트는 다음과 같은 Kubernetes의 표준 모범 사례를 지원합니다.

values.yaml을 통한 환경별 구성
리소스 제한 및 파드 수준 스케일링
TLS 및 인그레스 구성
시크릿 관리 및 인증 설정
차트와 함께 임의의 Kubernetes 객체(NetworkPolicy, HPA, ALB Ingress 등)를 배포하기 위한 추가 매니페스트

적합한 용도

개념 검증
프로덕션 환경

배포 절차

사전 요구 사항

Helm v3+
Kubernetes 클러스터(v1.20+ 권장)
kubectl이 클러스터와 통신할 수 있도록 구성되어 있음

ClickStack Helm 리포지토리 추가

ClickStack Helm 리포지토리를 추가하세요:

helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts
helm repo update

오퍼레이터 설치

먼저 오퍼레이터 차트를 설치합니다. 그러면 메인 차트에 필요한 CRD가 등록됩니다:

helm install clickstack-operators clickstack/clickstack-operators

계속 진행하기 전에 오퍼레이터 파드가 준비될 때까지 기다리십시오:

kubectl get pods -l app.kubernetes.io/instance=clickstack-operators

ClickStack 설치

오퍼레이터가 실행 중이면 메인 차트를 설치합니다:

helm install my-clickstack clickstack/clickstack

설치 확인

설치 상태를 확인하세요:

kubectl get pods -l "app.kubernetes.io/name=clickstack"

모든 파드가 준비되면 다음 단계로 진행하십시오.

포트 포워딩

포트 포워딩을 사용하면 HyperDX에 접근하고 설정할 수 있습니다. 프로덕션 환경에 배포할 때는 적절한 네트워크 액세스, TLS 종료, 확장성을 보장할 수 있도록 인그레스 또는 로드 밸런서를 통해 서비스를 노출해야 합니다. 포트 포워딩은 장기 운영이나 고가용성 환경용이 아니라 로컬 개발 또는 일회성 관리 작업에 가장 적합합니다.

kubectl port-forward \
  pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \
  8080:3000

프로덕션 인그레스 설정프로덕션 환경에 배포할 때는 포트 포워딩 대신 TLS를 사용하는 인그레스를 구성하세요. 자세한 설정 방법은 인그레스 구성 가이드를 참조하세요.

UI로 이동

HyperDX UI에 액세스하려면 http://localhost:8080에 접속하세요.요구 사항을 충족하는 사용자 이름과 비밀번호를 입력해 사용자를 생성하세요.Create를 클릭하면 Helm 차트로 배포된 ClickHouse 인스턴스에 대한 데이터 소스가 생성됩니다.

기본 연결 재정의통합된 ClickHouse 인스턴스의 기본 연결을 재정의할 수 있습니다. 자세한 내용은 “ClickHouse Cloud 사용”을 참조하세요.

값 사용자 지정(선택 사항)

--set 플래그를 사용해 설정을 사용자 지정할 수 있습니다. 예시는 다음과 같습니다:

helm install my-clickstack clickstack/clickstack --set key=value

또는 values.yaml을 수정하십시오. 기본값을 확인하려면 다음을 실행하십시오:

helm show values clickstack/clickstack > values.yaml

예시 설정:

hyperdx:
  frontendUrl: "https://hyperdx.example.com"

  deployment:
    replicas: 2
    resources:
      limits:
        cpu: "2"
        memory: 4Gi
      requests:
        cpu: 500m
        memory: 1Gi

  ingress:
    enabled: true
    host: hyperdx.example.com
    tls:
      enabled: true
      tlsSecretName: "hyperdx-tls"

helm install my-clickstack clickstack/clickstack -f values.yaml

시크릿 사용(선택 사항)

v2.x chart는 values의 hyperdx.secrets를 바탕으로 채워지는 통합 시크릿(clickstack-secret)을 사용합니다. ClickHouse 비밀번호, MongoDB 비밀번호, HyperDX API Key를 포함한 모든 민감한 환경 변수는 이 단일 시크릿을 통해 관리됩니다.시크릿 값을 재정의하려면:

hyperdx:
  secrets:
    HYPERDX_API_KEY: "your-api-key"
    CLICKHOUSE_PASSWORD: "your-clickhouse-password"
    CLICKHOUSE_APP_PASSWORD: "your-app-password"
    MONGODB_PASSWORD: "your-mongodb-password"

외부 시크릿 관리(예: secrets operator 사용)를 사용할 경우, 기존 Kubernetes 시크릿을 참조할 수 있습니다:

hyperdx:
  useExistingConfigSecret: true
  existingConfigSecret: "my-external-secret"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

API Key 관리여러 가지 구성 방법과 파드 재시작 절차를 포함한 API Key 설정에 대한 자세한 내용은 API Key 설정 가이드를 참조하세요.

ClickHouse Cloud 사용

ClickHouse Cloud를 사용하는 경우 기본 제공 ClickHouse 인스턴스를 비활성화하고 Cloud 자격 증명을 입력하십시오:

# values-clickhouse-cloud.yaml
clickhouse:
  enabled: false

hyperdx:
  secrets:
    CLICKHOUSE_PASSWORD: "your-cloud-password"
    CLICKHOUSE_APP_PASSWORD: "your-cloud-password"

  useExistingConfigSecret: true
  existingConfigSecret: "clickhouse-cloud-config"
  existingConfigConnectionsKey: "connections.json"
  existingConfigSourcesKey: "sources.json"

연결 시크릿을 별도로 생성하세요:

cat <<EOF > connections.json
[
  {
    "name": "ClickHouse Cloud",
    "host": "https://your-cloud-instance.clickhouse.cloud",
    "port": 8443,
    "username": "default",
    "password": "your-cloud-password"
  }
]
EOF

kubectl create secret generic clickhouse-cloud-config \
  --from-file=connections.json=connections.json

rm connections.json

helm install my-clickstack clickstack/clickstack -f values-clickhouse-cloud.yaml

고급 외부 구성시크릿 기반 구성, 외부 OTel collector 사용, 또는 최소 구성으로 프로덕션에 배포하는 경우 배포 옵션 가이드를 참조하십시오.

프로덕션 참고 사항

기본적으로 이 차트는 ClickHouse, MongoDB 및 OTel collector를 설치합니다. 프로덕션 환경에서는 ClickHouse와 OTel collector를 별도로 관리하는 것이 좋습니다. ClickHouse와 OTel collector를 비활성화하려면:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

프로덕션 모범 사례고가용성 구성, 리소스 관리, 인그레스/TLS 설정, 클라우드별 구성(GKE, EKS, AKS)을 포함한 프로덕션 배포에 대해서는 다음 문서를 참조하십시오.

구성 가이드 - 인그레스, TLS, 시크릿 관리
Cloud 배포 - Cloud별 설정 및 프로덕션 체크리스트

작업 구성

기본적으로 차트 설정에는 알림을 트리거해야 하는지 확인하는 CronJob 작업이 1개 포함되어 있습니다. v2.x에서는 작업 구성이 hyperdx.tasks 아래로 이동했습니다.

매개변수	설명	기본값
`hyperdx.tasks.enabled`	클러스터에서 cron 작업을 활성화 또는 비활성화합니다. 기본적으로는 HyperDX 이미지가 프로세스 내에서 cron 작업을 실행합니다. 클러스터에서 별도의 cron 작업을 사용하려면 `true`로 변경하십시오.	`false`
`hyperdx.tasks.checkAlerts.schedule`	check-alerts 작업의 cron 스케줄	`/1 * * *`
`hyperdx.tasks.checkAlerts.resources`	check-alerts 작업의 리소스 요청 및 제한	`values.yaml` 참조

차트 업그레이드

더 최신 버전으로 업그레이드하려면:

helm upgrade my-clickstack clickstack/clickstack -f values.yaml

사용 가능한 Helm 차트 버전을 확인하려면:

helm search repo clickstack

v1.x에서 업그레이드v1.x inline-template 차트에서 업그레이드하는 경우, 마이그레이션 지침은 업그레이드 가이드를 참조하십시오. 이는 호환성이 깨지는 변경 사항이므로, 현재 위치에서 helm upgrade를 수행하는 방식은 지원되지 않습니다.

ClickStack 제거

다음 역순으로 제거하십시오:

helm uninstall my-clickstack            # 앱 + CR 먼저 제거
helm uninstall clickstack-operators     # 연산자 + CRD 제거

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

MongoDB Kubernetes Operator 문서

문제 해결

로그 확인하기

kubectl logs -l app.kubernetes.io/name=clickstack

설치 실패 디버깅

helm install my-clickstack clickstack/clickstack --debug --dry-run

배포 확인

kubectl get pods -l app.kubernetes.io/name=clickstack

추가 문제 해결 리소스인그레스 관련 이슈, TLS 문제 또는 클라우드 배포 문제 해결은 다음 문서를 참조하십시오:

Ingress 문제 해결 - 정적 에셋 제공, 경로 재작성, 브라우저 문제
Cloud 배포 - GKE OpAMP 문제 및 클라우드별 문제

스키마 선택: Map vs JSON

ClickStack는 기본적으로 속성을 Map(LowCardinality(String), String) 컬럼에 저장합니다. 이는 관측성 워크로드에 권장되는 스키마입니다. 버킷 기반 맵 직렬화와 맵 키 및 값에 대한 텍스트 인덱스를 함께 사용하면, 동적 JSON 서브컬럼에서 발생하는 키별 수집 오버헤드 없이 필요한 항목만 선택적으로 조회할 수 있습니다. JSON 타입 스키마는 속성 키 집합이 작고 안정적인 워크로드에서 평가할 수 있도록 베타로 제공됩니다. 기본값으로는 권장되지 않습니다. 전체 비교 내용과 JSON 지원을 활성화하는 데 필요한 환경 변수는 Map vs JSON type에서 확인하십시오.

배포 가이드

배포 옵션 - 외부 ClickHouse, OTel collector 및 최소 배포
구성 가이드 - API Key, 시크릿 및 인그레스 설정
Cloud 배포 - GKE, EKS, AKS 구성 및 프로덕션 환경 모범 사례
업그레이드 가이드 - v1.x에서 v2.x로 마이그레이션
추가 매니페스트 - 차트와 함께 사용자 지정 Kubernetes 객체 배포

v1.x 문서

Helm (v1.x) - v1.x 배포 가이드
구성 (v1.x) - v1.x 구성
배포 옵션 (v1.x) - v1.x 배포 옵션
Cloud 배포 (v1.x) - v1.x Cloud 구성

추가 자료

ClickStack 시작하기 가이드 - ClickStack 소개
ClickStack Helm 차트 리포지토리 - 차트 소스 코드 및 values 참고
Kubernetes 문서 - Kubernetes 참고
Helm 문서 - Helm 참고

​적합한 용도

​배포 절차

​ClickHouse Cloud 사용

​프로덕션 참고 사항

​작업 구성

​차트 업그레이드

​ClickStack 제거

​문제 해결

​로그 확인하기

​설치 실패 디버깅

​배포 확인

​스키마 선택: Map vs JSON

​관련 문서

​배포 가이드

​v1.x 문서

​추가 자료

적합한 용도

배포 절차

ClickHouse Cloud 사용

프로덕션 참고 사항

작업 구성

차트 업그레이드

ClickStack 제거

문제 해결

로그 확인하기

설치 실패 디버깅

배포 확인

스키마 선택: Map vs JSON

관련 문서

배포 가이드

v1.x 문서

추가 자료