Almacenamiento y volúmenes

Esta guía explica cómo el operador aprovisiona almacenamiento persistente para un ClickHouseCluster: el volumen de datos principal, la incorporación de discos adicionales en una configuración de varios discos (JBOD), la ampliación de capacidad y las reglas que determinan qué se puede y qué no se puede cambiar una vez que existe un clúster.

Para consultar la referencia campo por campo, vea Configuración → Configuración de almacenamiento y la Referencia de la API.

spec.dataVolumeClaimSpec es un PersistentVolumeClaimSpec estándar de Kubernetes. El operador lo convierte en una volumeClaimTemplate de StatefulSet, de modo que el controlador de StatefulSet crea y conserva un PersistentVolumeClaim por réplica y lo monta en la ruta de datos de 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

• Cuando se omite accessModes, el operador usa ReadWriteOnce de forma predeterminada.
• El PVC por réplica se conserva cuando se elimina el clúster, por lo que los datos sobreviven a una eliminación y posterior recreación del recurso personalizado. Para los datos en una política cifrada, esto además requiere conservar la clave de cifrado; consulta la nota de esa sección.
• El mismo campo existe en KeeperCluster y se comporta de la misma manera.

dataVolumeClaimSpec es opcional. Si lo omite y no monta su propio volumen en la ruta de datos, ClickHouse escribe en el filesystem efímero del contenedor y el webhook de admisión devuelve una advertencia indicando que los datos podrían perderse si el clúster se reinicia.

Esto está pensado solo para clusters desechables o de prueba. Para proporcionar su propio almacenamiento en lugar de dataVolumeClaimSpec —por ejemplo, un emptyDir o un volumen preaprovisionado—, defínalo mediante spec.podTemplate.volumes y móntelo en /var/lib/clickhouse con spec.containerTemplate.volumeMounts.

Para ampliar un volumen, aumenta resources.requests.storage y aplica el cambio. El operador actualiza los PVC existentes sin recrearlos.

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

spec.additionalVolumeClaimTemplates añade discos adicionales a cada réplica de ClickHouse además del dataVolumeClaimSpec principal. Cada entrada es una plantilla de PVC con nombre —un metadata.name más una spec de PVC—, reconciliada exactamente igual que el disco de datos principal, por lo que el controlador de StatefulSet crea y conserva un PVC por réplica llamado <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

El operador monta cada volumen adicional en /var/lib/clickhouse/disks/<name> y genera automáticamente la storage_configuration de ClickHouse — no tienes que escribirla a mano. Registra cada disco adicional y lo añade a la política de almacenamiento default integrada.

El disco de datos principal (default) y cada disco adicional comparten un único volumen de la política default, por lo que ClickHouse distribuye las nuevas partes de datos entre todos ellos de forma round-robin. La capacidad utilizable es la suma de todos los discos, y cualquier tabla que no defina su propia storage_policy — incluidas las tablas system.* — usa el conjunto combinado.

No necesitas extraConfig para la disposición JBOD anterior: el operador genera automáticamente la política default. Usa spec.settings.extraConfig solo cuando quieras políticas de almacenamiento además de la predeterminada generada; por ejemplo, una política por niveles hot/cold con move_factor y prefer_not_to_merge, o un disco respaldado por S3. La configuración que añadas ahí se combina con la storage_configuration generada.

Consulta la documentación de almacenamiento de ClickHouse para ver los campos de la política.

Configurar spec.settings.encryption habilita el cifrado en reposo de los datos de la tabla. El operador genera una clave AES de 16 bytes — almacenada en el Secret del clúster gestionado, o proporcionada mediante externalSecret — y una política de almacenamiento dedicada que encapsula cada disco de datos con el tipo de disco encrypted de ClickHouse.

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

El cifrado se habilita por tabla; la política de almacenamiento predeterminada sigue sin cifrar. Seleccione la política cifrada al crear una tabla:

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

Establece encryption.policyName para usar otro nombre de política.

La configuración del almacenamiento queda prácticamente fija una vez creado un clúster. Las actualizaciones que dejarían huérfanas o volverían a vincular PersistentVolumeClaims se rechazan durante la admisión:

• La presencia de dataVolumeClaimSpec es inmutable: no puedes agregar un volumen de datos a un clúster creado sin uno, ni eliminarlo de un clúster creado con uno.
• El conjunto de additionalVolumeClaimTemplates es fijo: no puedes agregar, eliminar ni cambiar de nombre las entradas después de la creación.
• Sí se permite ampliar resources.requests.storage en una entrada existente (siempre que clase de almacenamiento lo admita; consulta Ampliación del almacenamiento).
• El cifrado no se puede deshabilitar una vez habilitado, y encryption.policyName no se puede cambiar de nombre: las tablas que ya usan la política cifrada quedarían inaccesibles.

• Configuración — la referencia completa de campos, incluido extraConfig.
• Escalado de clústeres — cómo se añaden y eliminan réplicas y segmentos.