본문으로 바로가기
본문으로 바로가기

ClickHouse Operator 소개

이 문서는 ClickHouse Operator의 핵심 개념과 사용 패턴을 개괄적으로 설명합니다.

ClickHouse Operator란 무엇입니까​

ClickHouse Operator는 Kubernetes에서 ClickHouse 클러스터의 배포와 관리를 자동화하는 Kubernetes 오퍼레이터입니다. 오퍼레이터 패턴을 기반으로 구현되어, ClickHouse 클러스터와 그 종속성을 표현하는 커스텀 리소스를 통해 Kubernetes API를 확장합니다.

이 Operator는 다음과 같은 작업을 처리합니다:

  • 클러스터 수명 주기 관리(생성, 업데이트, 스케일링, 삭제)
  • ClickHouse Keeper 클러스터 조정
  • 자동 구성 생성
  • 데이터베이스 스키마 동기화
  • 롤링 업데이트 및 업그레이드
  • 스토리지 프로비저닝

커스텀 리소스​

오퍼레이터는 두 개의 주요 커스텀 리소스 정의(CRD)를 제공합니다.

ClickHouseCluster​

레플리카와 세그먼트를 구성할 수 있는 ClickHouse 데이터베이스 클러스터를 나타냅니다.

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi

KeeperCluster​

분산 조정을 위한 ClickHouse Keeper 클러스터(ZooKeeper 대체)를 나타냅니다.

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

조정​

ClickHouse Keeper는 필수입니다​

각 ClickHouseCluster에는 분산 조정을 위한 ClickHouse Keeper 클러스터가 필요합니다. Keeper 클러스터는 keeperClusterRef를 사용하여 ClickHouseCluster 스펙에서 참조되어야 합니다.

1:1 Keeper 관계​

각 ClickHouseCluster는 전용 KeeperCluster를 하나씩 가져야 합니다. 여러 ClickHouseCluster가 하나의 KeeperCluster를 공유할 수는 없습니다.

이유는 무엇입니까? 오퍼레이터는 각 ClickHouseCluster가 해당 Keeper에 접근할 수 있도록 고유한 인증 키를 자동으로 생성합니다. 이 키는 Secret에 저장되며 공유할 수 없습니다.

결과:

  • 여러 ClickHouseCluster는 동일한 KeeperCluster를 참조할 수 없습니다.
  • ClickHouseCluster를 다시 생성하려면 해당 KeeperCluster도 다시 생성해야 합니다.
참고

ClickHouseCluster 또는 KeeperCluster 리소스를 삭제해도 Persistent Volume은 자동으로 삭제되지 않습니다.

클러스터를 다시 생성할 때는 다음 순서로 진행하십시오.

  1. ClickHouseCluster 리소스를 삭제합니다.
  2. KeeperCluster 리소스를 삭제합니다.
  3. 모든 파드가 종료될 때까지 기다립니다.
  4. 완전히 새로 시작하려는 경우 선택적으로 PersistentVolumeClaim을 삭제합니다.
  5. KeeperCluster와 ClickHouseCluster를 함께 다시 생성합니다.

인증 오류를 피하려면 Persistent Volume을 수동으로 삭제하거나, 새로운 스토리지를 사용해 두 클러스터를 동시에 다시 생성해야 합니다.

스키마 복제​

ClickHouse Operator는 클러스터 내 모든 레플리카에 데이터베이스 정의를 자동으로 복제합니다.

복제되는 항목​

operator는 다음을 동기화합니다.

  • Replicated 데이터베이스 정의
  • 통합 데이터베이스 엔진(PostgreSQL, MySQL 등)

operator는 다음은 동기화하지 않습니다.

  • 복제되지 않은 데이터베이스(Atomic, Ordinary 등)
  • 복제되지 않은 데이터베이스의 로컬 테이블
  • 테이블 데이터(ClickHouse 복제가 처리합니다)
모범 사례

프로덕션 배포에서는 항상 Replicated 데이터베이스 엔진을 사용하십시오.

이점:

  • 모든 노드 간 스키마 자동 복제
  • 테이블 관리 단순화
  • Operator가 새로운 레플리카와 동기화 가능
  • 클러스터 전반에서 일관된 스키마 유지

분산 DDL로 데이터베이스를 생성합니다:

CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;

Non-Replicated 엔진 사용 피하기​

Non-Replicated 데이터베이스 엔진(Atomic, Lazy, SQLite, Ordinary)은 스키마를 수동으로 관리해야 합니다.

  • 각 레플리카마다 테이블을 개별적으로 CREATE 해야 합니다
  • 노드 간에 스키마 불일치(스키마 드리프트)가 발생할 수 있습니다
  • 오퍼레이터는 새 레플리카를 자동으로 동기화할 수 없습니다

스키마 복제 비활성화​

자동 스키마 복제를 비활성화하려면 ClickHouseCluster 리소스의 spec.settings.enableDatabaseSync를 false로 설정합니다.

스토리지 관리​

오퍼레이터는 Kubernetes PersistentVolumeClaim(PVC)를 통해 스토리지를 관리합니다.

데이터 볼륨 구성​

스토리지 요구사항을 dataVolumeClaimSpec에 지정합니다.

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 500Gi

스토리지 수명 주기​

  • 생성: 클러스터 생성 시 PVC가 자동으로 생성됩니다.
  • 확장: StorageClass에서 볼륨 확장을 허용하는 경우 확장이 지원됩니다.
  • 보존: 클러스터를 삭제해도 PVC는 자동으로 삭제되지 않습니다.
  • 재사용: 동일한 이름으로 클러스터를 다시 생성하는 경우 기존 PVC를 재사용할 수 있습니다.

스토리지를 완전히 제거하려면:

# Delete cluster
kubectl delete clickhousecluster my-cluster

# Wait for pods to terminate
kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster

# Delete PVCs
kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster

기본 구성 주요 사항​

  • 사전 구성된 클러스터: 모든 ClickHouse 노드를 포함하는 이름이 'default'인 클러스터입니다.
  • 기본 매크로: 몇 가지 유용한 매크로가 미리 정의되어 있습니다.
    • {cluster}: 클러스터 이름 (default)
    • {shard}: 세그먼트 번호
    • {replica}: 레플리카 번호
  • Role Based Access Control(RBAC) 엔터티용 복제 스토리지
  • User Defined Functions(UDF)용 복제 스토리지

다음 단계​