ストレージとボリューム - 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 を参照してください。

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

クラスターが作成されると、ストレージレイアウトは基本的に固定されます。admission webhook は、 PersistentVolumeClaims が孤立したり再バインドされたりする更新を拒否します。

dataVolumeClaimSpec の有無は変更できません。つまり、これを持たない状態で作成したクラスターにデータボリュームを追加したり、これを持つ状態で作成したクラスターから削除したりすることはできません。
additionalVolumeClaimTemplates のセットは固定です。作成後にエントリを追加、削除、またはリネームすることはできません。
既存のエントリの resources.requests.storage を拡張することは可能です (StorageClass がサポートしている場合。ストレージの拡張を参照してください) 。

検証リファレンス

条件	結果
`dataVolumeClaimSpec` がなく、`/var/lib/clickhouse` にカスタムボリュームもマウントされていない	警告 — 再起動時にデータが失われる可能性があります
`dataVolumeClaimSpec` が設定されているのに、`/var/lib/clickhouse` にカスタムボリュームがマウントされている	拒否
`additionalVolumeClaimTemplates` が設定されているが、`dataVolumeClaimSpec` がない	拒否
`default` という名前の追加ディスク	拒否 — ClickHouse のデフォルトディスク用に予約されています
`clickhouse-storage-volume` という名前の追加ディスク	拒否 — プライマリデータボリューム名と競合します
追加ディスク名が重複している	拒否
名前が `^[a-z]([-a-z0-9]*[a-z0-9])?$` に一致しない、または 63 文字を超えている	CRD スキーマによって拒否
作成後に `dataVolumeClaimSpec` を追加または削除する	拒否
作成後に `additionalVolumeClaimTemplates` を追加、削除、または名前変更する	拒否
`podTemplate.volumes` に予約済みのボリューム名がある	拒否

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

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

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

​ストレージの拡張

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

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

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

​検証リファレンス

​関連ガイド

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

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

ストレージの拡張

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

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

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

検証リファレンス

関連ガイド