Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm

View as MarkdownEdit this pageReport an issueSet up docs MCP

ClickStack용 Helm 차트는 여기에서 확인할 수 있으며, 프로덕션 배포에 권장되는 방법입니다.

v2.x 차트는 2단계 설치 방식을 사용합니다. 먼저 clickstack-operators 차트를 통해 오퍼레이터와 CRD를 설치한 다음, 메인 clickstack 차트를 설치하여 ClickHouse, MongoDB, OpenTelemetry Collector에 대한 오퍼레이터 관리 사용자 지정 리소스를 생성합니다.

기본적으로 Helm 차트는 다음을 포함한 모든 핵심 구성 요소를 프로비저닝합니다.

하지만 기존 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

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

--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"

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

프로덕션 참고 사항

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

ClickHouse와 OTel collector를 비활성화하려면:

clickhouse:
  enabled: false

otel-collector:
  enabled: false

작업 구성

기본적으로 차트 설정에는 알림을 트리거해야 하는지 확인하는 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

ClickStack 제거

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

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

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

문제 해결

로그 확인하기

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

스키마 선택: Map vs JSON

ClickStack는 기본적으로 속성을 Map(LowCardinality(String), String) 컬럼에 저장합니다. 이는 관측성 워크로드에 권장되는 스키마입니다. 버킷 기반 맵 직렬화와 맵 키 및 값에 대한 텍스트 인덱스를 함께 사용하면, 동적 JSON 서브컬럼에서 발생하는 키별 수집 오버헤드 없이 필요한 항목만 선택적으로 조회할 수 있습니다.

JSON 타입 스키마는 속성 키 집합이 작고 안정적인 워크로드에서 평가할 수 있도록 베타로 제공됩니다. 기본값으로는 권장되지 않습니다. 전체 비교 내용과 JSON 지원을 활성화하는 데 필요한 환경 변수는 Map vs JSON type에서 확인하십시오.

배포 가이드

v1.x 문서

추가 자료

Navigation