Guía de configuración de ClickHouse Operator

Esta guía describe cómo configurar los clústeres de ClickHouse y Keeper mediante el operador.

Configuración de ClickHouseCluster

Configuración básica

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # Número de réplicas por segmento
  shards: 2             # Número de segmentos
  keeperClusterRef:
    name: my-keeper     # Referencia al KeeperCluster
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

Réplicas y segmentos

Réplicas: Número de instancias de ClickHouse por segmento (para alta disponibilidad)
Segmentos: Número de particiones horizontales (para el escalado)

spec:
  replicas: 3  # Predeterminado: 3
  shards: 2    # Predeterminado: 1

Un clúster con replicas: 3 y shards: 2 creará 6 pods de ClickHouse en total.

Integración de Keeper

Cada clúster de ClickHouse debe hacer referencia a un KeeperCluster para coordinarse:

spec:
  keeperClusterRef:
    name: my-keeper
    # namespace: keeper-system  # Opcional, por defecto usa el espacio de nombres de ClickHouseCluster

Cuando se establece keeperClusterRef.namespace, el operador debe observar ambos espacios de nombres. Si WATCH_NAMESPACE está configurado, incluya los espacios de nombres de ClickHouse y Keeper en esa lista.

Configuración de KeeperCluster

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # Debe ser impar: 1, 3, 5, 7, 9, 11, 13 o 15
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 5Gi

Configuración de almacenamiento

Configure el almacenamiento persistente:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Opcional: considera tu clase de almacenamiento según el CSI instalado
    resources:
      requests:
        storage: 100Gi

El operador solo puede modificar un PVC existente si la clase de almacenamiento asociada admite la expansión de volúmenes.

Configuración del pod de Kubernetes

Dispersión de topología y afinidad automáticas

Distribuya los pods entre las zonas de disponibilidad:

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname

Asegúrese de que su clúster de Kubernetes tenga suficientes nodos en distintas zonas para cumplir las restricciones de distribución.

Configuración manual

Se pueden especificar reglas arbitrarias de afinidad/antiafinidad de pod de Kubernetes y restricciones de distribución topológica.

spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>

Consulta la Referencia de la API para ver todas las opciones compatibles de la plantilla de pod de Kubernetes.

Presupuestos de interrupción de pods

El operador crea un PodDisruptionBudget (PDB) para cada clúster, de modo que las interrupciones voluntarias — drenado de nodos, actualizaciones progresivas y desalojos del autoscaler — no puedan dejar fuera de servicio suficientes pods como para perder el quórum o comprometer la disponibilidad. En los clústeres de ClickHouse con más de un segmento, se crea un PDB por segmento para que una interrupción en un segmento no se impute a otro.

Valores predeterminados

El operador elige valores predeterminados seguros según el tamaño del clúster, de modo que un apply inicial ya proteja frente a una pérdida accidental de quorum.

Recurso	Topología	PDB predeterminado
`ClickHouseCluster`	`replicas: 1` (segmento con una sola réplica)	`maxUnavailable: 1` — se permite la interrupción en un clúster de un solo nodo para que el drenaje de nodos no quede bloqueado
`ClickHouseCluster`	`replicas: 2+` (segmento con varias réplicas)	`minAvailable: 1` — al menos una réplica por segmento debe permanecer activa
`KeeperCluster`	`replicas: 1`	`maxUnavailable: 1` — se permite la interrupción en un clúster de un solo nodo para que el drenaje de nodos no quede bloqueado
`KeeperCluster`	`replicas: 3+`	`maxUnavailable: replicas/2` — preserva el quorum de RAFT para un clúster `2F+1` (3 réplicas toleran 1 caída, 5 réplicas toleran 2 caídas)

Para un ClickHouseCluster de 3 segmentos con replicas: 3, el operador crea tres PDB, uno por segmento, cada uno con minAvailable: 1.

Sobrescribir los valores predeterminados

