ClickHouse Operator 設定ガイド - ClickHouse Documentation

このガイドでは、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

ストレージ構成

dataVolumeClaimSpec (標準的な Kubernetes の PersistentVolumeClaimSpec) を使用して永続ストレージを設定します。オペレーターはこれをレプリカごとの PersistentVolumeClaim に変換し、データパス /var/lib/clickhouse にマウントします：

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    resources:
      requests:
        storage: 100Gi

オペレーターが既存の PVC を変更できるのは、基盤となる StorageClass がボリューム拡張に対応している場合のみです。

マルチディスク (JBOD) レイアウトでの追加ディスクの接続、永続ボリュームなしでの実行、容量の拡張、カスタムストレージポリシー、および作成後に何を変更できないかに関するルールについては、専用のストレージとボリュームのガイドで説明しています。

クラスタードメイン

spec.clusterDomain は、オペレーターが ClickHouse server の設定に書き込む完全修飾のポッドホスト名を生成する際に使用する、Kubernetes の DNS 接尾辞を設定します。既定値は cluster.local で、 ClickHouseCluster と KeeperCluster の両方にあります。

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

The オペレーターは、ヘッドレス Service を通じてすべてのポッドに <pod>.<headless-service>.<namespace>.svc.<clusterDomain> の形式でアクセスします。この接尾辞は、生成される構成の 2 つの箇所で使われます。

ClickHouseCluster では、この値が remote_servers 内のレプリカのホスト名に使用されます (レプリカ間および Distributed クエリ用) 。
KeeperCluster では、この値を基に、ClickHouse が協調に使用する Keeper ノードのホスト名が組み立てられます。

これを override するのは、クラスターの キューブレット が cluster.local 以外の --cluster-domain で実行されている場合だけにしてください。値が実際のクラスタードメインと一致しないと、 ClickHouse は Keeper とレプリカのホスト名を解決できず、協調と Distributed クエリは DNS 名前解決エラーで失敗します。参照先の KeeperCluster と ClickHouseCluster の両方に、同じ値を設定してください。

複数ディスク (JBOD) ストレージ

additionalVolumeClaimTemplates を使うと、使用に必須のプライマリ dataVolumeClaimSpec に加えて、各 ClickHouse レプリカに追加のディスクを接続できます。各エントリは PVC テンプレートで、metadata.name と PVC の spec で構成されます。これらのディスクは、プライマリデータディスクとまったく同様に、StatefulSet の volumeClaimTemplates としてリコンサイルされます。そのため、StatefulSet コントローラーはレプリカごとに 1 つの PVC を作成して保持し、その名前は <name>-<statefulset>-0 になります。

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 100Gi
  additionalVolumeClaimTemplates:
    - metadata:
        name: disk1
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 100Gi
    - metadata:
        name: disk2
      spec:
        storageClassName: fast-ssd
        resources:
          requests:
            storage: 100Gi

オペレーターは各追加ボリュームを /var/lib/clickhouse/disks/<name> にマウントし、生成された ClickHouse のストレージ構成に追加します。名前に含まれるハイフンは ClickHouse のディスク識別子ではアンダースコアに変換されますが、マウントパスでは元の名前のままです。プライマリデータディスクとすべての追加ディスクは、default ストレージポリシー内の 1 つのボリュームにまとめて配置されるため、ClickHouse は新しいデータパーツをそれらすべてにラウンドロビンで分散します。使用可能容量はすべてのディスクの合計となり、独自の storage_policy を設定していないすべてのテーブル (system.* テーブルを含む) は、この統合されたディスクセットを使用します。

PVC 名は ^[a-z]([-a-z0-9]*[a-z0-9])?$ に一致している必要があり、プライマリデータボリューム名と重複してはなりません。プライマリデータディスクと同様に、追加ディスクのセットは作成時に固定されます。作成後にエントリを追加、削除、または名前変更することはできず、拒否されます。追加の PVC は、プライマリデータディスクと同様に、クラスターを削除しても保持されます。 StorageClass が拡張をサポートしている場合、既存エントリのストレージサイズは拡張できます。

