Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Helm (v1.x)

View as MarkdownEdit this pageReport an issueSet up docs MCP

ClickStack용 helm 차트는 여기에서 확인할 수 있으며, 운영 환경 배포에 권장되는 방식입니다.

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

  • ClickHouse
  • HyperDX
  • OpenTelemetry (OTel) collector
  • MongoDB (애플리케이션 상태를 영구적으로 저장하기 위해)

하지만 기존 ClickHouse 배포와 통합하도록 손쉽게 사용자 지정할 수 있습니다. 예를 들어 ClickHouse Cloud에서 호스팅되는 배포와 연동할 수 있습니다.

이 차트는 다음과 같은 Kubernetes 모범 사례를 지원합니다.

  • values.yaml을 통한 환경별 구성
  • 리소스 제한 및 파드 수준 스케일링
  • TLS 및 인그레스 구성
  • 시크릿 관리 및 인증 설정

적합한 사용 사례

  • 개념 검증
  • 프로덕션 환경

배포 단계


사전 요구 사항

  • Helm v3+
  • Kubernetes 클러스터(v1.20+ 권장)
  • 클러스터와 상호 작용하도록 구성된 kubectl

ClickStack Helm 리포지토리 추가

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

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

ClickStack 설치

기본 values를 사용해 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

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

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

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

또는 values.yaml을 편집하세요. 기본값을 가져오려면 다음과 같이 하십시오:

helm show values clickstack/clickstack > values.yaml

구성 예시:

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
helm install my-clickstack clickstack/clickstack -f values.yaml

시크릿 사용(선택 사항)

API Key 또는 데이터베이스 자격 증명과 같은 민감한 데이터를 처리하려면 Kubernetes 시크릿을 사용하세요. HyperDX Helm 차트에는 수정한 뒤 클러스터에 적용할 수 있는 기본 시크릿 파일이 포함되어 있습니다.

미리 구성된 시크릿 사용

Helm 차트에는 charts/clickstack/templates/secrets.yaml에 있는 기본 시크릿 템플릿이 포함되어 있습니다. 이 파일은 시크릿 관리를 위한 기본 구조를 제공합니다.

시크릿을 수동으로 적용해야 하는 경우, 제공된 secrets.yaml 템플릿을 수정한 뒤 적용하세요:

apiVersion: v1
kind: Secret
metadata:
  name: hyperdx-secret
  annotations:
    "helm.sh/resource-policy": keep
type: Opaque
data:
  API_KEY: <base64-encoded-api-key>

클러스터에 시크릿을 적용하세요:

kubectl apply -f secrets.yaml

사용자 지정 시크릿 생성

원하면 사용자 지정 Kubernetes 시크릿을 수동으로 직접 생성할 수 있습니다.

kubectl create secret generic hyperdx-secret \
  --from-literal=API_KEY=my-secret-api-key

시크릿 참조

values.yaml에서 시크릿을 참조하려면 다음과 같이 하십시오:

hyperdx:
  apiKey:
    valueFrom:
      secretKeyRef:
        name: hyperdx-secret
        key: API_KEY

ClickHouse Cloud 사용

ClickHouse Cloud를 사용하는 경우 Helm 차트로 배포한 ClickHouse 인스턴스를 비활성화하고 Cloud 자격 증명을 지정합니다:

# ClickHouse Cloud 자격 증명 지정
export CLICKHOUSE_URL=<CLICKHOUSE_CLOUD_URL> # 전체 https URL
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>

# 기본 connection을 덮어쓰는 방법
helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.clickhouseEndpoint=${CLICKHOUSE_URL} \
  --set clickhouse.config.users.otelUser=${CLICKHOUSE_USER} \
  --set clickhouse.config.users.otelUserPassword=${CLICKHOUSE_PASSWORD}

또는 values.yaml 파일을 사용할 수도 있습니다:

clickhouse:
  enabled: false
  persistence:
    enabled: false
  config:
    users:
      otelUser: ${CLICKHOUSE_USER}
      otelUserPassword: ${CLICKHOUSE_PASSWORD}

otel:
  clickhouseEndpoint: ${CLICKHOUSE_URL}

hyperdx:
  defaultConnections: |
    [
      {
        "name": "External ClickHouse",
        "host": "http://your-clickhouse-server:8123",
        "port": 8123,
        "username": "your-username",
        "password": "your-password"
      }
    ]
helm install my-clickstack clickstack/clickstack -f values.yaml
# 또는 이미 설치되어 있는 경우...
# helm upgrade my-clickstack clickstack/clickstack -f values.yaml

프로덕션 참고 사항

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

ClickHouse와 OTel collector를 비활성화하려면 다음 values를 설정하십시오:

helm install my-clickstack clickstack/clickstack \
  --set clickhouse.enabled=false \
  --set clickhouse.persistence.enabled=false \
  --set otel.enabled=false

작업 구성

기본적으로 차트 설정에는 크론 작업으로 1개의 작업이 포함되어 있으며, 알림을 보내야 하는지 확인하는 역할을 합니다. 다음은 해당 구성 옵션입니다.

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

차트 업그레이드

새 버전으로 업그레이드하려면:

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

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

helm search repo clickstack

ClickStack 제거

배포를 삭제하려면:

helm uninstall my-clickstack

이렇게 하면 릴리스와 관련된 모든 리소스가 제거되지만, 영구 데이터가 있는 경우 남아 있을 수 있습니다.

문제 해결

로그 확인

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 배포 가이드

v2.x 문서

추가 자료

Navigation