ClickHouse Operator 設定ガイド

このガイドでは、Operatorを使用して ClickHouse および Keeper のクラスターを設定する方法を説明します。

ClickHouseCluster の設定

基本設定

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # シャードあたりのレプリカ数
  shards: 2             # 分片数
  keeperClusterRef:
    name: my-keeper     # KeeperCluster への参照
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

レプリカと分片

レプリカ: 各分片あたりの ClickHouse インスタンス数 (高可用性のため)
分片: 水平分割数 (スケーリングのため)

spec:
  replicas: 3  # デフォルト: 3
  shards: 2    # デフォルト: 1

replicas: 3、shards: 2 のクラスターでは、ClickHouse ポッドが合計 6 つ作成されます。

Keeper インテグレーション

すべてのClickHouseクラスターで、調整用のKeeperClusterを参照する必要があります。

spec:
  keeperClusterRef:
    name: my-keeper
    # namespace: keeper-system  # 省略可能。デフォルトはClickHouseClusterのネームスペース

keeperClusterRef.namespace が設定されている場合、オペレーターは両方のネームスペースを監視する必要があります。WATCH_NAMESPACE が設定されている場合は、その一覧に ClickHouse と Keeper のネームスペースを含めてください。

KeeperCluster の設定

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # 奇数である必要があります: 1, 3, 5, 7, 9, 11, 13, または 15
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 5Gi

ストレージ構成

永続ストレージを設定します：

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # オプション: インストール済みのCSIに合わせてストレージクラスを選択してください
    resources:
      requests:
        storage: 100Gi

Operator が既存の PVC を変更できるのは、使用しているストレージクラスがボリューム拡張に対応している場合のみです。

ポッドの設定

トポロジースプレッドとアフィニティの自動設定

ポッドをアベイラビリティゾーン間に分散します:

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname

Kubernetesクラスターに、分散制約を満たせるだけのノードが異なるゾーンに十分にあることを確認してください。

手動設定

ポッドのアフィニティ/アンチアフィニティルールやトポロジースプレッド制約を任意に指定できます。

spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>

サポートされているすべてのポッドテンプレートオプションについては、API リファレンスを参照してください。

ポッドの停止予算

オペレーターは、各クラスターに対して PodDisruptionBudget (PDB) を作成します。これにより、自発的な中断 (ノードのドレイン、ローリングアップグレード、オートスケーラーによるエビクション) が発生しても、クォーラムの喪失や可用性の低下につながるほど多くのポッドが停止しないようにできます。複数の分片を持つ ClickHouse クラスターでは、分片ごとに 1 つの PDB が作成されます。これにより、ある分片での中断が別の分片の許容範囲として扱われることはありません。

デフォルト

オペレーターはクラスターのサイズに応じて安全なデフォルト値を選択するため、新規に apply した時点で、意図しないクォーラムの喪失から保護されます。

Resource	Topology	Default PDB
`ClickHouseCluster`	`replicas: 1` (単一レプリカの分片)	`maxUnavailable: 1` — 単一ノードのクラスターでは中断を許可し、ノードのドレインが妨げられないようにします
`ClickHouseCluster`	`replicas: 2+` (複数レプリカの分片)	`minAvailable: 1` — 各分片で少なくとも 1 つのレプリカが稼働したままでなければなりません
`KeeperCluster`	`replicas: 1`	`maxUnavailable: 1` — 単一ノードのクラスターでは中断を許可し、ノードのドレインが妨げられないようにします
`KeeperCluster`	`replicas: 3+`	`maxUnavailable: replicas/2` — `2F+1` クラスターの RAFT クォーラムを維持します (3 レプリカでは 1 台の停止、5 レプリカでは 2 台の停止まで許容)

replicas: 3 の 3 分片 ClickHouseCluster では、オペレーターは分片ごとに 1 つずつ、合計 3 つの PDB を作成し、それぞれに minAvailable: 1 を設定します。

デフォルト設定の上書き

spec.podDisruptionBudget を使用して、minAvailable または maxUnavailable のいずれか一方のみを上書きできます (必ずどちらか一方のみ) :

spec:
  replicas: 3
  shards: 2
  podDisruptionBudget:
    minAvailable: 2   # 障害発生時に各分片で3つのレプリカのうち少なくとも2つを稼働状態に維持する

または、パーセンテージで指定する maxUnavailable 形式:

spec:
  replicas: 5
  podDisruptionBudget:
    maxUnavailable: 40%

minAvailable と maxUnavailable の両方を設定すると、検証 webhook によって拒否されます。どちらか一方を選んでください。Kubernetes 自体も、この 2 つを同時に許可していません。

生成される PDB に unhealthyPodEvictionPolicy フィールドをそのまま渡すこともできます。これは、まだ NotReady 状態のポッドのエビクションを許可する必要がある場合に便利です。

spec:
  podDisruptionBudget:
    minAvailable: 2
    unhealthyPodEvictionPolicy: AlwaysAllow

ポリシー

spec.podDisruptionBudget.policy では、オペレーターが PDB をどの程度積極的に管理するかを選択できます。