クラスタードメイン

spec.clusterDomain は、オペレーターが ClickHouse server の設定に書き込むポッドの完全修飾ホスト名を構築する際に使用する Kubernetes の DNS 接尾辞を設定します。既定値は cluster.local で、ClickHouseCluster と KeeperCluster の両方にあります。

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

オペレーターは、ヘッドレス Service 経由で各ポッドを <pod>.<headless-service>.<namespace>.svc.<clusterDomain> として参照します。この接尾辞は、生成される設定の次の 2 か所で使われます。

ClickHouseCluster では、この値が remote_servers 内のレプリカのホスト名に使用されます (レプリカ間および Distributed クエリ用) 。
KeeperCluster では、この値を基に、ClickHouse が協調に使用する Keeper ノードのホスト名が組み立てられます。

これを上書きするのは、クラスターの キューブレット が cluster.local 以外の --cluster-domain で実行されている場合だけにしてください。値が実際のクラスタードメインと一致しないと、ClickHouse は Keeper とレプリカのホスト名を名前解決できず、協調および Distributed クエリが DNS 名前解決エラーで失敗します。参照先の KeeperCluster と ClickHouseCluster の両方に、同じ値を設定してください。

ポッドの設定

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

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

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 とメモリを設定します。

# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "512Mi"

環境変数

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

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 エンコードされた秘密鍵

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

TLS を介した ClickHouse-Keeper 通信

KeeperCluster で TLS が有効になっている場合、ClickHouseCluster は Keeper ノードへのセキュアな接続を自動的に使用します。 ClickHouseCluster は、システムのトラストストアに加えて、設定した caBundle を使用して Keeper ノードの証明書を検証します。プライベート CA (たとえば、自己署名 CA や内部 CA) を信頼するには、カスタム CA バンドルへの参照を指定します。

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

External Secret

デフォルトでは、オペレーターはクラスターの内部認証情報 (interserver password、management password、Keeper identity、cluster secret、named-collections key) を含む Secret を作成して管理します。この Secret にはクラスター名が付けられ、クラスターのネームスペース内に作成されます。これらの認証情報を自分で管理したい場合 (たとえば、HashiCorp Vault、AWS Secrets Manager、または External Secrets Operator から取得する場合) は、spec.externalSecret を使用して、既存の Secret をオペレーターに指定します。

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi
  externalSecret:
    name: my-clickhouse-credentials
    policy: Observe

参照先のSecretは、ClickHouseClusterと同じネームスペース内に存在している必要があります。オペレーターが自ら作成していないSecretを削除することはありません。

必須のキー

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

Key	Format	When required
`interserver-password`	平文のパスワード	常に必須
`management-password`	平文のパスワード	常に必須
`keeper-identity`	`clickhouse:<password>`	常に必須
`cluster-secret`	平文のパスワード	常に必須
`named-collections-key`	16 バイトの AES 秘密鍵を 16 進数でエンコードしたもの (32 文字の 16 進数)	ClickHouse `>= 25.12` の場合のみ

完全な Secret は次のようになります。

apiVersion: v1
kind: Secret
metadata:
  name: my-clickhouse-credentials
  namespace: sample
type: Opaque
stringData:
  interserver-password: "a-strong-random-password"
  management-password: "another-strong-password"
  keeper-identity: "clickhouse:keeper-auth-password"
  cluster-secret: "cluster-internal-secret"
  named-collections-key: "0123456789abcdef0123456789abcdef"   # 32 hex chars = 16 bytes

ポリシー: Observe と Manage

spec.externalSecret.policy は、必須キーが不足している場合にオペレーターがどのように扱うかを制御します。

