メインコンテンツへスキップ
メインコンテンツへスキップ

ClickHouse Operator の概要

このドキュメントでは、ClickHouse Operator の主要な概念と利用パターンについて概説します。

ClickHouse Operator とは​

ClickHouse Operator は、Kubernetes 上で ClickHouse クラスターのデプロイと管理を自動化する Kubernetes オペレーターです。オペレーターパターンを用いて構築されており、ClickHouse クラスターとその依存関係を表すカスタムリソースによって Kubernetes API を拡張します。

このオペレーターは次の機能を提供します:

  • クラスターのライフサイクル管理（作成、更新、スケーリング、削除）
  • ClickHouse Keeper クラスターのコーディネーション
  • 設定の自動生成
  • データベーススキーマの同期
  • ローリングアップデートおよびアップグレード
  • ストレージのプロビジョニング

カスタムリソース​

ClickHouse オペレーターは、2 種類のカスタムリソース定義（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​

分散コーディネーション（ZooKeeper の代替）を行う ClickHouse Keeper クラスターを表します。

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

調整​

ClickHouse Keeper は必須です​

すべての ClickHouseCluster は、分散協調のために ClickHouse Keeper クラスターを必要とします。 Keeper クラスターは、ClickHouseCluster の Spec 内で keeperClusterRef を使用して参照する必要があります。

1 対 1 の Keeper 関係​

各 ClickHouseCluster は、それぞれ専用の KeeperCluster を持つ必要があります。1 つの KeeperCluster を複数の ClickHouseCluster 間で共有することはできません。

理由: オペレーターは、各 ClickHouseCluster が自身の Keeper にアクセスするための一意の認証キーを自動生成します。このキーは Secret に保存され、共有することはできません。

影響:

  • 複数の ClickHouseCluster は、同じ KeeperCluster を参照できません
  • ClickHouseCluster を再作成する場合、その KeeperCluster も再作成する必要があります
注記

ClickHouseCluster または KeeperCluster のリソースを削除しても、Persistent Volumes は自動では削除されません。

クラスターを再作成する場合:

  1. ClickHouseCluster リソースを削除する
  2. KeeperCluster リソースを削除する
  3. すべてのポッドが終了するまで待機する
  4. 完全に新しく開始したい場合は、必要に応じて PersistentVolumeClaims を削除する
  5. KeeperCluster と ClickHouseCluster の両方をまとめて再作成する

認証エラーを回避するには、Persistent Volumes を手動で削除するか、新しいストレージを使用して両方のクラスターを同時に再作成してください。

スキーマのレプリケーション​

ClickHouse Operator は、クラスター内のすべてのレプリカ間でデータベース定義を自動的にレプリケートします。

レプリケーションされる対象​

オペレーターが同期する対象:

  • Replicated データベース定義
  • 統合用データベースエンジン (PostgreSQL、MySQL など)

オペレーターが同期 しない 対象:

  • レプリケーションされていないデータベース (Atomic、Ordinary など)
  • レプリケーションされていないデータベース内のローカルテーブル
  • テーブルデータ (ClickHouse のレプリケーションで処理される)
ベストプラクティス

本番デプロイメントでは常に Replicated データベースエンジンを使用してください。

利点:

  • すべてのノード間でスキーマが自動的にレプリケーションされる
  • テーブル管理が簡素化される
  • Operator により新しいレプリカと同期できる
  • クラスター全体で一貫したスキーマを維持できる

分散 DDL を使用してデータベースを作成します:

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

非 Replicated エンジンの使用を避ける​

非レプリケーション対応のデータベースエンジン（Atomic、Lazy、SQLite、Ordinary）は、スキーマを手動で管理する必要があります。

  • テーブルは各レプリカごとに個別に作成する必要がある
  • ノード間でスキーマのドリフト（不整合）が発生する可能性がある
  • Operator は新しいレプリカを自動的に同期できない

スキーマのレプリケーションを無効にする​

自動スキーマレプリケーションを無効にするには、ClickHouseCluster リソース内の spec.settings.enableDatabaseSync を false に設定します。

ストレージ管理​

ClickHouse Operator は 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}: レプリカ番号
  • ロールベースアクセス制御 (RBAC) エンティティ用のレプリケーションされるストレージ
  • ユーザー定義関数 (UDF) 用のレプリケーションされるストレージ

次のステップ​