> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse Operator 設定ガイド

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

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

<div id="clickhousecluster-configuration">
  ## ClickHouseCluster の設定
</div>

<div id="basic-configuration">
  ### 基本設定
</div>

```yaml theme={null}
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
```

<div id="replicas-and-shards">
  ### レプリカと分片
</div>

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

```yaml theme={null}
spec:
  replicas: 3  # デフォルト: 3
  shards: 2    # デフォルト: 1
```

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

<div id="keeper-integration">
  ### Keeper インテグレーション
</div>

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

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

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

<div id="keepercluster-configuration">
  ## KeeperCluster の設定
</div>

```yaml theme={null}
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
```

<div id="storage-configuration">
  ## ストレージ構成
</div>

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

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

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

<div id="pod-configuration">
  ## ポッドの設定
</div>

<div id="automatic-topology-spread-and-affinity">
  ### トポロジースプレッドとアフィニティの自動設定
</div>

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

```yaml theme={null}
spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
```

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

<div id="manual-configuration">
  ### 手動設定
</div>

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

```yaml theme={null}
spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>
```

<div id="see-api-referenceproductskubernetes-operatorreferenceapi-referencepodtemplatespec-for-all-supported-pod-template-options">
  ### サポートされているすべてのポッドテンプレートオプションについては、[API リファレンス](/ja/products/kubernetes-operator/reference/api-reference#podtemplatespec)を参照してください。
</div>

<div id="pod-disruption-budgets">
  ## ポッドの停止予算
</div>

オペレーターは、各クラスターに対して [PodDisruptionBudget](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/) (PDB) を作成します。これにより、自発的な中断 (ノードのドレイン、ローリングアップグレード、オートスケーラーによるエビクション) が発生しても、クォーラムの喪失や可用性の低下につながるほど多くのポッドが停止しないようにできます。

複数の分片を持つ ClickHouse クラスターでは、**分片ごとに 1 つの PDB が作成されます**。これにより、ある分片での中断が別の分片の許容範囲として扱われることはありません。

<div id="pdb-defaults">
  ### デフォルト
</div>

オペレーターはクラスターのサイズに応じて安全なデフォルト値を選択するため、新規に `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` を設定します。

<div id="pdb-overrides">
  ### デフォルト設定の上書き
</div>

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

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

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

```yaml theme={null}
spec:
  replicas: 5
  podDisruptionBudget:
    maxUnavailable: 40%
```

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

生成される PDB に [`unhealthyPodEvictionPolicy`](https://kubernetes.io/docs/concepts/workloads/pods/disruptions/#unhealthy-pod-eviction-policy) フィールドをそのまま渡すこともできます。これは、まだ `NotReady` 状態のポッドのエビクションを許可する必要がある場合に便利です。

```yaml theme={null}
spec:
  podDisruptionBudget:
    minAvailable: 2
    unhealthyPodEvictionPolicy: AlwaysAllow
```

<div id="pdb-policies">
  ### ポリシー
</div>

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

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

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

```yaml theme={null}
spec:
  podDisruptionBudget:
    policy: Disabled
```

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

```yaml theme={null}
spec:
  podDisruptionBudget:
    policy: Ignored
```

<div id="pdb-cluster-wide-disable">
  ### クラスター全体での無効化
</div>

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

```yaml theme={null}
# operatorのデプロイメントspecに記述
env:
- name: ENABLE_PDB
  value: "false"
```

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

<div id="container-configuration">
  ## コンテナーの設定
</div>

<div id="custom-image">
  ### カスタムイメージ
</div>

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

```yaml theme={null}
spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent
```

<div id="container-resources">
  ### コンテナーのリソース
</div>

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

```yaml theme={null}
# デフォルト値
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "1Gi"
```

<div id="environment-variables">
  ### 環境変数
</div>

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

```yaml theme={null}
spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"
```

<div id="volume-mounts">
  ### ボリュームマウント
</div>

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

```yaml theme={null}
spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml
```

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

<div id="see-api-referenceproductskubernetes-operatorreferenceapi-referencecontainertemplatespec-for-all-supported-container-template-options">
  ### サポートされているすべての コンテナー テンプレートオプションについては、[API リファレンス](/ja/products/kubernetes-operator/reference/api-reference#containertemplatespec)を参照してください。
</div>

<div id="tls-ssl-configuration">
  ## TLS/SSL 設定
</div>

<div id="configure-secure-endpoints">
  ### セキュアなエンドポイントを設定する
</div>

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

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

<div id="ssl-certificate-secret-format">
  ### SSL 証明書 Secret の形式
</div>

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

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

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

<div id="clickhouse-keeper-communication-over-tls">
  ### TLS を介した ClickHouse-Keeper 通信
</div>

KeeperCluster で TLS が有効になっている場合、ClickHouseCluster は Keeper ノードへのセキュアな接続を自動的に使用します。

ClickHouseCluster は、Keeper ノードの証明書を検証できる必要があります。
ClickHouseCluster で TLS が有効になっている場合、検証には `ca.crt` バンドルが使用されます。そうでない場合は、デフォルトの CA バンドルが使用されます。

必要に応じて、カスタム CA バンドルへの参照を指定できます。

```yaml theme={null}
spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>
```

<div id="clickhouse-settings">
  ## ClickHouse の設定
</div>

<div id="default-user-password">
  ### デフォルトユーザーのパスワード
</div>

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

```yaml theme={null}
spec:
  settings:
    defaultUserPassword:
      passwordType: <password-type> # デフォルト: password
      <secret|configMap>:
        name: <resource name>
        key: <password>
```

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

Secret を作成します:

```bash theme={null}
kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'
```

<div id="using-configmap-for-user-passwords">
  #### ユーザーパスワードに ConfigMap を使用する
</div>

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

```yaml theme={null}
spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password
```

<div id="custom-users-in-configuration">
  ### 設定でのカスタムユーザー
</div>

設定ファイルで追加ユーザーを設定します。

ユーザー用のConfigMapとSecretを作成します。

```yaml theme={null}
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 にカスタム設定を追加します:

```yaml theme={null}
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
```

<div id="database-sync">
  ### データベース同期
</div>

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

```yaml theme={null}
spec:
  settings:
    enableDatabaseSync: true  # デフォルト: true
```

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

<div id="custom-configuration">
  ## カスタム設定
</div>

<div id="embedded-extra-configuration">
  ### 埋め込みの追加設定
</div>

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

`extraConfig` を使用して、カスタムの ClickHouse 設定を追加します。

```yaml theme={null}
spec:
  settings:
    extraConfig:
      background_pool_size: 20
```

<div id="useful-links">
  #### 役立つリンク:
</div>

* [YAML 設定例](/ja/concepts/features/configuration/server-config/configuration-files#example-1)
* [すべてのサーバー設定](/ja/reference/settings/server-settings/settings)

<div id="embedded-extra-users-configuration">
  ### 埋め込み追加ユーザー設定
</div>

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

```yaml theme={null}
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
```

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

<div id="see-documentationconceptsfeaturesconfigurationsettingssettings-users-for-all-supported-clickhouse-users-configuration-options">
  #### サポートされているすべての ClickHouse ユーザー設定オプションについては、[ドキュメント](/ja/concepts/features/configuration/settings/settings-users)を参照してください。
</div>

<div id="configuration-example">
  ### 設定例
</div>

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

```yaml theme={null}
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
```