ClickHouse Operator の概要

このドキュメントでは、ClickHouse Operator の主要な概念と基本的な使用方法の概要を説明します。

このドキュメントでは、ClickHouse Operator の主要な概念と基本的な使用方法の概要を説明します。

​

ClickHouse Operator とは

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

この operator は次を担います:

• クラスターのライフサイクル管理 (作成、更新、スケーリング、削除)
• ClickHouse Keeper クラスターの協調
• 構成の自動生成
• データベーススキーマの同期
• ローリング更新とアップグレード
• ストレージのプロビジョニング

​

カスタムリソース

operator は、主要なカスタムリソース定義 (CRD) を 2 つ提供しています。

​

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 の spec で参照する必要があります。デフォルトでは、operator は ClickHouseCluster のネームスペース内を参照しますが、keeperClusterRef.namespace を設定して、監視対象の別のネームスペース内にある KeeperCluster を指定することもできます。

​

1 対 1 の Keeper の対応関係

各 ClickHouseCluster には、専用の KeeperCluster が必要です。1 つの KeeperCluster を複数の ClickHouseCluster で共有することはできません。

なぜですか？ operator は、各 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 は、データベースの定義をクラスター内のすべてのレプリカに自動的にレプリケートします。

​

レプリケートされるもの

operator は以下を同期します。

• Replicated データベースの定義
• インテグレーション用データベースエンジン (PostgreSQL、MySQL など)

operator は以下を同期しません。

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

​

推奨: Replicated データベースエンジンを使用する

ベストプラクティス

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

利点:

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

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

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

​

Replicated 以外のエンジンを避ける

レプリケーションされないデータベースエンジン (Atomic、Lazy、SQLite、Ordinary) では、スキーマを手動で管理する必要があります。

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

​

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

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

​

ストレージ管理

operator は、Kubernetes の PersistentVolumeClaim (PVC) を通じてストレージを管理します。

​

データボリュームの設定

dataVolumeClaimSpec でストレージ要件を指定します。

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    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-clickhouse

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

​

デフォルト構成の主なポイント

• 事前設定済みのクラスター: すべての ClickHouse ノードを含む、default という名前のクラスター。
• デフォルトのマクロ: 便利なマクロがいくつか事前定義されています:
  • {cluster}: クラスター名 (default)
  • {shard}: 分片番号
  • {replica}: レプリカ番号
• ロールベースのアクセス制御 (RBAC) エンティティ向けのレプリケートストレージ
• ユーザー定義関数 (UDF) 向けのレプリケートストレージ

​

次のステップ

• 設定ガイド - 設定オプションの詳細
• API リファレンス - API の完全なドキュメント