Usa spec.podDisruptionBudget para sobrescribir minAvailable o maxUnavailable (exactamente uno):

spec:
  replicas: 3
  shards: 2
  podDisruptionBudget:
    minAvailable: 2   # mantener al menos 2 de 3 réplicas en cada segmento activas durante una interrupción

O bien la forma maxUnavailable, con un porcentaje:

spec:
  replicas: 5
  podDisruptionBudget:
    maxUnavailable: 40%

El webhook de validación rechaza configurar a la vez minAvailable y maxUnavailable. Elige uno: Kubernetes tampoco permite ambos.

También puedes pasar el campo unhealthyPodEvictionPolicy al PDB generado, lo que resulta útil cuando necesitas permitir la expulsión de pods que aún siguen en NotReady:

spec:
  podDisruptionBudget:
    minAvailable: 2
    unhealthyPodEvictionPolicy: AlwaysAllow

Políticas

spec.podDisruptionBudget.policy te permite elegir con qué nivel de agresividad el operador gestiona los PDB:

Policy	Behavior
`Enabled` (default)	El operador crea y actualiza el PDB en cada reconciliación. Esta es la opción predeterminada segura para producción.
`Disabled`	El operador no crea PDB y elimina cualquier PDB existente con etiquetas coincidentes. Resulta útil para clústeres de desarrollo en los que deba permitirse cualquier interrupción voluntaria.
`Ignored`	El operador no crea ni elimina PDB. Los PDB existentes se dejan tal cual. Úsalo cuando otro sistema (p. ej., una política de admisión o una herramienta de GitOps) gestione los PDB por ti.

Ejemplo — deshabilita por completo la gestión de PDB en un clúster de desarrollo:

spec:
  podDisruptionBudget:
    policy: Disabled

Ejemplo — mantén tu PDB definido manualmente junto al clúster y evita que el operador lo toque:

spec:
  podDisruptionBudget:
    policy: Ignored

Desactivación a nivel de clúster

La gestión de PDB también puede deshabilitarse a nivel de clúster mediante la variable de entorno ENABLE_PDB del operador. Con ENABLE_PDB=false, el operador omite el paso de reconciliación de PDB para todos los ClickHouseCluster y KeeperCluster, independientemente de su spec.podDisruptionBudget.policy, y no observa en absoluto los recursos PodDisruptionBudget. Por lo tanto, el ServiceAccount del operador no necesita permisos de RBAC sobre poddisruptionbudgets.policy/v1, lo cual resulta útil cuando el operador se ejecuta con un ServiceAccount restringido que omite intencionadamente esos permisos.

# en la especificación de Implementación del operador
env:
- name: ENABLE_PDB
  value: "false"

Esto está pensado para entornos que incorporan sus propias políticas de interrupción (p. ej., mediante Gatekeeper / Kyverno) y quieren que el operador quede completamente fuera del proceso.

Configuración del contenedor

Imagen personalizada

Usa una imagen concreta de ClickHouse:

spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent

Recursos de los contenedores

Configure la CPU y la memoria de los contenedores de ClickHouse:

# valores predeterminados
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "1Gi"

Variables de entorno

Añada variables de entorno personalizadas:

spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"

Montajes de volúmenes

Agregue montajes de volúmenes adicionales:

spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml

Se permite especificar varios montajes de volúmenes en el mismo mountPath. El operador creará un volumen proyectado con todos los montajes especificados.

Consulta la referencia de la API para ver todas las opciones compatibles de la plantilla de contenedor.

Configuración de TLS/SSL

Configurar endpoints seguros

Pasa una referencia a un Secret de Kubernetes con certificados TLS para habilitar endpoints seguros

spec:
  settings:
    tls:
      enabled: true
      required: true # Los puertos no seguros se deshabilitan si se establece
      serverCertSecret:
        name: <certificate-secret-name>

Formato del Secret del certificado SSL

Se espera que el Secret contenga las siguientes claves:

tls.crt - certificado del server codificado en PEM
tls.key - private key codificada en PEM
ca.crt - cadena de certificados de la CA codificada en PEM

Este formato es compatible con los certificados generados por cert-manager.

Comunicación de ClickHouse-Keeper mediante TLS

Si KeeperCluster tiene TLS habilitado, ClickHouseCluster usará automáticamente una conexión segura a los nodos de Keeper. ClickHouseCluster debe poder verificar los certificados de los nodos de Keeper. Si ClickHouseCluster tiene TLS habilitado, usa el bundle ca.crt para la verificación. De lo contrario, se usa el bundle de CA predeterminado. El usuario puede proporcionar una referencia a un bundle de CA personalizado:

spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>

Configuración de ClickHouse

Contraseña predeterminada del usuario

Configure la contraseña predeterminada del usuario:

spec:
  settings:
    defaultUserPassword:
      passwordType: <password-type> # Predeterminado: password
      <secret|configMap>:
        name: <resource name>
        key: <password>

No se recomienda usar ConfigMap para almacenar contraseñas en texto plano.

Cree el secret:

kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'

Uso de ConfigMap para las contraseñas de los usuarios

También puede usar ConfigMap para contraseñas predeterminadas no confidenciales:

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password

Usuarios personalizados en la configuración

Configure usuarios adicionales en los archivos de configuración. Cree un ConfigMap y un Secret para el usuario:

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          - query: "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")

Añade una configuración personalizada a ClickHouseCluster:

spec:
  podTemplate:
    volumes:
      - name: reader-user
        configMap:
          name: user-config
  containerTemplate:
    env:
      - name: READER_PASSWORD
        valueFrom:
          secretKeyRef:
            name: reader-password
            key: password
    volumeMounts:
      - mountPath: /etc/clickhouse-server/users.d/
        name: reader-user
        readOnly: true

Sincronización de la base de datos

Habilite la sincronización automática de la base de datos para las nuevas réplicas:

spec:
  settings:
    enableDatabaseSync: true  # Predeterminado: true

Cuando está activado, el operador sincroniza las tablas Replicated y de integración en las nuevas réplicas.

Configuración personalizada

Configuración adicional integrada

En lugar de montar archivos de configuración personalizados, puedes especificar directamente opciones adicionales de configuración de ClickHouse. Agrega una configuración personalizada de ClickHouse con extraConfig:

spec:
  settings:
    extraConfig:
      background_pool_size: 20

Enlaces útiles:

Configuración integrada de usuarios adicionales

También puedes especificar la configuración adicional de usuarios de ClickHouse mediante extraUsersConfig. Esto es útil para definir usuarios, perfiles, cuotas y privilegios directamente en la especificación del clúster.

spec:
  settings:
    extraUsersConfig:
      users:
        analyst:
          password:
            - '@from_env': ANALYST_PASSWORD
          profile: "readonly"
          quota: "default"
      profiles:
        readonly:
          readonly: 1
          max_memory_usage: 10000000000
      quotas:
        default:
          interval:
            duration: 3600
            queries: 1000
            errors: 100

La extraUsersConfig se almacena en el objeto ConfigMap de k8s. Evite incluir secretos en texto plano allí.

Consulta la documentación para ver todas las opciones de configuración de usuarios de ClickHouse admitidas.

Ejemplo de configuración

Ejemplo completo de configuración:

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 10Gi
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  containerTemplate:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: <keeper-certificate-secret>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: default-user-password
data:
  # contraseña-secreta
  password: "..." # sha256 hex de la contraseña
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 200Gi
  keeperClusterRef:
    name: sample
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        key: password
        name: default-password

Install

Guides

Reference

Guía de configuración de ClickHouse Operator

Configuración de ClickHouseCluster

Configuración básica

Réplicas y segmentos

Integración de Keeper

Configuración de KeeperCluster

Configuración de almacenamiento

Configuración del pod de Kubernetes

