> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# ストレージとボリューム
> オペレーターが ClickHouse クラスター用の永続ストレージをどのようにプロビジョニングするかを説明します。対象には、プライマリデータボリューム、マルチディスク（JBOD）レイアウト、容量の拡張、作成後に変更できない項目が含まれます。
このガイドでは、オペレーターが `ClickHouseCluster` の永続ストレージを
どのようにプロビジョニングするかを説明します。対象には、プライマリデータボリューム、
マルチディスク (JBOD) レイアウトへの追加ディスクの接続、容量の拡張、
そしてクラスター作成後に変更できる項目と変更できない項目に関するルールが
含まれます。
各フィールドのリファレンスについては、
[Configuration → ストレージ構成](/docs/ja/products/kubernetes-operator/guides/configuration#storage-configuration)
および [API リファレンス](/docs/ja/products/kubernetes-operator/reference/api-reference) を参照してください。
## プライマリ データボリューム
`spec.dataVolumeClaimSpec` は、標準の Kubernetes `PersistentVolumeClaimSpec` です。
オペレーターはこれを StatefulSet の `volumeClaimTemplate` に変換するため、StatefulSet
コントローラーはレプリカごとに 1 つの PersistentVolumeClaim を作成して保持し、これを
ClickHouse のデータパス `/var/lib/clickhouse` にマウントします。
```yaml theme={null}
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
name: my-cluster
spec:
dataVolumeClaimSpec:
storageClassName: fast-ssd # optional; depends on the installed CSI driver
resources:
requests:
storage: 100Gi
```
* `accessModes` を省略した場合、オペレーター はデフォルトで `ReadWriteOnce` を使用します。
* クラスターが削除されてもレプリカごとの PVC は保持されるため、Custom Resource を
削除して再作成してもデータは維持されます。[暗号化ポリシー](#at-rest-encryption) 上の
データについては、これに加えて暗号化鍵を保持する必要があります。該当セクションの注記を
参照してください。
* 同じフィールドが `KeeperCluster` にもあり、同様に動作します。
## 永続データボリュームを使わずに実行する
`dataVolumeClaimSpec` は省略可能です。これを省略し、かつデータパスに独自のボリュームをマウントしない場合、
ClickHouse はコンテナーの一時的なファイルシステムに書き込みます。また、クラスターが再起動されると
データが失われる可能性があるという警告を admission webhook が返します。
これは、一時的な用途やテスト用のクラスターでのみ使用することを想定しています。`dataVolumeClaimSpec` の代わりに
独自のストレージ (たとえば `emptyDir` や事前にプロビジョニングされた
ボリューム) を使用するには、`spec.podTemplate.volumes` で定義し、
`spec.containerTemplate.volumeMounts` で `/var/lib/clickhouse` にマウントします。
`dataVolumeClaimSpec` と、データパス上のカスタムボリュームは相互排他的です。
`dataVolumeClaimSpec` が設定されている場合、`/var/lib/clickhouse` へのカスタムボリュームのマウントは
拒否されます。予約済みのボリューム名 `clickhouse-storage-volume`、
`clickhouse-server-tls-volume`、`clickhouse-server-custom-ca-volume` は、
`podTemplate.volumes` では使用できません。
## ストレージの拡張
ボリュームを拡張するには、`resources.requests.storage` を増やして変更を適用します。オペレーターが既存の PVC をその場で更新します。
```yaml theme={null}
spec:
dataVolumeClaimSpec:
resources:
requests:
storage: 200Gi # was 100Gi
```
拡張は、使用している StorageClass で
`allowVolumeExpansion: true` が設定されている場合にのみ可能です。Kubernetes は PVC の縮小をサポートしていないため、
新しいサイズは現在のサイズ以上である必要があります。
## マルチディスク (JBOD) ストレージ
`spec.additionalVolumeClaimTemplates` は、プライマリの `dataVolumeClaimSpec` に加えて、各 ClickHouse
レプリカに追加のディスクを割り当てます。各エントリは、`metadata.name` と PVC の `spec` で構成される名前付きの PVC
テンプレートで、プライマリ データディスクとまったく同じようにリコンサイルされるため、StatefulSet コントローラーは
レプリカごとに `--0` という名前の PVC を 1 つ作成して保持します。
```yaml theme={null}
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/` にマウントし、
**ClickHouse の `storage_configuration` を自動生成します**。これを手動で
記述する必要はありません。各追加ディスクを登録し、組み込みの `default`
ストレージポリシーに追加します。
プライマリデータディスク (`default`) と各追加ディスクは、`default` ポリシー内の
単一ボリュームを共有するため、ClickHouse は新しいデータパーツをそれら全体に
ラウンドロビン方式で分散します。使用可能容量はすべてのディスクの合計となり、
独自の `storage_policy` を設定していないすべてのテーブル (`system.*` テーブルを
含む) は、この統合されたセットを使用します。
マウントパスではテンプレート名がそのまま使われますが、`storage_configuration` 内のディスク名では
ハイフンがアンダースコアに置き換えられます。`cold-disk` という名前のテンプレートは
`/var/lib/clickhouse/disks/cold-disk` にマウントされ、生成された構成では
`cold_disk` として表示されます。
## カスタムストレージポリシー
上記の JBOD レイアウトでは、`extraConfig` は**不要**です。オペレーターが
`default` ポリシーを自動的に生成します。`spec.settings.extraConfig` を使うのは、
自動生成されるデフォルト以外のストレージポリシーが必要な場合だけです。たとえば、
`move_factor` と `prefer_not_to_merge` を使った階層型のホット/コールドポリシーや、
S3 をバックエンドにしたディスクなどです。ここに追加した設定は、生成された
`storage_configuration` に追加でマージされます。
ポリシーのフィールドについては、
[ClickHouse storage documentation](https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-multiple-volumes)
を参照してください。
## 保存時暗号化
`spec.settings.encryption` を設定すると、table データの保存時暗号化が有効になります。
オペレーター は 16 バイトの AES 秘密鍵 (Managed クラスターの Secret に保存されるか、
`externalSecret` を通じて指定) と、各
data ディスクを ClickHouse の `encrypted` disk type で包む専用の storage policy を生成します。
```yaml theme={null}
spec:
settings:
encryption: {} # enables the feature; the policy defaults to "encrypted"
```
暗号化はテーブル単位で有効化するオプトイン方式です。デフォルトのストレージポリシーは平文のままです。テーブル作成時に
暗号化ポリシーを選択します。
```sql theme={null}
CREATE TABLE secret_data (id UInt64) ENGINE = MergeTree ORDER BY id
SETTINGS storage_policy = 'encrypted';
```
`encryption.policyName` を設定して、別のポリシー名を使用します。
これにより、暗号化ポリシー経由で書き込まれる MergeTree のデータパーツは
AES-128-CTR で暗号化されます。ClickHouse server のメタデータと
データルート上のログは対象に含まれません —
それらについては、LUKS や CSI ドライバーなどのディスクレベル暗号化を使用してください。
実行中のクラスターで暗号化を有効にすると、秘密鍵を注入するために
一回限りのローリング再起動がトリガーされます。レプリカでは、その再起動が完了するまで
一時的に設定の再読み込みエラーが報告されることがあります。
秘密鍵は オペレーター が管理するクラスター Secret に保存され、この Secret は
Custom Resource によって所有され、Custom Resource の削除時に一緒に削除されます。暗号化されたパーツは
秘密鍵がなければ読み取れません。暗号化データを CR の削除後も保持する必要がある場合
(PVC は保持されます) は、`externalSecret` を通じて秘密鍵を提供するか、
削除前に `disk-encryption-key` エントリをバックアップしてください。
管理対象の Secret は削除しないでください — オペレーター が新しい秘密鍵を生成し、
既存の暗号化パーツが読み取れなくなります。
## 作成後に変更できない項目
クラスターが作成されると、ストレージレイアウトは基本的に固定されます。データが孤立したり PersistentVolumeClaims が再バインドされたりする更新は、admission の段階で拒否されます。
* `dataVolumeClaimSpec` の有無は変更できません。つまり、これを持たない状態で作成したクラスターにデータ
ボリュームを**追加**したり、これを持つ状態で作成したクラスターから**削除**したりすることはできません。
* `additionalVolumeClaimTemplates` のセットは固定です。作成後にエントリを**追加**、
**削除**、または**リネーム**することはできません。
* 既存のエントリの `resources.requests.storage` を拡張することは**可能**です (StorageClass がサポート
している場合。[ストレージの拡張](#expanding-storage)を参照してください) 。
* 暗号化は一度有効にすると**無効化**できず、`encryption.policyName` も**リネーム**できません。すでに暗号化ポリシーを使用している
テーブルにアクセスできなくなるためです。
## 検証リファレンス
| 条件 | 結果 |
| --------------------------------------------------------------------------- | ---------------------------------------------- |
| `dataVolumeClaimSpec` がなく、`/var/lib/clickhouse` にカスタムボリュームもマウントされていない | 警告 — 再起動時にデータが失われる可能性があります |
| `dataVolumeClaimSpec` が設定されているのに、`/var/lib/clickhouse` にカスタムボリュームがマウントされている | 拒否 |
| `additionalVolumeClaimTemplates` が設定されているが、`dataVolumeClaimSpec` がない | 拒否 |
| `default` という名前の追加ディスク | 拒否 — ClickHouse のデフォルトディスク用に予約されています |
| 名前の末尾が `-encrypted` の追加ディスク | 拒否 — 生成される暗号化ディスク名と競合します |
| `clickhouse-storage-volume` という名前の追加ディスク | 拒否 — プライマリデータボリューム名と競合します |
| 追加ディスク名が重複している | 拒否 |
| 名前が `^[a-z]([-a-z0-9]*[a-z0-9])?$` に一致しない、または 63 文字を超えている | CRD スキーマによって拒否 |
| 作成後に `dataVolumeClaimSpec` を追加または削除する | 拒否 |
| 作成後に `additionalVolumeClaimTemplates` を追加、削除、または名前変更する | 拒否 |
| `podTemplate.volumes` に予約済みのボリューム名がある | 拒否 |
| `encryption.policyName` が `default` に設定されている | CRD スキーマによって拒否 — 暗号化ポリシーでデフォルトポリシーを置き換えてはなりません |
| 作成後に `encryption` を無効化する、またはそのポリシー名を変更する | CRD スキーマによって拒否 |
## 関連ガイド
* [設定](/docs/ja/products/kubernetes-operator/guides/configuration) — `extraConfig` を含む、全フィールドのリファレンス。
* [クラスターのスケーリング](/docs/ja/products/kubernetes-operator/guides/scaling) — レプリカと分片の追加・削除の方法。