데이터 분석 환경 구축 - 02. 쿠버네티스에 Clickhouse 설치 및 클러스터 구성

이번 글에서는 Kubernetes 환경에서 ClickHouse를 배포 및 실행하는 방법을 설명합니다.
Docker Desktop의 내장 Kubernetes를 활용하고, Helm 및 Bitnami Helm 차트를 사용하여 간편하게 ClickHouse를 배포합니다.

1. 사전 준비

1) kubectl 설치 (Kubernetes CLI)

kubectl은 Kubernetes 클러스터를 관리하는 명령줄 도구입니다.

🔹 macOS

brew install kubectl

🔹 Windows (PowerShell)

choco install kubernetes-cli

✅ 설치 확인:

kubectl version --client

2) Docker Desktop에서 Kubernetes 활성화

Docker Desktop에는 Kubernetes가 기본적으로 포함되어 있으며, 간단한 설정으로 활성화할 수 있습니다.

🔹 Kubernetes 활성화 방법

1. Docker Desktop 실행
2. Settings(설정) → Kubernetes 탭 이동

3. "Enable Kubernetes" 옵션 체크 후 "Apply & Restart" 클릭

꽤 오랜 시간이 걸립니다.

kubectl 명령어가 정상적으로 동작하는지 확인

kubectl version --client
kubectl get nodes  # Kubernetes 노드 상태 확인

3) Helm 설치 (패키지 매니저)

Helm은 Kubernetes에서 애플리케이션을 쉽게 배포하고 관리할 수 있도록 도와주는 패키지 관리 도구입니다.
로컬에 Helm을 설치하려면 다음 명령어를 실행합니다.

• 자세한 설치 방법은 공식 사이트를 참고하세요

🔹 Helm 설치 (Mac)

brew install helm

🔹 Helm 설치 (Windows)

choco install kubernetes-helm

🔹 설치 확인

helm version

2. Bitnami Helm Chart를 이용한 ClickHouse 설치

이제 Bitnami의 공식 Helm 차트를 사용하여 ClickHouse를 Kubernetes에 배포하겠습니다. Bitnami Helm Repository 추가 후 배포하는 방법도 있지만, values.yaml 파일을 기반으로 배포하는 방법을 소개합니다.

1) ClickHouse value.yaml 파일 생성

먼저 values.yaml 파일을 생성합니다.

mkdir clickhouse-local && cd clickhouse-local
touch values.yaml

생성된 폴더 구조

└── clickhouse-local
    └── values.yaml

그리고 artifacthub 내 bitnami/clickhouse 저장소에 접속하여 values.yaml 원본을 확인합니다.

artifacthub 내 bitnami clickhouse 저장소

values.yaml

해당 원본을 이전에 생성한 values.yaml 파일에 추가합니다.

2) ClickHouse 설정 변경

해당 values.yaml 파일 기반으로 배포하기 위해 몇가지 설정을 변경합니다.

1. Authentication 설정

• values.yaml에서 auth: 를 검색합니다. username과 password를 변경합니다.

2. Resource 설정

• values.yaml에서는 clickhouse, zookeeper에 대한 리소스를 변경할 수 있습니다. 우선 clickhouse의 리소스만 변경하여 배포합니다.
• resourcePreset 설정을 변경하여 이미 지정된 리소스로 배포할 수도 있습니다. 자세한 리소스 preset 설정별 cpu, memory 사용량은 문서를 참고하시기 바랍니다.
• DB IDE(DBeaver, HeidiSQL 등)와 연결을 위해 request(cpu: 2, memory: 1Gi) / limit(cpu:3, memory 2Gi)로 설정했습니다.
  • 이보다 작을 경우 DBeaver에서 연결 시 MEMORY_LIMIT_EXCEED 에러가 발생할 수 있습니다.

3. replica, shard 설정

• values.yaml에서 shards: 를 검색합니다. 이번 실습에서는 shards 2, replicaCount 2로 설정합니다.
• zookeeper의 replicaCount를 2로 변경합니다. 

3) ClickHouse 배포

이제 ClickHouse를 Kubernetes 클러스터에 배포합니다. clickhouse-local 디렉토리에서 실행합니다.

• 각 네임스페이스 별 리소스 관리를 위해 별도의 네임스페이스를 생성하였습니다.(clickhouse)

helm install clickhouse oci://registry-1.docker.io/bitnamicharts/clickhouse -f ./values.yaml --create-namespace --namespace clickhouse

설치가 완료되면, 배포된 리소스를 확인할 수 있습니다.

kubectl get pods -n clickhouse

출력 예시:

NAME                     READY   STATUS    RESTARTS   AGE
clickhouse-shard0-0      1/1     Running   0          53s
clickhouse-shard0-1      1/1     Running   0          78s
clickhouse-shard1-0      1/1     Running   0          53s
clickhouse-shard1-1      1/1     Running   0          78s
clickhouse-zookeeper-0   1/1     Running   0          71s
clickhouse-zookeeper-1   1/1     Running   0          87s

---

3. ClickHouse 접속 및 테스트

1) Pod 내부에서 ClickHouse 접속

ClickHouse Pod에 직접 접속하여 쿼리를 실행할 수 있습니다.

kubectl exec -it pod/clickhouse-shard0-0 -n clickhouse -- clickhouse-client --user <username> --password <password>

 

샘플 데이터 삽입 및 조회

CREATE TABLE default.test_table (
    id UInt32,
    name String
) ENGINE = MergeTree()
ORDER BY id;

INSERT INTO default.test_table VALUES (1, 'Alice'), (2, 'Bob');

SELECT * FROM default.test_table;

 

클러스터 구성 조회

select * from system.clusters

 

2) 외부에서 ClickHouse 접속 (Port Forwarding)

로컬 환경에서 ClickHouse에 접근하려면 포트 포워딩을 설정해야 합니다.

kubectl port-forward svc/clickhouse 8123:8123 -n clickhouse

이제 웹 브라우저 또는 curl 명령어로 ClickHouse의 REST API에 접근할 수 있습니다.

curl "http://localhost:8123/?query=SELECT%201"

출력:

1

4. ClickHouse 업데이트

values.yaml 파일 내 설정 변경 후 업데이트 시 다음 명령어를 사용합니다.

helm upgrade clickhouse oci://registry-1.docker.io/bitnamicharts/clickhouse -f ./clickhouse-local/values.yaml -n clickhouse

 

5. ClickHouse 제거 방법 (Cleanup)

테스트가 끝난 후 Helm을 사용하여 ClickHouse를 삭제할 수 있습니다.

helm uninstall my-clickhouse

삭제된 리소스 확인:

kubectl get all