Policy	挙動
`Enabled` (default)	オペレーターはリコンサイルのたびに PDB を作成・更新します。これは本番環境で安全に使えるデフォルト設定です。
`Disabled`	オペレーターは PDB を作成せず、一致するラベルを持つ既存の PDB を削除します。あらゆる自発的な中断を許可したい開発用クラスターで便利です。
`Ignored`	オペレーターは PDB を作成も削除もしません。既存の PDB はそのまま維持されます。別のシステム (例: policy admission、GitOps tool) が PDB 管理を担っている場合に使用します。

例 — 開発用クラスターで PDB 管理を完全に無効にする:

spec:
  podDisruptionBudget:
    policy: Disabled

例 — 手動で作成した PDB をクラスターと同じ場所に置き、オペレーターがそれを変更しないようにします:

spec:
  podDisruptionBudget:
    policy: Ignored

クラスター全体での無効化

PDB の管理は、オペレーターの ENABLE_PDB 環境変数を使用して、クラスター全体で無効にすることもできます。ENABLE_PDB=false の場合、オペレーターは すべての ClickHouseCluster と KeeperCluster について、spec.podDisruptionBudget.policy の設定にかかわらず PDB のリコンサイル手順をスキップし、PodDisruptionBudget リソースを一切監視しません。そのため、オペレーターの ServiceAccount には poddisruptionbudgets.policy/v1 に対する RBAC 権限は不要です。これは、それらの権限を意図的に含めていない制限付きの ServiceAccount でオペレーターを実行する場合に便利です。

# operatorのデプロイメントspecに記述
env:
- name: ENABLE_PDB
  value: "false"

これは、独自の中断ポリシー (たとえば Gatekeeper / Kyverno 経由) を備えており、オペレーターを完全に関与させたくない環境を対象としています。

コンテナーの設定

カスタムイメージ

特定のClickHouseイメージを使用します。

spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent

コンテナーのリソース

ClickHouse コンテナーの CPU とメモリを設定します。

# デフォルト値
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "1Gi"

環境変数

任意の環境変数を追加します:

spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"

ボリュームマウント

追加のボリュームマウントを設定します:

spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml

同じmountPathに対して複数のボリュームマウントを指定できます。 Operator は、指定されたすべてのマウントを含む projected volume を作成します。

サポートされているすべてのコンテナーテンプレートオプションについては、API リファレンスを参照してください。

TLS/SSL 設定

セキュアなエンドポイントを設定する

セキュアなエンドポイントを有効にするには、TLS 証明書を含む Kubernetes Secret への参照を指定します

spec:
  settings:
    tls:
      enabled: true
      required: true # 設定すると、非セキュアポートは無効になります
      serverCertSecret:
        name: <certificate-secret-name>

SSL 証明書 Secret の形式

Secret には、以下のキーが含まれている必要があります。

tls.crt - PEM エンコードされたサーバー証明書
tls.key - PEM エンコードされた秘密鍵
ca.crt - PEM エンコードされた CA 証明書チェーン

この形式は、cert-manager によって生成された証明書と互換性があります。

TLS を介した ClickHouse-Keeper 通信

KeeperCluster で TLS が有効になっている場合、ClickHouseCluster は Keeper ノードへのセキュアな接続を自動的に使用します。 ClickHouseCluster は、Keeper ノードの証明書を検証できる必要があります。 ClickHouseCluster で TLS が有効になっている場合、検証には ca.crt バンドルが使用されます。そうでない場合は、デフォルトの CA バンドルが使用されます。必要に応じて、カスタム CA バンドルへの参照を指定できます。

spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>

ClickHouse の設定

デフォルトユーザーのパスワード

デフォルトユーザーのパスワードを設定します。

spec:
  settings:
    defaultUserPassword:
      passwordType: <password-type> # デフォルト: password
      <secret|configMap>:
        name: <resource name>
        key: <password>

平文のパスワードの保存に ConfigMap を使用することは推奨されません。

Secret を作成します:

kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'

ユーザーパスワードに ConfigMap を使用する

機密性の低いデフォルトパスワードについては、ConfigMap を使用することもできます。

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password

設定でのカスタムユーザー

設定ファイルで追加ユーザーを設定します。ユーザー用のConfigMapとSecretを作成します。

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          - query: "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")

ClickHouseCluster にカスタム設定を追加します:

spec:
  podTemplate:
    volumes:
      - name: reader-user
        configMap:
          name: user-config
  containerTemplate:
    env:
      - name: READER_PASSWORD
        valueFrom:
          secretKeyRef:
            name: reader-password
            key: password
    volumeMounts:
      - mountPath: /etc/clickhouse-server/users.d/
        name: reader-user
        readOnly: true

データベース同期

新しいレプリカのデータベース自動同期を有効にします。

spec:
  settings:
    enableDatabaseSync: true  # デフォルト: true

有効にすると、オペレーターは Replicated テーブルとインテグレーションテーブルを新しいレプリカに同期します。

カスタム設定

埋め込みの追加設定

