ClickHouse Operator API リファレンス

このドキュメントでは、ClickHouse Operator のカスタムリソース用の詳細な API リファレンスを提供します。

ClickHouseCluster

ClickHouseCluster は、ClickHouse クラスター API のスキーマです。

API バージョンと Kind

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster

ClickHouseClusterSpec

ClickHouseClusterSpec は、ClickHouse クラスターの望ましい状態を定義します。

Field	Type	Required	Default	Description
`replicas`	`*int32`	No	`3`	単一の分片内のレプリカ数。0 以上である必要があります。
`shards`	`*int32`	No	`1`	クラスター内の分片数。0 以上である必要があります。
`keeperClusterRef`	`LocalObjectReference`	Yes	-	調整に使用される KeeperCluster への参照。
`podTemplate`	`PodTemplateSpec`	No	-	Pod Spec のパラメーター。
`containerTemplate`	`ContainerTemplateSpec`	No	See defaults	ClickHouse コンテナー Spec のパラメーター。
`dataVolumeClaimSpec`	`PersistentVolumeClaimSpec`	Yes	-	データボリューム用のストレージ構成。
`labels`	`map[string]string`	No	-	すべてのリソースに付与されるラベル。
`annotations`	`map[string]string`	No	-	すべてのリソースに付与されるアノテーション。
`settings`	`ClickHouseConfig`	No	-	ClickHouse の構成パラメーター。

例

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: example-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: example-keeper
  dataVolumeClaimSpec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 100Gi
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    resources:
      requests:
        cpu: "2"
        memory: "8Gi"
      limits:
        cpu: "4"
        memory: "16Gi"
  settings:
    defaultUserPassword:
      secret:
        name: clickhouse-password
        key: password
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert

ClickHouseConfig

ClickHouse の構成パラメータ。

Field	Type	Required	Default	Description
`defaultUserPassword`	`*DefaultPasswordSelector`	No	-	Secret または ConfigMap から取得する `default` ユーザーのパスワード。
`logger`	`LoggerConfig`	No	See defaults	ロガーの構成。
`tls`	`ClusterTLSSpec`	No	-	ClickHouse 用の TLS 設定。
`enableDatabaseSync`	`bool`	No	`true`	データベースを新しいレプリカに同期するかどうかを有効化する。
`extraConfig`	`runtime.RawExtension`	No	-	追加の ClickHouse 構成（デフォルト構成とマージされる）。
`extraUsersConfig`	`runtime.RawExtension`	No	-	追加の ClickHouse ユーザー構成（デフォルト構成とマージされる）。

ClickHouseClusterStatus

ClickHouseClusterStatus は、ClickHouse クラスターの観測された状態を定義します。

Field	Type	Description
`conditions`	`[]metav1.Condition`	クラスターの現在の Condition 一覧。
`observedGeneration`	`int64`	直近で観測された generation。
`replicas`	`int32`	現在稼働中のレプリカ数。
`readyReplicas`	`int32`	Ready 状態のレプリカ数。
`configurationRevision`	`string`	Operator によって適用されたターゲット設定リビジョン。
`statefulSetRevision`	`string`	対象となる StatefulSet コントローラーのリビジョン。
`currentRevision`	`string`	最後に適用されたクラスター spec のリビジョン。
`updateRevision`	`string`	最後に要求されたクラスター spec のリビジョン。

KeeperCluster

KeeperCluster は、ClickHouse Keeper クラスター API 用のスキーマです。

API バージョンとKind

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster

KeeperClusterSpec

KeeperClusterSpec は、Keeper クラスターの望ましい状態を定義します。

Field	Type	Required	Default	Description
`replicas`	`*int32`	No	`3`	レプリカ数。必ず奇数である必要があります。0、1、3、5、7、9、11、13、15 のいずれかです。
`podTemplate`	`PodTemplateSpec`	No	-	ポッドの Spec に対するパラメータ。
`containerTemplate`	`ContainerTemplateSpec`	No	See defaults	Keeper コンテナの Spec に対するパラメータ。
`dataVolumeClaimSpec`	`PersistentVolumeClaimSpec`	Yes	-	データボリューム用のストレージ構成。
`labels`	`map[string]string`	No	-	すべてのリソースに付与される追加ラベル。
`annotations`	`map[string]string`	No	-	すべてのリソースに付与される追加アノテーション。
`settings`	`KeeperConfig`	No	-	Keeper の設定パラメータ。

例

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: example-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 10Gi
  containerTemplate:
    resources:
      requests:
        cpu: "500m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "1Gi"
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: keeper-cert

KeeperConfig

Keeper の設定パラメータ。

