Stockage et volumes

Ce guide explique comment l’opérateur provisionne le stockage persistant pour un ClickHouseCluster : le volume de données principal, l’ajout de disques supplémentaires dans une configuration multi-disques (JBOD), l’extension de capacité et les règles qui définissent ce que vous pouvez ou non modifier une fois le cluster créé. Pour une référence détaillée champ par champ, consultez Configuration → Configuration du stockage et la Référence de l’API.

Volume de données principal

spec.dataVolumeClaimSpec est un PersistentVolumeClaimSpec Kubernetes standard. L’opérateur le convertit en volumeClaimTemplate de StatefulSet, de sorte que le contrôleur StatefulSet crée et conserve un PersistentVolumeClaim par réplique et le monte dans le chemin de données 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

Lorsque accessModes est omis, l’opérateur le définit par défaut sur ReadWriteOnce.
Le PVC de chaque réplique est conservé lorsque le cluster est supprimé, de sorte que les données sont préservées après la suppression puis la recréation de la ressource personnalisée. Pour les données relevant d’une politique chiffrée, cela nécessite en outre de préserver la clé de chiffrement — voir la note dans cette section.
Le même champ existe sur KeeperCluster et se comporte de la même façon.

Exécution sans volume de données persistant

dataVolumeClaimSpec est facultatif. Si vous l’omettez et ne montez pas votre propre volume sur le chemin de données, ClickHouse écrit dans le système de fichiers éphémère du conteneur, et le webhook d’admission renvoie un avertissement indiquant que les données risquent d’être perdues si le cluster redémarre. Cette configuration est uniquement prévue pour les clusters de test ou jetables. Pour fournir votre propre stockage à la place de dataVolumeClaimSpec — par exemple un emptyDir ou un volume préprovisionné — définissez-le via spec.podTemplate.volumes et montez-le sur /var/lib/clickhouse avec spec.containerTemplate.volumeMounts.

dataVolumeClaimSpec et un volume personnalisé sur le chemin de données sont mutuellement exclusifs. Si dataVolumeClaimSpec est défini, le montage d’un volume personnalisé sur /var/lib/clickhouse est rejeté. Les noms de volumes réservés clickhouse-storage-volume, clickhouse-server-tls-volume et clickhouse-server-custom-ca-volume ne peuvent pas être utilisés dans podTemplate.volumes.

Extension du stockage

Pour agrandir un volume, augmentez resources.requests.storage et appliquez la modification. L’opérateur met à jour les PVC existants directement.

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

L’extension ne fonctionne que si le StorageClass sous-jacent utilise allowVolumeExpansion: true. Kubernetes ne prend pas en charge la réduction d’un PVC. La nouvelle taille doit donc être supérieure ou égale à la taille actuelle.

Stockage multi-disques (JBOD)

spec.additionalVolumeClaimTemplates ajoute des disques supplémentaires à chaque réplique ClickHouse, en complément du dataVolumeClaimSpec principal. Chaque entrée est un modèle de PVC nommé — un metadata.name plus une spec de PVC — reconcilié exactement comme le disque de données principal, de sorte que le contrôleur StatefulSet crée et conserve un PVC par réplique nommé <name>-<statefulset>-0.

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

L’opérateur monte chaque volume supplémentaire dans /var/lib/clickhouse/disks/<name> et génère la storage_configuration de ClickHouse pour vous — vous n’avez pas à la rédiger manuellement. Il enregistre chaque disque supplémentaire et l’ajoute à la politique de stockage default intégrée. Le disque de données principal (default) et chaque disque supplémentaire partagent un même volume de la politique default, de sorte que ClickHouse répartit les nouvelles data parts entre eux selon un mécanisme de round-robin. La capacité utilisable est la somme de tous les disques, et chaque table qui ne définit pas sa propre storage_policy — y compris les tables system.* — utilise cet ensemble combiné.

Le chemin de montage conserve le nom du modèle tel quel, mais l’identifiant du disque dans storage_configuration remplace les traits d’union par des underscores. Un modèle nommé cold-disk est monté dans /var/lib/clickhouse/disks/cold-disk et apparaît sous la forme cold_disk dans la configuration générée.

Politiques de stockage personnalisées

Vous n’avez pas besoin de extraConfig pour la configuration JBOD ci-dessus — l’opérateur génère automatiquement la politique default. N’utilisez spec.settings.extraConfig que si vous avez besoin de politiques de stockage en plus de celle générée par défaut, par exemple une politique hot/cold à plusieurs niveaux avec move_factor et prefer_not_to_merge, ou un disque basé sur S3. La configuration que vous y ajoutez est fusionnée par-dessus la storage_configuration générée. Consultez la documentation de stockage ClickHouse pour les champs de la politique.

Chiffrement au repos

Le paramètre spec.settings.encryption active le chiffrement au repos des données des tables. L’opérateur génère une clé AES de 16 octets — stockée dans le Secret du cluster géré, ou fournie via externalSecret — ainsi qu’une politique de stockage dédiée qui enveloppe chaque disque de données avec le type de disque encrypted de ClickHouse.

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

