ストレージとボリューム - ClickHouse Documentation

このガイドでは、オペレーターが ClickHouseCluster の永続ストレージをどのようにプロビジョニングするかを説明します。対象には、プライマリデータボリューム、マルチディスク (JBOD) レイアウトへの追加ディスクの接続、容量の拡張、そしてクラスター作成後に変更できる項目と変更できない項目に関するルールが含まれます。各フィールドのリファレンスについては、 Configuration → ストレージ構成および API リファレンスを参照してください。

プライマリデータボリューム

spec.dataVolumeClaimSpec は、標準の Kubernetes PersistentVolumeClaimSpec です。オペレーターはこれを StatefulSet の volumeClaimTemplate に変換するため、StatefulSet コントローラーはレプリカごとに 1 つの PersistentVolumeClaim を作成して保持し、これを ClickHouse のデータパス /var/lib/clickhouse にマウントします。

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 を削除して再作成してもデータは維持されます。暗号化ポリシー上のデータについては、これに加えて暗号化鍵を保持する必要があります。該当セクションの注記を参照してください。
同じフィールドが 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 をその場で更新します。

spec:
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 200Gi   # was 100Gi

拡張は、使用している StorageClass で allowVolumeExpansion: true が設定されている場合にのみ可能です。Kubernetes は PVC の縮小をサポートしていないため、新しいサイズは現在のサイズ以上である必要があります。

マルチディスク (JBOD) ストレージ

spec.additionalVolumeClaimTemplates は、プライマリの dataVolumeClaimSpec に加えて、各 ClickHouse レプリカに追加のディスクを割り当てます。各エントリは、metadata.name と PVC の spec で構成される名前付きの PVC テンプレートで、プライマリデータディスクとまったく同じようにリコンサイルされるため、StatefulSet コントローラーはレプリカごとに <name>-<statefulset>-0 という名前の PVC を 1 つ作成して保持します。

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 の 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 を参照してください。

保存時暗号化

spec.settings.encryption を設定すると、table データの保存時暗号化が有効になります。オペレーターは 16 バイトの AES 秘密鍵 (Managed クラスターの Secret に保存されるか、 externalSecret を通じて指定) と、各 data ディスクを ClickHouse の encrypted disk type で包む専用の storage policy を生成します。

spec:
  settings:
    encryption: {}   # enables the feature; the policy defaults to "encrypted"

暗号化はテーブル単位で有効化するオプトイン方式です。デフォルトのストレージポリシーは平文のままです。テーブル作成時に暗号化ポリシーを選択します。

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 がサポートしている場合。ストレージの拡張を参照してください) 。
暗号化は一度有効にすると無効化できず、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 スキーマによって拒否

設定 — extraConfig を含む、全フィールドのリファレンス。
クラスターのスケーリング — レプリカと分片の追加・削除の方法。

​プライマリ データボリューム

​永続データボリュームを使わずに実行する

​ストレージの拡張

​マルチディスク (JBOD) ストレージ

​カスタムストレージポリシー

​保存時暗号化

​作成後に変更できない項目

​検証リファレンス

​関連ガイド

プライマリデータボリューム

永続データボリュームを使わずに実行する

ストレージの拡張

マルチディスク (JBOD) ストレージ

カスタムストレージポリシー

保存時暗号化

作成後に変更できない項目

検証リファレンス

関連ガイド