> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Helm > Helm을 사용한 ClickStack 배포 - ClickHouse 관측성 스택 export const Image = ({img, alt, size}) => { return {alt} ; }; **차트 버전 2.x** 이 페이지는 **v2.x** 서브차트 기반 Helm 차트를 설명합니다. 아직 v1.x 인라인 템플릿 차트를 사용 중이라면 [v1.x Helm 가이드](/ko/clickstack/deployment/helm-v1)를 참조하십시오. 마이그레이션 절차는 [업그레이드 가이드](/ko/clickstack/deployment/helm-upgrade)를 참조하십시오. ClickStack용 Helm 차트는 [여기](https://github.com/ClickHouse/ClickStack-helm-charts)에서 확인할 수 있으며, 프로덕션 배포에 **권장되는** 방법입니다. v2.x 차트는 **2단계 설치** 방식을 사용합니다. 먼저 `clickstack-operators` 차트를 통해 오퍼레이터와 CRD를 설치한 다음, 메인 `clickstack` 차트를 설치하여 ClickHouse, MongoDB, OpenTelemetry Collector에 대한 오퍼레이터 관리 사용자 지정 리소스를 생성합니다. 기본적으로 Helm 차트는 다음을 포함한 모든 핵심 구성 요소를 프로비저닝합니다. * **ClickHouse** — `ClickHouseCluster` 및 `KeeperCluster` 사용자 지정 리소스를 통해 [ClickHouse Operator](/ko/products/kubernetes-operator/overview)가 관리 * **HyperDX** — 관측성 UI 및 API * **OpenTelemetry (OTel) collector** — [공식 OpenTelemetry Collector Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts)를 서브차트로 사용해 배포 * **MongoDB** — `MongoDBCommunity` 사용자 지정 리소스를 통해 [MongoDB Kubernetes Operator (MCK)](https://github.com/mongodb/mongodb-kubernetes)가 관리 하지만 기존 ClickHouse 배포와 통합하도록 쉽게 사용자 지정할 수 있습니다. 예를 들어 **ClickHouse Cloud**에서 호스팅되는 배포를 연동할 수 있습니다. 이 차트는 다음과 같은 Kubernetes의 표준 모범 사례를 지원합니다. * `values.yaml`을 통한 환경별 구성 * 리소스 제한 및 파드 수준 스케일링 * TLS 및 인그레스 구성 * 시크릿 관리 및 인증 설정 * 차트와 함께 임의의 Kubernetes 객체(NetworkPolicy, HPA, ALB Ingress 등)를 배포하기 위한 [추가 매니페스트](/ko/clickstack/deployment/helm-additional-manifests)
### 적합한 용도
* 개념 검증 * 프로덕션 환경
## 배포 절차

### 사전 요구 사항 * [Helm](https://helm.sh/) v3+ * Kubernetes 클러스터(v1.20+ 권장) * `kubectl`이 클러스터와 통신할 수 있도록 구성되어 있음 ### ClickStack Helm 리포지토리 추가 ClickStack Helm 리포지토리를 추가하세요: ```shell theme={null} helm repo add clickstack https://clickhouse.github.io/ClickStack-helm-charts helm repo update ``` ### 오퍼레이터 설치 먼저 오퍼레이터 차트를 설치합니다. 그러면 메인 차트에 필요한 CRD가 등록됩니다: ```shell theme={null} helm install clickstack-operators clickstack/clickstack-operators ``` 계속 진행하기 전에 오퍼레이터 파드가 준비될 때까지 기다리십시오: ```shell theme={null} kubectl get pods -l app.kubernetes.io/instance=clickstack-operators ``` ### ClickStack 설치 오퍼레이터가 실행 중이면 메인 차트를 설치합니다: ```shell theme={null} helm install my-clickstack clickstack/clickstack ``` ### 설치 확인 설치 상태를 확인하세요: ```shell theme={null} kubectl get pods -l "app.kubernetes.io/name=clickstack" ``` 모든 파드가 준비되면 다음 단계로 진행하십시오. ### 포트 포워딩 포트 포워딩을 사용하면 HyperDX에 접근하고 설정할 수 있습니다. 프로덕션 환경에 배포할 때는 적절한 네트워크 액세스, TLS 종료, 확장성을 보장할 수 있도록 인그레스 또는 로드 밸런서를 통해 서비스를 노출해야 합니다. 포트 포워딩은 장기 운영이나 고가용성 환경용이 아니라 로컬 개발 또는 일회성 관리 작업에 가장 적합합니다. ```shell theme={null} kubectl port-forward \ pod/$(kubectl get pod -l app.kubernetes.io/name=clickstack -o jsonpath='{.items[0].metadata.name}') \ 8080:3000 ``` **프로덕션 인그레스 설정** 프로덕션 환경에 배포할 때는 포트 포워딩 대신 TLS를 사용하는 인그레스를 구성하세요. 자세한 설정 방법은 [인그레스 구성 가이드](/ko/clickstack/deployment/helm-configuration#ingress-setup)를 참조하세요. ### UI로 이동 HyperDX UI에 액세스하려면 [http://localhost:8080](http://localhost:8080)에 접속하세요. 요구 사항을 충족하는 사용자 이름과 비밀번호를 입력해 사용자를 생성하세요. HyperDX UI `Create`를 클릭하면 Helm 차트로 배포된 ClickHouse 인스턴스에 대한 데이터 소스가 생성됩니다. **기본 연결 재정의** 통합된 ClickHouse 인스턴스의 기본 연결을 재정의할 수 있습니다. 자세한 내용은 ["ClickHouse Cloud 사용"](#using-clickhouse-cloud)을 참조하세요. ### 값 사용자 지정(선택 사항) `--set` 플래그를 사용해 설정을 사용자 지정할 수 있습니다. 예시는 다음과 같습니다: ```shell theme={null} helm install my-clickstack clickstack/clickstack --set key=value ``` 또는 `values.yaml`을 수정하십시오. 기본값을 확인하려면 다음을 실행하십시오: ```shell theme={null} helm show values clickstack/clickstack > values.yaml ``` 예시 설정: ```yaml theme={null} 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" ``` ```shell theme={null} helm install my-clickstack clickstack/clickstack -f values.yaml ``` ### 시크릿 사용(선택 사항) v2.x chart는 values의 `hyperdx.secrets`를 바탕으로 채워지는 통합 시크릿(`clickstack-secret`)을 사용합니다. ClickHouse 비밀번호, MongoDB 비밀번호, HyperDX API Key를 포함한 모든 민감한 환경 변수는 이 단일 시크릿을 통해 관리됩니다. 시크릿 값을 재정의하려면: ```yaml theme={null} 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 시크릿을 참조할 수 있습니다: ```yaml theme={null} hyperdx: useExistingConfigSecret: true existingConfigSecret: "my-external-secret" existingConfigConnectionsKey: "connections.json" existingConfigSourcesKey: "sources.json" ``` **API Key 관리** 여러 가지 구성 방법과 파드 재시작 절차를 포함한 API Key 설정에 대한 자세한 내용은 [API Key 설정 가이드](/ko/clickstack/deployment/helm-configuration#api-key-setup)를 참조하세요.
## ClickHouse Cloud 사용
ClickHouse Cloud를 사용하는 경우 기본 제공 ClickHouse 인스턴스를 비활성화하고 Cloud 자격 증명을 입력하십시오: ```yaml theme={null} # 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" ``` 연결 시크릿을 별도로 생성하세요: ```bash theme={null} cat < 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 ``` ```shell theme={null} helm install my-clickstack clickstack/clickstack -f values-clickhouse-cloud.yaml ``` **고급 외부 구성** 시크릿 기반 구성, 외부 OTel collector 사용, 또는 최소 구성으로 프로덕션에 배포하는 경우 [배포 옵션 가이드](/ko/clickstack/deployment/helm-deployment-options)를 참조하십시오.
## 프로덕션 참고 사항
기본적으로 이 차트는 ClickHouse, MongoDB 및 OTel collector를 설치합니다. 프로덕션 환경에서는 ClickHouse와 OTel collector를 별도로 관리하는 것이 좋습니다. ClickHouse와 OTel collector를 비활성화하려면: ```yaml theme={null} clickhouse: enabled: false otel-collector: enabled: false ``` **프로덕션 모범 사례** 고가용성 구성, 리소스 관리, 인그레스/TLS 설정, 클라우드별 구성(GKE, EKS, AKS)을 포함한 프로덕션 배포에 대해서는 다음 문서를 참조하십시오. * [구성 가이드](/ko/clickstack/deployment/helm-configuration) - 인그레스, TLS, 시크릿 관리 * [Cloud 배포](/ko/clickstack/deployment/helm-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` 참조 |
## 차트 업그레이드
더 최신 버전으로 업그레이드하려면: ```shell theme={null} helm upgrade my-clickstack clickstack/clickstack -f values.yaml ``` 사용 가능한 Helm 차트 버전을 확인하려면: ```shell theme={null} helm search repo clickstack ``` **v1.x에서 업그레이드** v1.x inline-template 차트에서 업그레이드하는 경우, 마이그레이션 지침은 [업그레이드 가이드](/ko/clickstack/deployment/helm-upgrade)를 참조하십시오. 이는 호환성이 깨지는 변경 사항이므로, 현재 위치에서 `helm upgrade`를 수행하는 방식은 지원되지 않습니다.
## ClickStack 제거
다음 역순으로 제거하십시오: ```shell theme={null} helm uninstall my-clickstack # 앱 + CR 먼저 제거 helm uninstall clickstack-operators # 연산자 + CRD 제거 ``` **참고:** MongoDB 및 ClickHouse 오퍼레이터가 생성한 PersistentVolumeClaims는 `helm uninstall`을 실행해도 **제거되지 않습니다**. 이는 실수로 데이터가 손실되는 것을 방지하기 위한 의도된 동작입니다. PVC를 정리하려면 다음 문서를 참조하십시오. * [MongoDB Kubernetes Operator 문서](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity)
## 문제 해결
### 로그 확인하기
```shell theme={null} kubectl logs -l app.kubernetes.io/name=clickstack ```
### 설치 실패 디버깅
```shell theme={null} helm install my-clickstack clickstack/clickstack --debug --dry-run ```
### 배포 확인
```shell theme={null} kubectl get pods -l app.kubernetes.io/name=clickstack ``` **추가 문제 해결 리소스** 인그레스 관련 이슈, TLS 문제 또는 클라우드 배포 문제 해결은 다음 문서를 참조하십시오: * [Ingress 문제 해결](/ko/clickstack/deployment/helm-configuration#troubleshooting-ingress) - 정적 에셋 제공, 경로 재작성, 브라우저 문제 * [Cloud 배포](/ko/clickstack/deployment/helm-cloud#loadbalancer-dns-resolution-issue) - GKE OpAMP 문제 및 클라우드별 문제
## 스키마 선택: Map vs JSON
ClickStack는 기본적으로 속성을 `Map(LowCardinality(String), String)` 컬럼에 저장합니다. 이는 관측성 워크로드에 권장되는 스키마입니다. [버킷 기반 맵 직렬화](/ko/reference/data-types/map#bucketed-map-serialization)와 맵 키 및 값에 대한 텍스트 인덱스를 함께 사용하면, 동적 JSON 서브컬럼에서 발생하는 키별 수집 오버헤드 없이 필요한 항목만 선택적으로 조회할 수 있습니다. `JSON` 타입 스키마는 속성 키 집합이 작고 안정적인 워크로드에서 평가할 수 있도록 베타로 제공됩니다. 기본값으로는 **권장되지 않습니다**. 전체 비교 내용과 JSON 지원을 활성화하는 데 필요한 환경 변수는 [Map vs JSON type](/ko/clickstack/ingesting-data/schema/map-vs-json)에서 확인하십시오.
### 배포 가이드
* [배포 옵션](/ko/clickstack/deployment/helm-deployment-options) - 외부 ClickHouse, OTel collector 및 최소 배포 * [구성 가이드](/ko/clickstack/deployment/helm-configuration) - API Key, 시크릿 및 인그레스 설정 * [Cloud 배포](/ko/clickstack/deployment/helm-cloud) - GKE, EKS, AKS 구성 및 프로덕션 환경 모범 사례 * [업그레이드 가이드](/ko/clickstack/deployment/helm-upgrade) - v1.x에서 v2.x로 마이그레이션 * [추가 매니페스트](/ko/clickstack/deployment/helm-additional-manifests) - 차트와 함께 사용자 지정 Kubernetes 객체 배포
### v1.x 문서
* [Helm (v1.x)](/ko/clickstack/deployment/helm-v1) - v1.x 배포 가이드 * [구성 (v1.x)](/ko/clickstack/deployment/helm-configuration-v1) - v1.x 구성 * [배포 옵션 (v1.x)](/ko/clickstack/deployment/helm-deployment-options-v1) - v1.x 배포 옵션 * [Cloud 배포 (v1.x)](/ko/clickstack/deployment/helm-cloud-v1) - v1.x Cloud 구성
### 추가 자료
* [ClickStack 시작하기 가이드](/ko/clickstack/getting-started/index) - ClickStack 소개 * [ClickStack Helm 차트 리포지토리](https://github.com/ClickHouse/ClickStack-helm-charts) - 차트 소스 코드 및 values 참고 * [Kubernetes 문서](https://kubernetes.io/docs/) - Kubernetes 참고 * [Helm 문서](https://helm.sh/docs/) - Helm 참고