Le chiffrement s’active table par table ; la politique de stockage par défaut reste en clair. Sélectionnez la politique chiffrée lors de la création d’une table :

CREATE TABLE secret_data (id UInt64) ENGINE = MergeTree ORDER BY id
SETTINGS storage_policy = 'encrypted';

Définissez encryption.policyName pour utiliser un autre nom de politique.

Cela chiffre les parties de données MergeTree écrites via la politique chiffrée avec AES-128-CTR. Les métadonnées du serveur ClickHouse et les logs à la racine des données ne sont pas couverts — utilisez un chiffrement au niveau du disque, comme LUKS ou un pilote CSI, pour ceux-ci. L’activation du chiffrement sur un cluster en cours d’exécution déclenche un redémarrage progressif ponctuel afin d’injecter la clé ; les répliques peuvent brièvement signaler une erreur de rechargement de la configuration jusqu’à ce que ce redémarrage soit terminé.La clé est stockée dans le Secret du cluster géré par l’opérateur, qui appartient à la ressource personnalisée et est supprimé avec elle. Les parties chiffrées sont illisibles sans la clé : si les données chiffrées doivent survivre à la suppression du CR (les PVC sont conservés), fournissez la clé via externalSecret ou sauvegardez l’entrée disk-encryption-key avant la suppression. Ne supprimez pas le Secret géré — l’opérateur générerait une nouvelle clé et les parties chiffrées existantes deviendraient illisibles.

Ce que vous ne pouvez pas modifier après la création

L’organisation du stockage est en grande partie figée une fois le cluster créé. Les mises à jour qui rendraient des PersistentVolumeClaims orphelins ou les réassocieraient sont rejetées lors de l’admission :

La présence de dataVolumeClaimSpec est immuable — vous ne pouvez pas ajouter un volume de données à un cluster créé sans ce volume, ni le supprimer d’un cluster créé avec un tel volume.
L’ensemble des additionalVolumeClaimTemplates est figé — vous ne pouvez pas ajouter, supprimer ni renommer d’entrées après la création.
L’augmentation de resources.requests.storage sur une entrée existante est autorisée (sous réserve de la prise en charge par la StorageClass, voir Extension du stockage).
Le chiffrement ne peut pas être désactivé une fois activé, et encryption.policyName ne peut pas être renommé — les tables utilisant déjà la politique de chiffrement deviendraient inaccessibles.

Référence de validation

Condition	Résultat
Ni `dataVolumeClaimSpec` ni volume personnalisé monté sur `/var/lib/clickhouse`	Avertissement — risque de perte de données au redémarrage
Volume personnalisé monté sur `/var/lib/clickhouse` alors que `dataVolumeClaimSpec` est défini	Rejeté
`additionalVolumeClaimTemplates` défini, mais `dataVolumeClaimSpec` absent	Rejeté
Disque supplémentaire nommé `default`	Rejeté — réservé par le disque `default` de ClickHouse
Nom de disque supplémentaire se terminant par `-encrypted`	Rejeté — entre en conflit avec les noms de disques chiffrés générés
Disque supplémentaire nommé `clickhouse-storage-volume`	Rejeté — entre en conflit avec le nom du volume de données principal
Nom de disque supplémentaire en double	Rejeté
Nom ne correspondant pas à `^[a-z]([-a-z0-9]*[a-z0-9])?$` ou de plus de 63 caractères	Rejeté par le schéma de la CRD
Ajout ou suppression de `dataVolumeClaimSpec` après la création	Rejeté
Ajout, suppression ou renommage de `additionalVolumeClaimTemplates` après la création	Rejeté
Nom de volume réservé dans `podTemplate.volumes`	Rejeté
`encryption.policyName` défini sur `default`	Rejeté par le schéma de la CRD — la politique chiffrée ne doit pas remplacer la politique par défaut
Désactivation de `encryption` ou renommage de sa politique après la création	Rejeté par le schéma de la CRD

Configuration — la référence complète des champs, y compris extraConfig.
Mise à l’échelle des clusters — comment ajouter et supprimer des répliques et des shards.

Installation

Guides

Référence

Volume de données principal

Exécution sans volume de données persistant

Extension du stockage

Stockage multi-disques (JBOD)

Politiques de stockage personnalisées

Chiffrement au repos

Ce que vous ne pouvez pas modifier après la création

Référence de validation

​Volume de données principal

​Exécution sans volume de données persistant

​Extension du stockage

​Stockage multi-disques (JBOD)

​Politiques de stockage personnalisées

​Chiffrement au repos

​Ce que vous ne pouvez pas modifier après la création

​Référence de validation

​Guides associés

Volume de données principal

Exécution sans volume de données persistant

Extension du stockage

Stockage multi-disques (JBOD)

Politiques de stockage personnalisées

Chiffrement au repos

Ce que vous ne pouvez pas modifier après la création

Référence de validation

Guides associés