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

ClickHouse Operator 設定ガイド

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

ClickHouseCluster の設定​

基本設定​

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # Number of replicas per shard
  shards: 2             # Number of shards
  keeperClusterRef:
    name: my-keeper     # Reference to KeeperCluster
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 10Gi

レプリカと分片​

  • レプリカ: 各分片あたりの ClickHouse インスタンス数（高可用性のため）
  • 分片: 水平方向のパーティション数（スケールアウトのため）
spec:
  replicas: 3  # Default: 3
  shards: 2    # Default: 1

replicas: 3 と shards: 2 に設定されたクラスタでは、合計 6 個の ClickHouse ポッドが作成されます。

Keeper 統合​

すべての ClickHouse クラスターは、コーディネーションのために KeeperCluster を参照する必要があります。

spec:
  keeperClusterRef:
    name: my-keeper  # Name of the KeeperCluster in the same namespace

KeeperCluster の構成​

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # Must be odd: 1, 3, 5, 7, 9, 11, 13, or 15
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 5Gi

ストレージ設定​

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

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

ClickHouse Operator は、基盤となる StorageClass がボリューム拡張をサポートしている場合にのみ、既存の 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>

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

コンテナ構成​

カスタムイメージ​

特定の ClickHouse イメージを使用する:

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

コンテナーリソース​

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

# default values
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 Reference を参照してください。​

TLS/SSL 構成​

セキュアなエンドポイントを構成する​

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

spec:
  settings:
    tls:
      enabled: true
      required: true # Insecure ports are disabled if set
      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> # Default: 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  # Default: 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>
    accessModes:
      - ReadWriteOnce
    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:
  # secret-password
  password: "..." # sha256 hex of the password
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    accessModes:
      - ReadWriteOnce
    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