ClickHouse Operator の概要 - ClickHouse Documentation

このドキュメントでは、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 クラスターが必要です。 operator が管理する KeeperCluster を、keeperClusterRef を使って ClickHouseCluster の spec で参照してください。デフォルトでは、operator は ClickHouseCluster のネームスペース内を参照しますが、keeperClusterRef.namespace を設定して、監視対象の別のネームスペース内にある KeeperCluster を指定することもできます。 operator の管理対象外の Keeper アンサンブルを使用する場合は、代わりに externalKeeper にそのサーバーを列挙してください。詳しくは、外部で管理される Keeper を参照してください。

1 対 1 の Keeper の対応関係

デフォルトでは、各 ClickHouseCluster には専用の KeeperCluster が必要です。 なぜですか？ operator は、各 ClickHouseCluster が自身の Keeper にアクセスするための一意の認証キーを自動生成します。このキーは Secret に保存されます。影響:

以下の設定を行わない限り、複数の ClickHouseCluster から同じ KeeperCluster を参照することはできません
ClickHouseCluster を再作成する場合は、対応する KeeperCluster も再作成する必要があります

1 つの Keeper クラスターを共有するには、ClickHouseCluster ごとに settings.extraConfig で異なる zookeeper.root を設定し、 ClickHouse の起動前にその znode を作成しておいてください。詳しくは外部で管理される Keeper を参照してください。

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

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

ClickHouseCluster リソースを削除します
KeeperCluster リソースを削除します
すべてのポッドが終了するまで待ちます
必要に応じて、PersistentVolumeClaims を削除してクリーンな状態からやり直します
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 の完全なドキュメント

​ClickHouse Operator とは

​カスタムリソース

​ClickHouseCluster

​KeeperCluster

​協調

​ClickHouse Keeper は必須です

​1 対 1 の Keeper の対応関係

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

​レプリケートされるもの

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

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

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

​ストレージ管理

​データボリュームの設定

​ストレージのライフサイクル

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

​次のステップ

ClickHouse Operator とは

カスタムリソース

ClickHouseCluster

KeeperCluster

協調

ClickHouse Keeper は必須です

1 対 1 の Keeper の対応関係

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

レプリケートされるもの

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

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

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

ストレージ管理

データボリュームの設定

ストレージのライフサイクル

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

次のステップ