Field	Type	Required	Default	Description
`logger`	`LoggerConfig`	No	See defaults	ロガー設定。
`tls`	`ClusterTLSSpec`	No	-	Keeper 用の TLS 設定。
`extraConfig`	`runtime.RawExtension`	No	-	デフォルト設定とマージされる追加の Keeper 設定。

KeeperClusterStatus

KeeperClusterStatus は、Keeper クラスターの観測された状態を定義します。

Field	Type	Description
`conditions`	`[]metav1.Condition`	クラスターの現在の Condition。
`observedGeneration`	`int64`	直近で観測された generation。
`replicas`	`int32`	現在実行中のレプリカの数。
`readyReplicas`	`int32`	Ready 状態のレプリカの数。
`configurationRevision`	`string`	オペレーターによって適用された対象の構成リビジョン。
`statefulSetRevision`	`string`	対象となる StatefulSet コントローラーのリビジョン。
`currentRevision`	`string`	最後に適用されたクラスター spec のリビジョン。
`updateRevision`	`string`	最後に要求されたクラスター spec のリビジョン。

共通型

PodTemplateSpec

ポッドを設定するためのパラメーター。

Field	Type	Required	Description
`topologyZoneKey`	`string`	No	ゾーン分散のための Kubernetes トポロジーキー（例: `topology.kubernetes.io/zone`）。
`nodeHostnameKey`	`string`	No	ノードのホスト名用の Kubernetes ラベルキー（例: `kubernetes.io/hostname`）。
`nodeSelector`	`map[string]string`	No	ポッド配置用のノードセレクター。
`affinity`	`corev1.Affinity`	No	ポッドの affinity/anti-affinity ルール。
`tolerations`	`[]corev1.Toleration`	No	テイントされたノードに対するトレランス（toleration）の設定。
`securityContext`	`*corev1.PodSecurityContext`	No	ポッドのセキュリティコンテキスト。

例

podTemplate:
  topologyZoneKey: topology.kubernetes.io/zone
  nodeHostnameKey: kubernetes.io/hostname
  nodeSelector:
    disktype: ssd
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "clickhouse"
    effect: "NoSchedule"
  affinity:
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: clickhouse
        topologyKey: kubernetes.io/hostname

ContainerTemplateSpec

コンテナ設定用のパラメーター。

Field	Type	Required	Description
`image`	`ContainerImage`	No	コンテナイメージの設定。
`imagePullPolicy`	`corev1.PullPolicy`	No	イメージのプルポリシー (Always, IfNotPresent, Never)。
`resources`	`corev1.ResourceRequirements`	No	CPU およびメモリのリソース要求。
`env`	`[]corev1.EnvVar`	No	環境変数。
`volumeMounts`	`[]corev1.VolumeMount`	No	追加のボリュームマウント。
`securityContext`	`*corev1.SecurityContext`	No	コンテナのセキュリティコンテキスト。

例

containerTemplate:
  image:
    repository: clickhouse/clickhouse-server
    tag: "25.12"
  imagePullPolicy: IfNotPresent
  resources:
    requests:
      cpu: "2"
      memory: "8Gi"
    limits:
      cpu: "4"
      memory: "16Gi"
  env:
  - name: TZ
    value: "UTC"

ContainerImage

コンテナイメージ仕様。

Field	Type	Required	Default	Description
`repository`	`string`	No	ClickHouse: `clickhouse/clickhouse-server` Keeper: `clickhouse/clickhouse-keeper`	コンテナイメージのリポジトリ。
`tag`	`string`	No	`latest`	イメージタグ。

ClusterTLSSpec

クラスターの TLS 構成。

Field	Type	Required	Description
`enabled`	`bool`	No	TLS を有効にします。
`required`	`bool`	No	すべての接続に TLS を必須にします（非セキュアなエンドポイントを無効化）。
`serverCertSecret`	`corev1.LocalObjectReference`	No	サーバー証明書（tls.crt, tls.key）を含む Secret。
`caBundle`	`*SecretKeySelector`	No	検証用の CA バンドルを含む Secret。

例

tls:
  enabled: true
  required: true
  serverCertSecret:
    name: clickhouse-cert
  caBundle:
    secretKeyRef:
      name: ca-cert-secret
      key: ca.crt

LoggerConfig

ClickHouse および Keeper のロギング設定。

Field	Type	Required	Default	Description
`logToFile`	`bool`	No	`true`	ログをファイルに書き込みます。
`level`	`string`	No	`"trace"`	ログレベル。trace、debug、information、warning、error を指定します。
`size`	`string`	No	`"1000M"`	ログファイルサイズの上限。
`count`	`int`	No	`50`	保持するログファイル数。

例

logger:
  logToFile: true
  level: "information"
  size: "1000M"
  count: 50

