> ## 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.
# Stockage et volumes
> Comment l'opérateur provisionne le stockage persistant pour les clusters ClickHouse, y compris le volume de données principal, les configurations multi-disques (JBOD), l'extension de capacité et ce qui ne peut pas être modifié après la création.
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](/docs/fr/products/kubernetes-operator/guides/configuration#storage-configuration)
et la [Référence de l’API](/docs/fr/products/kubernetes-operator/reference/api-reference).
## 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`.
```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
```
* 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](#at-rest-encryption), 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.
```yaml theme={null}
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é `--0`.
```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
```
L’opérateur monte chaque volume supplémentaire dans `/var/lib/clickhouse/disks/`
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](https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-multiple-volumes)
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.
```yaml theme={null}
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 :
```sql theme={null}
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](#expanding-storage)).
* 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 |
## Guides associés
* [Configuration](/docs/fr/products/kubernetes-operator/guides/configuration) — la référence complète des champs, y compris `extraConfig`.
* [Mise à l’échelle des clusters](/docs/fr/products/kubernetes-operator/guides/scaling) — comment ajouter et supprimer des répliques et des shards.