Policy	キー不足時の動作
`Observe` (デフォルト)	必須キーがすべて揃うまでリコンサイル処理は停止されます。オペレーターは不足している各キーとそのフォーマットのヒントを、`ExternalSecretValid` 条件 (reason は `ExternalSecretInvalid`) と `Warning` イベントで報告します。
`Manage`	オペレーターは不足している必須キーを生成し、同じ Secret に書き戻します。Bootstrap に便利です。空の Secret を作成してオペレーターに値を補完させ、必要に応じてその後アクセスをさらに制限できます。なお、オペレーターが Secret を削除することはありません。

policy: Manage を指定していても、Secret はそのネームスペース内にあらかじめ存在している必要があります。オペレーターは Secret 自体を作成せず、既存の Secret に生成したキーを書き込むだけです。参照先の Secret が存在しない場合、ポリシーに関係なく ExternalSecretNotFound reason でリコンサイル処理は停止されます。

外部システム (Vault、ESO、sealed-secrets、GitOps) を信頼できる情報源として扱い、設定ミスがあればオペレーターに明確に失敗させたい場合は Observe を選択してください。自己完結的な Bootstrap を行いつつ、Secret オブジェクト自体の管理権は保持しておきたい (たとえばバックアップしたい) 場合は Manage を選択してください.

ステータス条件とトラブルシューティング

オペレーターは ClickHouseCluster.status.conditions に ExternalSecretValid 条件を出力します。リコンサイルが停止しているように見える場合は、この条件を確認してください。

# Plain kubectl — works out of the box
kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p'

# Same data as YAML
kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

# Pretty-printed JSON (requires jq)
kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq

考えられる理由:

`reason`	意味	対処
`ExternalSecretNotFound`	参照先の Secret がネームスペース内に存在しません。	Secret を作成するか、`spec.externalSecret.name` を修正してください。
`ExternalSecretInvalid`	Secret は存在しますが、必要なキーが不足しています (`Observe` の場合のみ) 。メッセージには、不足している各キーと想定されるフォーマットが表示されます。	不足しているキーを追加するか、`policy: Manage` に切り替えてください。
`ExternalSecretValid`	必要なキーがすべてそろっており、オペレーターがその Secret を使用しています。	—

Secret が無効な間、オペレーターはリコンサイルを再キューするため、不足しているキーを追加すれば、次回のリコンサイルで自動的に反映されます。ポッドを再起動する必要はありません。

必要なキーのセットは、実行中の ClickHouse のバージョンによって異なります。named-collections-key が検証されるのは、オペレーターの version probe が ClickHouse 25.12 以降を検出した場合のみです。古いバージョンでは、このキーが Secret に含まれていなくても問題ありません。

追加ポート

オペレーターは、すべての ClickHouse ポッドとそのヘッドレス Service で、固定のポート群を公開します。具体的には、8123 HTTP、9000 ネイティブ、9009 interserver、9001 management、9363 Prometheus メトリクス、さらに TLS が有効な場合は TLS 用の 8443/9440 です。ClickHouse で MySQL、PostgreSQL、gRPC、または任意のカスタムポートなどの追加プロトコルを待ち受けるようにするには、spec.additionalPorts で宣言します。

spec:
  additionalPorts:
    - name: mysql
      port: 9004
    - name: postgres
      port: 9005
    - name: grpc
      port: 9100

operator は、それらのポートをポッドの containerPorts と headless Service に追加します。完全な例は、examples/custom_protocols.yaml にあります。

additionalPorts は、Kubernetes 側でのみポートを開きます。これだけでは、ClickHouse server がそれらのポートで待ち受けるようには設定されません。対応するプロトコルを spec.settings.extraConfig.protocols で有効にする必要もあります。これを行わないと、Service 上ではポートが開いていても、ポッド内では何も応答しません。

エンドツーエンドの例: MySQLワイヤプロトコル