カスタムの設定ファイルをマウントする代わりに、追加の ClickHouse 設定オプションを直接指定できます。 extraConfig を使用して、カスタムの ClickHouse 設定を追加します。

spec:
  settings:
    extraConfig:
      background_pool_size: 20

役立つリンク:

埋め込み追加ユーザー設定

extraUsersConfig を使用すると、追加の ClickHouse ユーザー設定を指定することもできます。これは、ユーザー、プロファイル、クォータ、権限をクラスター仕様内で直接定義する場合に便利です。

spec:
  settings:
    extraUsersConfig:
      users:
        analyst:
          password:
            - '@from_env': ANALYST_PASSWORD
          profile: "readonly"
          quota: "default"
      profiles:
        readonly:
          readonly: 1
          max_memory_usage: 10000000000
      quotas:
        default:
          interval:
            duration: 3600
            queries: 1000
            errors: 100

extraUsersConfig は k8s の ConfigMap オブジェクトに保存されます。平文のシークレットはそこに保存しないでください。

サポートされているすべての ClickHouse ユーザー設定オプションについては、ドキュメントを参照してください。

設定例

設定例全体は次のとおりです:

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 10Gi
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  containerTemplate:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: <keeper-certificate-secret>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: default-user-password
data:
  # シークレットパスワード
  password: "..." # パスワードのsha256 16進数
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 200Gi
  keeperClusterRef:
    name: sample
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        key: password
        name: default-password

Install

Guides

Reference

ClickHouseCluster の設定

基本設定

レプリカと分片

Keeper インテグレーション

KeeperCluster の設定

ストレージ構成

ポッドの設定

トポロジースプレッドとアフィニティの自動設定

手動設定

サポートされているすべてのポッドテンプレートオプションについては、API リファレンスを参照してください。

ポッドの停止予算

デフォルト

デフォルト設定の上書き

ポリシー

クラスター全体での無効化

コンテナーの設定

カスタムイメージ

コンテナーのリソース

環境変数

ボリュームマウント

サポートされているすべてのコンテナーテンプレートオプションについては、API リファレンスを参照してください。

TLS/SSL 設定

セキュアなエンドポイントを設定する

SSL 証明書 Secret の形式

TLS を介した ClickHouse-Keeper 通信

ClickHouse の設定

デフォルトユーザーのパスワード

ユーザーパスワードに ConfigMap を使用する

設定でのカスタムユーザー

データベース同期

カスタム設定

埋め込みの追加設定

役立つリンク:

埋め込み追加ユーザー設定

サポートされているすべての ClickHouse ユーザー設定オプションについては、ドキュメントを参照してください。

設定例

​ClickHouseCluster の設定

​基本設定

​レプリカと分片

​Keeper インテグレーション

​KeeperCluster の設定

​ストレージ構成

​ポッドの設定

​トポロジースプレッドとアフィニティの自動設定

​手動設定

​サポートされているすべてのポッドテンプレートオプションについては、API リファレンスを参照してください。

​ポッドの停止予算

​デフォルト

​デフォルト設定の上書き

​ポリシー

​クラスター全体での無効化

​コンテナーの設定

​カスタムイメージ

​コンテナーのリソース

​環境変数

​ボリュームマウント

​サポートされているすべての コンテナー テンプレートオプションについては、API リファレンスを参照してください。

​TLS/SSL 設定

​セキュアなエンドポイントを設定する

​SSL 証明書 Secret の形式

​TLS を介した ClickHouse-Keeper 通信

​ClickHouse の設定

​デフォルトユーザーのパスワード

​ユーザーパスワードに ConfigMap を使用する

​設定でのカスタムユーザー

​データベース同期

​カスタム設定

​埋め込みの追加設定

​役立つリンク:

​埋め込み追加ユーザー設定

​サポートされているすべての ClickHouse ユーザー設定オプションについては、ドキュメントを参照してください。

​設定例

ClickHouseCluster の設定

基本設定

レプリカと分片

Keeper インテグレーション

KeeperCluster の設定

ストレージ構成

ポッドの設定

トポロジースプレッドとアフィニティの自動設定

手動設定

サポートされているすべてのポッドテンプレートオプションについては、API リファレンスを参照してください。

ポッドの停止予算

デフォルト

デフォルト設定の上書き

ポリシー

クラスター全体での無効化

コンテナーの設定

カスタムイメージ

コンテナーのリソース

環境変数

ボリュームマウント

サポートされているすべてのコンテナーテンプレートオプションについては、API リファレンスを参照してください。

TLS/SSL 設定

セキュアなエンドポイントを設定する

SSL 証明書 Secret の形式

TLS を介した ClickHouse-Keeper 通信

ClickHouse の設定

デフォルトユーザーのパスワード

ユーザーパスワードに ConfigMap を使用する

設定でのカスタムユーザー

データベース同期

カスタム設定

埋め込みの追加設定

役立つリンク:

埋め込み追加ユーザー設定

サポートされているすべての ClickHouse ユーザー設定オプションについては、ドキュメントを参照してください。

設定例