DefaultPasswordSelector

パスワードを格納した Secret または ConfigMap のキーを参照します。

Field	Type	Required	Default	Description
`passwordType`	`string`	No	`plaintext`	パスワードのエンコード方式。指定可能な値: `plaintext`, `sha256_password`, `sha256_hash`, `double_sha1_password`, `double_sha1_hash`。詳細は ClickHouse documentation を参照してください。
`secret`	`*SecretKeySelector`	No	-	Secret のキーからパスワードを選択します。`configMap` と同時には指定できません。
`configMap`	`*ConfigMapKeySelector`	No	-	ConfigMap のキーからパスワードを選択します。`secret` と同時には指定できません。

注記

secret と configMap のいずれか一方を指定する必要があり、両方を同時に指定することはできません。

Secret を使った例（推奨）

defaultUserPassword:
  passwordType: plaintext  # Optional, default
  secret:
    name: clickhouse-password
    key: password

SHA256 を使用した例

defaultUserPassword:
  passwordType: sha256_password
  secret:
    name: clickhouse-password
    key: password_hash

ConfigMap を使用した例

defaultUserPassword:
  passwordType: plaintext
  configMap:
    name: clickhouse-config
    key: default_password

デフォルト値

ClickHouse のデフォルト設定

設定	デフォルト値
レプリカ数	`3`
分片数	`1`
イメージリポジトリ	`clickhouse/clickhouse-server`
イメージタグ	`latest`
イメージのPullポリシー	`IfNotPresent`
CPU リクエスト	`2`
CPU 制限	`4`
メモリリクエスト	`4Gi`
メモリ制限	`8Gi`
ロガーレベル	`trace`
ログをファイルに出力	`true`
ロガーサイズ	`1000M`
ロガー数	`50`
データベース同期を有効化	`true`

Keeper のデフォルト

設定項目	デフォルト値
レプリカ	`3`
イメージリポジトリ	`clickhouse/clickhouse-keeper`
イメージタグ	`latest`
イメージのPullポリシー	`IfNotPresent`
CPU 要求	`500m`
CPU 制限	`1`
メモリ要求	`512Mi`
メモリ制限	`1Gi`
ログレベル	`trace`
ファイルへのログ出力	`true`
ログサイズ	`1000M`
ログファイル数	`50`

条件

ClickHouseCluster の条件

Type	Description
`SpecValid`	ClickHouseCluster CustomResource が検証に合格しているかどうか。Webhook を使用しないデプロイメントで有用です
`ReconcileSucceeded`	直近のリコンシリエーションサイクルが成功したかどうか
`ReplicaStartupSucceeded`	ClickHouseCluster のすべてのレプリカが起動可能かどうか
`Healthy`	要求されたすべてのレプリカの Readiness
`ClusterSizeAligned`	クラスターが要求されたレプリカ／分片の数と一致している状態
`ConfigurationInSync`	設定のデプロイ状態を表します
`Ready`	ClickHouseCluster がクライアント要求を処理可能な状態。各分片で少なくとも 1 つのレプリカが Ready 状態です
`SchemaInSync`	スケーリング操作完了後、すべてのレプリカが同一のデータベーススキーマを保持している状態

KeeperCluster conditions

Type	Description
`SpecValid`	KeeperCluster CustomResource が検証に合格しているかどうか。webhook を使用しないデプロイメントで有用です。
`ReconcileSucceeded`	直近の Reconcile サイクルが成功したかどうか。
`ReplicaStartupSucceeded`	KeeperCluster のすべてのレプリカが起動可能かどうか。
`Healthy`	要求されたすべてのレプリカの Readiness 状態。
`ClusterSizeAligned`	クラスターが要求された数と同じ数のレプリカを持っているかどうか。
`ConfigurationInSync`	Configuration のデプロイメント状態を表します。
`Ready`	KeeperCluster がクライアントリクエストを処理する準備ができている状態。リーダー選出済み。

ClickHouseCluster​

API バージョンと Kind​

ClickHouseClusterSpec​

例​

ClickHouseConfig​

ClickHouseClusterStatus​

KeeperCluster​

API バージョンとKind​

KeeperClusterSpec​

例​

KeeperConfig​

KeeperClusterStatus​

共通型​

PodTemplateSpec​

例​

ContainerTemplateSpec​

例​

ContainerImage​

ClusterTLSSpec​

例​

LoggerConfig​

例​

DefaultPasswordSelector​

Secret を使った例（推奨）​

SHA256 を使用した例​

ConfigMap を使用した例​

デフォルト値​

ClickHouse のデフォルト設定​

Keeper のデフォルト​

条件​

ClickHouseCluster の条件​

KeeperCluster conditions​