ポート 9004 で ClickHouse を MySQLワイヤプロトコル経由で公開するには:

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 1
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 2Gi

  # 1) Open the port on the Pod and the headless Service.
  additionalPorts:
    - name: mysql
      port: 9004

  # 2) Tell ClickHouse server to actually listen on it.
  settings:
    extraConfig:
      protocols:
        mysql:
          type: mysql
          port: 9004
          description: "MySQL wire protocol"

適用後、クラスター内で確認します：

kubectl exec sample-clickhouse-0-0-0 -- \
  clickhouse-client --port 9004 --query "SELECT 1"

フィールドの制約

フィールド	ルール
`name`	DNS_LABEL パターン `^[a-z]([-a-z0-9]*[a-z0-9])?$` に一致する必要があります。最大 63 文字です。一意性は、CRD により list-map キーとして保証されます。
`port`	`[1, 65535]` の整数です。webhook は、リスト内の重複するポート番号を拒否します。

予約済みのポートと名前

validating webhook は、オペレーター自身がバインドするポートと競合する additionalPorts エントリを拒否します。TLS 関連のポートは、後から spec.settings.tls.enabled を切り替えても、それまで有効だったクラスターが壊れないよう、無条件で予約されています。

ポート	予約用途
`8123`	HTTP
`8443`	HTTPS
`9000`	native TCP
`9440`	native TLS
`9009`	interserver
`9001`	management
`9363`	Prometheus メトリクス

次の名前も拒否されます。これらはオペレーターの内部的なプロトコル種別の識別子であり (人が読める別名ではありません) 、以下のとおりです。

名前
`http`
`http-secure`
`tcp`
`tcp-secure`
`interserver`
`management`
`prometheus`

拒否されたリクエストでは、次のようなエラーが生成されます。

spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port
spec.additionalPorts[0].name: "http" is reserved by the operator

バージョンプローブとアップグレードチャネル

オペレーターは、クラスターのバージョンに関して 2 つの独立した処理を行います。