Dispersión de topología y afinidad automáticas

Configuración manual

Consulta la Referencia de la API para ver todas las opciones compatibles de la plantilla de pod de Kubernetes.

Presupuestos de interrupción de pods

Valores predeterminados

Sobrescribir los valores predeterminados

Políticas

Desactivación a nivel de clúster

Configuración del contenedor

Imagen personalizada

Recursos de los contenedores

Variables de entorno

Montajes de volúmenes

Consulta la referencia de la API para ver todas las opciones compatibles de la plantilla de contenedor.

Configuración de TLS/SSL

Configurar endpoints seguros

Formato del Secret del certificado SSL

Comunicación de ClickHouse-Keeper mediante TLS

Configuración de ClickHouse

Contraseña predeterminada del usuario

Uso de ConfigMap para las contraseñas de los usuarios

Usuarios personalizados en la configuración

Sincronización de la base de datos

Configuración personalizada

Configuración adicional integrada

Enlaces útiles:

Configuración integrada de usuarios adicionales

Consulta la documentación para ver todas las opciones de configuración de usuarios de ClickHouse admitidas.

Ejemplo de configuración

​Configuración de ClickHouseCluster

​Configuración básica

​Réplicas y segmentos

​Integración de Keeper

​Configuración de KeeperCluster

​Configuración de almacenamiento

​Configuración del pod de Kubernetes

​Dispersión de topología y afinidad automáticas

​Configuración manual

​Consulta la Referencia de la API para ver todas las opciones compatibles de la plantilla de pod de Kubernetes.

​Presupuestos de interrupción de pods

​Valores predeterminados

​Sobrescribir los valores predeterminados

​Políticas

​Desactivación a nivel de clúster

​Configuración del contenedor

​Imagen personalizada

​Recursos de los contenedores

​Variables de entorno

​Montajes de volúmenes

​Consulta la referencia de la API para ver todas las opciones compatibles de la plantilla de contenedor.

​Configuración de TLS/SSL

​Configurar endpoints seguros

​Formato del Secret del certificado SSL

​Comunicación de ClickHouse-Keeper mediante TLS

​Configuración de ClickHouse

​Contraseña predeterminada del usuario

​Uso de ConfigMap para las contraseñas de los usuarios

​Usuarios personalizados en la configuración

​Sincronización de la base de datos

​Configuración personalizada

​Configuración adicional integrada

​Enlaces útiles:

​Configuración integrada de usuarios adicionales

​Consulta la documentación para ver todas las opciones de configuración de usuarios de ClickHouse admitidas.

​Ejemplo de configuración

Configuración de ClickHouseCluster

Configuración básica

Réplicas y segmentos

Integración de Keeper

Configuración de KeeperCluster

Configuración de almacenamiento

Configuración del pod de Kubernetes

Dispersión de topología y afinidad automáticas

Configuración manual

Consulta la Referencia de la API para ver todas las opciones compatibles de la plantilla de pod de Kubernetes.

Presupuestos de interrupción de pods

Valores predeterminados

Sobrescribir los valores predeterminados

Políticas

Desactivación a nivel de clúster

Configuración del contenedor

Imagen personalizada

Recursos de los contenedores

Variables de entorno

Montajes de volúmenes

Consulta la referencia de la API para ver todas las opciones compatibles de la plantilla de contenedor.

Configuración de TLS/SSL

Configurar endpoints seguros

Formato del Secret del certificado SSL

Comunicación de ClickHouse-Keeper mediante TLS

Configuración de ClickHouse

Contraseña predeterminada del usuario

Uso de ConfigMap para las contraseñas de los usuarios

Usuarios personalizados en la configuración

Sincronización de la base de datos

Configuración personalizada

Configuración adicional integrada

Enlaces útiles:

Configuración integrada de usuarios adicionales

Consulta la documentación para ver todas las opciones de configuración de usuarios de ClickHouse admitidas.

Ejemplo de configuración