バージョン報告 — ClickHouseCluster では、Kubernetes の Job がコンテナーイメージを 1 回実行して実行中の ClickHouse のバージョンを検出します。KeeperCluster では、オペレーターが実行中のレプリカからサーバーが報告するバージョンを読み取ります。検出されたバージョンは .status.version に記録され、他のリコンサイルステップで使用されます (たとえば、External Secret の named-collections キーは ClickHouse 25.12 以降でのみ必要です) 。
アップグレードチャネル — 公開されている ClickHouse のリリースフィード (https://clickhouse.com/data/version_date.tsv) を定期的に確認します。オペレーターは、新しいバージョンが利用可能かどうかを VersionUpgraded ステータス条件で報告します。クラスターを自動的にアップグレードすることはなく、イメージタグはユーザーが管理します。

リリースチャネルの選択

spec.upgradeChannel は、オペレーターが比較対象とするアップストリームのリリース群を選択します。このフィールドは ClickHouseCluster と KeeperCluster の両方にあります。

spec:
  upgradeChannel: lts   # or "stable", or "25.8", or omitted

許可される値 (CRD によりパターン ^(lts|stable|\d+\.\d+)?$ で検証) :

Value	Behavior
empty (default)	オペレーターは、現在実行中の major.minor 系列内のマイナー更新のみを提示します。`25.8.3.1` のクラスターには `25.8.4.x` が通知されますが、`25.9.x` は通知されません。
`stable`	アップストリームの `stable` チャネルを追跡します。これは、ClickHouse Inc. がメインのリリース系列で安定版として示している最新の release です。`lts` チャネルより早くメジャーアップグレードを受け取ります。
`lts`	アップストリームの `lts` チャネルを追跡します。これは長期サポートの release です。メジャーアップグレードの頻度は低く、サポート期間は長くなります。
`25.8` (or any `<major>.<minor>`)	チャネルを特定の major.minor 系列に固定します。アップストリームに新しいバージョンが存在していても、それを超えるメジャーアップグレードは提示されません。

本番環境では、通常、チャネルを明示的な <major>.<minor> (例: 25.8) に固定することが推奨されます。これにより、クラスターを意図したメジャー release 系列に固定でき、いずれかのレプリカが何らかの理由で別のメジャーへずれてしまった場合に、オペレーターが WrongReleaseChannel 警告を表示できるようになります。これは特に、イメージが人が読めるタグではなくダイジェスト (@sha256:...) で参照されている場合に重要です。デフォルトの空値は、メジャーバージョンのジャンプが問題にならない開発用クラスターであれば問題ありません。

ステータス条件

プローブとアップグレードチェックの結果は、次の 2 つの条件に反映されます。

Condition	Reason	Meaning
`VersionInSync`	`VersionMatch`	すべてのレプリカが同じバージョンを報告しています
`VersionInSync`	`VersionMismatch`	レプリカごとに異なるバージョンで稼働しています。計画されたローリングアップグレード中は、この理由は抑止されます。通常これは、可変のイメージタグ (たとえば `latest` や、`26.3` のようなメジャー番号だけのタグ) を固定しており、基盤となるレジストリの内容が pull の間に変わった結果、同じタグでも各レプリカで異なるパッチ版が使われた場合に発生します。
`VersionInSync`	`VersionPending`	バージョンプローブ Job がまだ完了していないか、Keeper レプリカのバージョンがまだ観測されていません
`VersionInSync`	`VersionProbeFailed`	ClickHouse プローブ Job が失敗したため、オペレーターは実行中のバージョンを特定できません
`VersionUpgraded`	`UpToDate`	クラスターは、選択したチャネルで利用可能な最新バージョンを実行しています
`VersionUpgraded`	`MinorUpdateAvailable`	同じ `major.minor` 系列で、より新しいパッチが利用可能です
`VersionUpgraded`	`MajorUpdateAvailable`	選択したチャネル内で、より新しい `major.minor` が利用可能です
`VersionUpgraded`	`VersionOutdated`	実行中のバージョンは古く、選択したチャネルから今後修正を受けられなくなります。通常、これはそのメジャー系列が上流の `lts` または `stable` から外されたためです
`VersionUpgraded`	`WrongReleaseChannel`	実行中のイメージは、選択した `upgradeChannel` に属していません。例: `upgradeChannel: lts` で `26.5` を実行しているクラスター。`26.5` は上流の `lts` 系列に含まれていないためです。
`VersionUpgraded`	`UpgradeCheckFailed`	オペレーターが上流のリリースフィードに到達できませんでした

次のように確認します:

kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

バージョンプローブ Job のオーバーライド

これは ClickHouseCluster にのみ適用されます。KeeperCluster では version-probe Job は実行されなくなりました。バージョンは実行中の Keeper レプリカから直接読み取られるため、spec.versionProbeTemplate は非推奨であり、KeeperCluster では効果がありません。この probe は通常の Kubernetes Job として実装されています。クラスターで、特定の Tolerations、node selector、security context を必須とする Admission ポリシーが設定されている場合や、完了後の probe Job の保持期間を制限したい場合は、spec.versionProbeTemplate でテンプレートをオーバーライドします:

spec:
  versionProbeTemplate:
    spec:
      ttlSecondsAfterFinished: 600   # delete completed probe Jobs 10 minutes after completion
      template:
        spec:
          nodeSelector:
            kubernetes.io/arch: amd64
          tolerations:
            - key: dedicated
              operator: Equal
              value: clickhouse
              effect: NoSchedule
          containers:
            - name: version-probe
              resources:
                requests:
                  cpu: 50m
                  memory: 64Mi

コンテナー名 version-probe はオペレーターのデフォルトです。containers: 配下の項目は名前でこれに一致するため、オペレーターはユーザー指定のフィールドをデフォルトに対してディープマージします。

オペレーター全体に適用される制御

オペレーターマネージャーの 2 つのフラグで、アップグレードチェックのループ全体を制御します。

フラグ	デフォルト	効果
`--version-update-interval`	`24h`	オペレーターがアップストリームのバージョン一覧を再取得する頻度
`--disable-version-update-checks`	`false`	アップグレードチェッカーを完全に無効にします。`VersionUpgraded` 条件は設定されず、`clickhouse.com` への外向きの HTTP トラフィックも発生しません

エアギャップ環境、または clickhouse.com への egress が許可されていない場合は、--disable-version-update-checks=true を設定してください。

ClickHouse の設定

`default` ユーザーのパスワード

spec.settings.defaultUserPassword は、組み込みの default ユーザーのパスワードを設定します。値は、CR に直接記述するのではなく、作成した Secret (推奨) または ConfigMap のキーから指定してください。

spec:
  settings:
    defaultUserPassword:
      passwordType: password   # default; see "Password types" below
      secret:                  # exactly one of secret or configMap
        name: clickhouse-password   # name of the Secret/ConfigMap
        key: password               # the key inside it, not the password value

secret または configMap のいずれか一方のみを指定し、どちらの場合も name (オブジェクト) と key (パスワードを保持するエントリ) の両方を指定してください。

パスワードの種類

passwordType は、値をどのように解釈するかを ClickHouse に指定します。デフォルトは password (平文) で、代わりに password_sha256_hex や password_double_sha1_hex などのハッシュ形式も使用できます。平文が保存されないよう、ハッシュ化された種類を使用することを推奨します。完全な一覧は、 ClickHouse のユーザー設定を参照してください。

Secretを使った完全な例

Secretを作成し、そのキーを参照します。

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

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  settings:
    defaultUserPassword:
      passwordType: password
      secret:
        name: clickhouse-password
        key: password

passwordType: password を使用すると、ポッド内の clickhouse-client がこのパスワードで設定されるため、デバッグに便利です。

パスワードをハッシュ化する場合は、平文ではなくハッシュ値を保存します。

echo -n 'your-secure-password' | sha256sum   # use the hex digest as the value
kubectl create secret generic clickhouse-password \
  --from-literal=password='<sha256-hex-digest>'

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      secret:
        name: clickhouse-password
        key: password

ConfigMap を使用する

ConfigMap も同じように機能しますが、その内容は Secret のように保護されません。機密性のない値、またはすでにハッシュ化されている値にのみ使用してください。たとえば、 password_sha256_hex ダイジェストです。

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

平文のパスワードを ConfigMap に入れないでください。平文の値 (passwordType: password) には、必ず Secret を使用してください。

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

設定ファイルで追加ユーザーを設定します。ユーザー用の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 テーブルとインテグレーションテーブルを新しいレプリカに同期します。

サーバーロギング

spec.settings.logger で ClickHouse server のログを設定します。すべてのフィールドは省略可能で、安全なデフォルト値が設定されているため、何も変更していないクラスターでも、コンテナーのコンソールとディスク上のローテーションされるファイルの両方に trace レベルでログが出力されます。

spec:
  settings:
    logger:
      logToFile: true   # Default: true. Set false to log only to the console
      jsonLogs: false   # Default: false. Set true for structured JSON log lines
      level: trace      # Default: trace
      size: 1000M       # Default: 1000M. Rotate a log file once it reaches this size
      count: 50         # Default: 50. Number of rotated files to keep

フィールド	既定値	説明
`logToFile`	`true`	`false` の場合、オペレーターはファイル出力先を削除し、サーバーはコンテナーのコンソールにのみログを出力します。
`jsonLogs`	`false`	`true` の場合、オペレーターは `formatting.type: json` を追加するため、各行が JSONオブジェクトになります。
`level`	`trace`	ログの詳細度です。`test`、`trace`、`debug`、`information`、`notice`、`warning`、`error`、`critical`、`fatal` のいずれかを指定します。
`size`	`1000M`	ローテーションされる前の単一ログファイルの最大サイズです。
`count`	`50`	サーバーが保持するローテーション済みログファイルの数です。

オペレーターは、kubectl logs が使えるよう、常にコンソールへのログ出力を有効にしています。logToFile が true の場合は、それに加えてファイルへのログ出力も有効にします。既定値を使用するクラスターでは、次の ロガー ブロックが生成されます。

logger:
  console: true
  level: trace
  log: /var/log/clickhouse-server/clickhouse-server.log
  errorlog: /var/log/clickhouse-server/clickhouse-server.err.log
  size: 1000M
  count: 50

同じ spec.settings.logger ブロックは KeeperCluster にも適用されます。この場合、operator はファイルを代わりに /var/log/clickhouse-keeper/ 配下へ書き込みます。

logToFile の設定にかかわらずコンソールへのログ出力は有効なままなので、ファイルロギングを無効にしても kubectl logs は引き続き利用できます。JSON を解析する構造化ログストアにログを送る場合は、jsonLogs: true を設定してください。

カスタム設定

埋め込みの追加設定

カスタムの設定ファイルをマウントする代わりに、追加の 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

最終更新日 2026年6月25日

ストレージとボリュームオペレーターが ClickHouse クラスター用の永続ストレージをどのようにプロビジョニングするかを説明します。対象には、プライマリデータボリューム、マルチディスク（JBOD）レイアウト、容量の拡張、作成後に変更できない項目が含まれます。

​ClickHouseCluster の設定

​基本設定

​レプリカと分片

​Keeper インテグレーション

​KeeperCluster の設定

​ストレージ構成

​クラスター ドメイン

​複数ディスク (JBOD) ストレージ

​クラスター ドメイン

​ポッドの設定

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

​手動設定

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

​ポッドの停止予算

​デフォルト

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

​ポリシー

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

​コンテナーの設定

​カスタムイメージ

​コンテナーのリソース

​環境変数

​ボリュームマウント

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

​TLS/SSL の設定

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

​SSL 証明書 Secret の形式

​TLS を介した ClickHouse-Keeper 通信

​External Secret

​必須のキー

​ポリシー: Observe と Manage

​ステータス条件とトラブルシューティング

​追加ポート

​エンドツーエンドの例: MySQLワイヤプロトコル

​フィールドの制約

​予約済みのポートと名前

​バージョンプローブとアップグレードチャネル

​リリースチャネルの選択

​ステータス条件

​バージョンプローブ Job のオーバーライド

​オペレーター全体に適用される制御

​ClickHouse の設定

​default ユーザーのパスワード

​パスワードの種類

​Secretを使った完全な例

​ConfigMap を使用する

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

​データベース同期

​サーバーロギング

​カスタム設定

​埋め込みの追加設定

​役立つリンク:

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

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

​設定例

ClickHouseCluster の設定

基本設定

レプリカと分片

Keeper インテグレーション

KeeperCluster の設定

ストレージ構成

クラスタードメイン

複数ディスク (JBOD) ストレージ

クラスタードメイン

ポッドの設定

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

手動設定

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

ポッドの停止予算

デフォルト

デフォルト設定の上書き

ポリシー

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

コンテナーの設定

カスタムイメージ

コンテナーのリソース

環境変数

ボリュームマウント

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

TLS/SSL の設定

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

SSL 証明書 Secret の形式

TLS を介した ClickHouse-Keeper 通信

External Secret

必須のキー

ポリシー: Observe と Manage

ステータス条件とトラブルシューティング

追加ポート

エンドツーエンドの例: MySQLワイヤプロトコル

フィールドの制約

予約済みのポートと名前

バージョンプローブとアップグレードチャネル

リリースチャネルの選択

ステータス条件

バージョンプローブ Job のオーバーライド

オペレーター全体に適用される制御

ClickHouse の設定

`default` ユーザーのパスワード

パスワードの種類

Secretを使った完全な例

ConfigMap を使用する

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

データベース同期

サーバーロギング

カスタム設定

埋め込みの追加設定

役立つリンク:

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

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

設定例