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 con dataVolumeClaimSpec, un PersistentVolumeClaimSpec estándar de Kubernetes. El operador lo convierte en un PersistentVolumeClaim por réplica montado en la ruta de datos /var/lib/clickhouse:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    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.

La adición de discos adicionales en una configuración de varios discos (JBOD), la ejecución sin un volumen persistente, la ampliación de la capacidad, las políticas de almacenamiento personalizadas y las reglas sobre lo que no puede cambiar después de la creación se tratan en la guía de almacenamiento y volúmenes.

Dominio del clúster

spec.clusterDomain establece el sufijo DNS de Kubernetes que usa el operador al generar los nombres de host completos de los pods de Kubernetes que escribe en la configuración de servidor ClickHouse. Su valor predeterminado es cluster.local y está disponible tanto en ClickHouseCluster como en KeeperCluster.

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

El operador se dirige a cada pod de Kubernetes a través del Service headless como <pod>.<headless-service>.<namespace>.svc.<clusterDomain>. Ese sufijo se usa en dos partes de la configuración generada:

En un ClickHouseCluster, su valor se usa para los nombres del host de las réplicas en remote_servers (consultas entre réplicas y consultas Distributed).
En un KeeperCluster, su valor se usa para construir los nombres del host de los nodos de Keeper que ClickHouse utiliza para la coordinación.

Sobrescriba esto solo cuando el agente kubelet de su clúster se ejecute con un --cluster-domain distinto de cluster.local. Si el valor no coincide con el dominio real del clúster, ClickHouse no podrá resolver los nombres del host de Keeper ni de las réplicas, y la coordinación y las consultas Distributed fallarán con errores de resolución de DNS. Establezca el mismo valor en el ClickHouseCluster y en el KeeperCluster al que hace referencia.

Almacenamiento multidisco (JBOD)

additionalVolumeClaimTemplates agrega discos adicionales a cada réplica de ClickHouse, además del dataVolumeClaimSpec principal, que es necesario para poder usarlos. Cada entrada es una plantilla de PVC: un metadata.name y una spec de PVC. Los discos se reconcilian exactamente igual que el disco de datos principal, como volumeClaimTemplates de StatefulSet, por lo que el controlador de StatefulSet crea y conserva un PVC por réplica, con el nombre <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 lo añade a una configuración de almacenamiento de ClickHouse generada automáticamente. Los guiones de un nombre se convierten en guiones bajos en el identificador del disco de ClickHouse; la ruta de montaje conserva el nombre original. El disco de datos principal y todos los discos adicionales se colocan en un único volumen de la política de almacenamiento default, por lo que ClickHouse distribuye las nuevas partes de datos entre todos ellos con un esquema round-robin. La capacidad utilizable es la suma de todos los discos, y toda tabla que no defina su propia storage_policy (incluidas las tablas system.*) usa el conjunto combinado.

Los nombres de los PVC deben coincidir con ^[a-z]([-a-z0-9]*[a-z0-9])?$ y no deben entrar en conflicto con el nombre del volumen de datos principal. Al igual que el disco de datos principal, el conjunto de discos adicionales queda fijado en el momento de la creación: cualquier intento de añadir, eliminar o renombrar entradas después de la creación se rechaza. Los PVC adicionales se conservan cuando se elimina el clúster, igual que el disco de datos principal. El tamaño de almacenamiento de una entrada existente puede ampliarse si la clase de almacenamiento admite la expansión.

Dominio del clúster

spec.clusterDomain establece el sufijo DNS de Kubernetes que el operador usa al generar los nombres de host completos de los pods de Kubernetes que escribe en la configuración del servidor ClickHouse. Su valor predeterminado es cluster.local y existe tanto en ClickHouseCluster como en KeeperCluster.

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

El operador accede a cada pod de Kubernetes a través del Service headless como <pod>.<headless-service>.<namespace>.svc.<clusterDomain>. Ese sufijo se refleja en dos partes de la configuración generada:

En un ClickHouseCluster, su valor se utiliza para los nombres del host de las réplicas en remote_servers (consultas entre réplicas y consultas Distributed).
En un KeeperCluster, su valor se usa para construir los nombres del host de los nodos de Keeper que ClickHouse utiliza para la coordinación.

Solo sobrescriba esto cuando el agente kubelet de su clúster se ejecute con un --cluster-domain distinto de cluster.local. Si el valor no coincide con el dominio real del clúster, ClickHouse no podrá resolver los nombres del host de Keeper ni de las réplicas, y la coordinación y las consultas Distributed fallarán con errores de resolución de DNS. Establezca el mismo valor en el ClickHouseCluster y en el KeeperCluster al que hace referencia.

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:

# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "512Mi"

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 el par de claves del server:

tls.crt - certificado del server codificado en PEM
tls.key - private key 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 verifica los certificados de los nodos de Keeper con el almacén de confianza del sistema, además de cualquier caBundle que configure. Para confiar en una CA privada (por ejemplo, una CA autofirmada o interna), proporcione una referencia a un bundle de CA personalizado:

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

Secret externo

De forma predeterminada, el operador crea y controla un Secret que contiene las credenciales internas del clúster (contraseña entre servidores, contraseña de administración, identidad de Keeper, secreto del clúster y clave de colecciones con nombre). El Secret toma el nombre del clúster y reside en el espacio de nombres del clúster. Si quiere gestionar estas credenciales usted mismo —por ejemplo, obteniéndolas de HashiCorp Vault, AWS Secrets Manager o External Secrets Operator—, haga que el operador apunte a un Secret ya existente mediante spec.externalSecret:

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi
  externalSecret:
    name: my-clickhouse-credentials
    policy: Observe

El Secret referenciado debe estar en el mismo espacio de nombres que el ClickHouseCluster. El operador nunca elimina un Secret que no haya creado.

Claves requeridas

El Secret debe contener las siguientes claves:

Clave	Formato	Cuándo es obligatoria
`interserver-password`	contraseña en texto plano	Siempre
`management-password`	contraseña en texto plano	Siempre
`keeper-identity`	`clickhouse:<password>`	Siempre
`cluster-secret`	contraseña en texto plano	Siempre
`named-collections-key`	clave AES de 16 bytes codificada en hexadecimal (32 caracteres hexadecimales)	Solo en ClickHouse `>= 25.12`

Un Secret completo tiene este aspecto:

apiVersion: v1
kind: Secret
metadata:
  name: my-clickhouse-credentials
  namespace: sample
type: Opaque
stringData:
  interserver-password: "a-strong-random-password"
  management-password: "another-strong-password"
  keeper-identity: "clickhouse:keeper-auth-password"
  cluster-secret: "cluster-internal-secret"
  named-collections-key: "0123456789abcdef0123456789abcdef"   # 32 hex chars = 16 bytes

Política: Observe vs Manage

spec.externalSecret.policy controla cómo el operador maneja las claves requeridas que faltan:

Política	Comportamiento cuando faltan claves
`Observe` (predeterminada)	La reconciliación queda bloqueada hasta que estén presentes todas las claves requeridas. El operador informa de cada clave que falta —y de la indicación de formato correspondiente— mediante la condición `ExternalSecretValid` (con el motivo `ExternalSecretInvalid`) y un evento `Warning`.
`Manage`	El operador genera cualquier clave requerida que falte y la vuelve a escribir en el mismo Secret. Resulta útil para el aprovisionamiento inicial: crea un Secret vacío, deja que el operador lo complete y, después, opcionalmente, restringe el acceso. Aun así, el operador nunca elimina el Secret.

Incluso con policy: Manage, el Secret ya debe existir en el espacio de nombres: el operador nunca crea el Secret por sí mismo; solo escribe las claves generadas en uno ya existente. Si el Secret referenciado no existe, la reconciliación se bloquea con el motivo ExternalSecretNotFound, independientemente de la política.

Elige Observe cuando un sistema externo (Vault, ESO, sealed-secrets, GitOps) sea la fuente de referencia y quieras que el operador falle claramente ante una configuración incorrecta. Elige Manage cuando quieras un aprovisionamiento inicial autosuficiente, pero también conservar la propiedad del propio objeto Secret (por ejemplo, para hacer una copia de seguridad).

Condición de estado y solución de problemas

El operador expone una condición ExternalSecretValid en ClickHouseCluster.status.conditions. Revísala cuando parezca que la reconciliación está atascada:

# Plain kubectl — works out of the box
kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p'

# Same data as YAML
kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

# Pretty-printed JSON (requires jq)
kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq

Posibles razones:

`reason`	Significado	Solución
`ExternalSecretNotFound`	El Secret referenciado no existe en el espacio de nombres.	Crea el Secret o corrige `spec.externalSecret.name`.
`ExternalSecretInvalid`	El Secret existe, pero no tiene las claves requeridas (solo con `Observe`). El mensaje enumera cada clave faltante junto con su formato esperado.	Agrega las claves faltantes o cambia a `policy: Manage`.
`ExternalSecretValid`	Todas las claves requeridas están presentes y el operador está usando el Secret.	—

El operador vuelve a encolar la reconciliación mientras el Secret no sea válido, así que, en cuanto agregues las claves faltantes, la siguiente reconciliación las detectará automáticamente; no hace falta reiniciar los pods.

El conjunto de claves requeridas depende de la versión de ClickHouse en ejecución. named-collections-key solo se valida una vez que la sonda de versión del operador ha detectado ClickHouse 25.12 o una versión posterior. En versiones anteriores, la clave puede no estar presente en el Secret.

Puertos adicionales

El operador expone un conjunto fijo de puertos en cada pod de Kubernetes de ClickHouse y en su Service headless: 8123 para HTTP, 9000 nativo, 9009 entre servidores, 9001 de administración, 9363 para métricas de Prometheus, y las variantes TLS 8443/9440 cuando TLS está habilitado. Para que ClickHouse escuche en protocolos adicionales —MySQL, PostgreSQL, gRPC o cualquier puerto personalizado—, declárelos en spec.additionalPorts:

spec:
  additionalPorts:
    - name: mysql
      port: 9004
    - name: postgres
      port: 9005
    - name: grpc
      port: 9100

El operador añade esos puertos a containerPorts del pod de Kubernetes y al Service headless. El ejemplo completo se encuentra en examples/custom_protocols.yaml.

additionalPorts solo abre los puertos del lado de Kubernetes. No configura el ClickHouse server para que escuche en ellos. También tienes que habilitar el protocolo correspondiente en spec.settings.extraConfig.protocols. De lo contrario, el puerto está abierto en el Service, pero nada dentro del pod de Kubernetes responde.

Ejemplo completo: MySQL wire protocol

Para exponer ClickHouse mediante el MySQL wire protocol en el puerto 9004:

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 1
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 2Gi

  # 1) Open the port on the Pod and the headless Service.
  additionalPorts:
    - name: mysql
      port: 9004

  # 2) Tell ClickHouse server to actually listen on it.
  settings:
    extraConfig:
      protocols:
        mysql:
          type: mysql
          port: 9004
          description: "MySQL wire protocol"

Una vez aplicado, verifique desde dentro del clúster:

kubectl exec sample-clickhouse-0-0-0 -- \
  clickhouse-client --port 9004 --query "SELECT 1"

Restricciones de los campos

Campo	Regla
`name`	Debe coincidir con el patrón DNS_LABEL `^[a-z]([-a-z0-9]*[a-z0-9])?$`, con un máximo de 63 caracteres. El CRD aplica la unicidad como clave list-map.
`port`	Entero en `[1, 65535]`. El webhook rechaza números de puerto duplicados en la lista.

Puertos y nombres reservados

El webhook de validación rechaza las entradas de additionalPorts que entrarían en conflicto con los puertos en los que el propio operador escucha. Todos los puertos relacionados con TLS están reservados incondicionalmente para que habilitar spec.settings.tls.enabled más adelante no invalide un clúster que antes era válido.

Port	Reservado para
`8123`	HTTP
`8443`	HTTPS
`9000`	native TCP
`9440`	TLS nativo
`9009`	interserver
`9001`	management
`9363`	métricas de Prometheus

Los siguientes nombres también se rechazan: son los identificadores internos del operador para tipos de protocolo (no los alias legibles para humanos):

Name
`http`
`http-secure`
`tcp`
`tcp-secure`
`interserver`
`management`
`prometheus`

Una solicitud rechazada produce un error como:

spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port
spec.additionalPorts[0].name: "http" is reserved by the operator

Sonda de versión y canal de actualización

El operador realiza dos tareas independientes con las versiones del clúster:

Informe de versión — para ClickHouseCluster, un Job de Kubernetes ejecuta la imagen de contenedor una vez para detectar la versión de ClickHouse en ejecución; para KeeperCluster, el operador lee la versión informada por el servidor desde las réplicas en ejecución. La versión detectada se registra en .status.version y se utiliza en otros pasos de reconciliación (por ejemplo, la clave de named collections de External Secret solo es necesaria a partir de ClickHouse 25.12).
Canal de actualización — una comprobación periódica del feed público de versiones de ClickHouse (https://clickhouse.com/data/version_date.tsv). El operador informa si hay una versión más reciente disponible mediante la condición de estado VersionUpgraded. Nunca actualiza el clúster por sí solo; el usuario controla la etiqueta de la imagen.

Elegir un canal de lanzamientos

spec.upgradeChannel selecciona con qué conjunto de lanzamientos upstream compara el operador. El mismo campo existe tanto en ClickHouseCluster como en KeeperCluster.

spec:
  upgradeChannel: lts   # or "stable", or "25.8", or omitted

Valores permitidos (validados por la CRD con el patrón ^(lts|stable|\d+\.\d+)?$):

Valor	Comportamiento
vacío (predeterminado)	El operador propone solo actualizaciones menores dentro de la línea major.minor que se está ejecutando actualmente. A un cluster en `25.8.3.1` se le notificará sobre `25.8.4.x`, pero no sobre `25.9.x`.
`stable`	Sigue el canal `stable` de upstream: la última versión que ClickHouse Inc. marca como estable en la línea principal de releases. Recibe actualizaciones mayores antes que el canal `lts`.
`lts`	Sigue el canal `lts` de upstream: releases con soporte a largo plazo. Recibe actualizaciones mayores con menos frecuencia y con ventanas de soporte más largas.
`25.8` (o cualquier `<major>.<minor>`)	Fija el canal en una línea major.minor específica. No se proponen actualizaciones mayores más allá de esa línea, aunque exista una versión más reciente en upstream.

Para production, en general se prefiere fijar el canal a un <major>.<minor> explícito (por ejemplo, 25.8). Esto fija el cluster en la línea de release mayor prevista y permite que el operador mustre una advertencia WrongReleaseChannel si alguna réplica se desvía de algún modo a una major distinta, algo especialmente importante cuando la image se referencia mediante un digest (@sha256:...) en lugar de un tag legible para humanos. El valor predeterminado vacío es adecuado para clusters de Development en los que los saltos entre versiones major no son una preocupación.

Condiciones de estado

Dos condiciones reflejan el resultado de la sonda y de la comprobación de actualización:

Condición	Motivo	Significado
`VersionInSync`	`VersionMatch`	Todas las réplicas informan la misma versión
`VersionInSync`	`VersionMismatch`	Las réplicas están ejecutando versiones distintas. Este motivo se suprime durante una actualización gradual planificada. Suele aparecer cuando se ha fijado una etiqueta de imagen mutable (por ejemplo, `latest` o una versión major sin más, como `26.3`) y el registry subyacente ha cambiado entre una descarga y otra, por lo que distintas réplicas acabaron con parches diferentes de la misma etiqueta.
`VersionInSync`	`VersionPending`	El Job de la sonda de versión aún no ha terminado, o todavía no se ha observado ninguna versión de réplica de Keeper
`VersionInSync`	`VersionProbeFailed`	El Job de la sonda de ClickHouse falló; el operador no puede determinar la versión en ejecución
`VersionUpgraded`	`UpToDate`	El cluster está en la versión más reciente disponible en el canal seleccionado
`VersionUpgraded`	`MinorUpdateAvailable`	Hay un parche más reciente disponible en la misma línea `major.minor`
`VersionUpgraded`	`MajorUpdateAvailable`	Hay una versión `major.minor` más reciente disponible dentro del canal elegido
`VersionUpgraded`	`VersionOutdated`	La versión en ejecución está desactualizada y ya no recibirá correcciones del canal seleccionado; normalmente porque la línea major se ha retirado de `lts` o `stable` upstream
`VersionUpgraded`	`WrongReleaseChannel`	La imagen en ejecución no pertenece al `upgradeChannel` seleccionado. Ejemplo: un cluster que ejecuta `26.5` con `upgradeChannel: lts`, ya que `26.5` no forma parte de la línea `lts` upstream.
`VersionUpgraded`	`UpgradeCheckFailed`	El operador no pudo acceder al feed de versiones upstream

Inspecciónalas con:

kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

Sobrescritura del Job de la sonda de versión

Esto se aplica solo a ClickHouseCluster. KeeperCluster ya no ejecuta un Job de sonda de versión; su versión se lee directamente de las réplicas de Keeper en ejecución, por lo que spec.versionProbeTemplate está obsoleto y no tiene efecto allí. La sonda se implementa como un Job estándar de Kubernetes. Si su clúster tiene políticas de admisión que exigen Tolerations específicas, selectores de nodo o contextos de seguridad, o si desea limitar cuánto tiempo permanecen los Jobs de sonda completados, sobrescriba la plantilla mediante spec.versionProbeTemplate:

spec:
  versionProbeTemplate:
    spec:
      ttlSecondsAfterFinished: 600   # delete completed probe Jobs 10 minutes after completion
      template:
        spec:
          nodeSelector:
            kubernetes.io/arch: amd64
          tolerations:
            - key: dedicated
              operator: Equal
              value: clickhouse
              effect: NoSchedule
          containers:
            - name: version-probe
              resources:
                requests:
                  cpu: 50m
                  memory: 64Mi

El nombre del contenedor version-probe es el predeterminado del operador: la entrada en containers: coincide con él por nombre, por lo que el operador aplica una fusión profunda de los campos proporcionados por el usuario sobre los valores predeterminados.

Controles globales del operador

Dos opciones del administrador del operador controlan globalmente el bucle de comprobación de actualizaciones:

Opción	Predeterminado	Efecto
`--version-update-interval`	`24h`	Frecuencia con la que el operador vuelve a obtener la lista de versiones del origen
`--disable-version-update-checks`	`false`	Desactiva por completo la comprobación de actualizaciones. No se establece la condición `VersionUpgraded` y no se genera tráfico HTTP saliente a `clickhouse.com`

Establece --disable-version-update-checks=true en entornos aislados de la red o cuando no se permite la salida a clickhouse.com.

Configuración de ClickHouse

Contraseña del usuario `default`

spec.settings.defaultUserPassword establece la contraseña del usuario default integrado. Proporcione el valor de una clave de un Secret (recomendado) o de un ConfigMap que cree, en lugar de incluirlo directamente en el CR:

spec:
  settings:
    defaultUserPassword:
      passwordType: password   # default; see "Password types" below
      secret:                  # exactly one of secret or configMap
        name: clickhouse-password   # name of the Secret/ConfigMap
        key: password               # the key inside it, not the password value

Proporcione exactamente uno de secret o configMap, y en ambos casos name (el objeto) y key (la entrada que contiene la contraseña).

Tipos de contraseña

passwordType le indica a ClickHouse cómo interpretar el valor. De forma predeterminada, es password (texto plano); las alternativas son formas con hash, como password_sha256_hex y password_double_sha1_hex. Se recomienda usar un tipo con hash para que la contraseña en texto plano nunca se almacene. Consulte la configuración de usuarios de ClickHouse para ver la lista completa.

Ejemplo completo con un Secret

Crea el Secret y, a continuación, haz referencia a su clave:

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

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  settings:
    defaultUserPassword:
      passwordType: password
      secret:
        name: clickhouse-password
        key: password

Con passwordType: password, el clickhouse-client del pod de Kubernetes se configura con esta contraseña, lo cual resulta práctico para la depuración.

Si usas una contraseña con hash, almacena el hash en lugar del texto plano:

echo -n 'your-secure-password' | sha256sum   # use the hex digest as the value
kubectl create secret generic clickhouse-password \
  --from-literal=password='<sha256-hex-digest>'

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      secret:
        name: clickhouse-password
        key: password

Uso de un ConfigMap

Un ConfigMap funciona de la misma manera, pero su contenido no está protegido como un Secret. Úselo solo para valores no confidenciales o con hash previo, como un resumen password_sha256_hex:

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

No coloque una contraseña en texto plano en un ConfigMap. Use un Secret para cualquier valor (passwordType: password) en texto plano.

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.

Registro del servidor

Configure el registro del ClickHouse server mediante spec.settings.logger. Todos los campos son opcionales y tienen valores predeterminados seguros, por lo que incluso un clúster que no modifique registrará en trace tanto en la consola del contenedor como en un archivo rotado en disco.

spec:
  settings:
    logger:
      logToFile: true   # Default: true. Set false to log only to the console
      jsonLogs: false   # Default: false. Set true for structured JSON log lines
      level: trace      # Default: trace
      size: 1000M       # Default: 1000M. Rotate a log file once it reaches this size
      count: 50         # Default: 50. Number of rotated files to keep

Campo	Predeterminado	Descripción
`logToFile`	`true`	Cuando es `false`, el operador elimina los destinos de archivo y el servidor solo escribe logs en la consola del contenedor.
`jsonLogs`	`false`	Cuando es `true`, el operador añade `formatting.type: json` para que cada línea sea un objeto JSON.
`level`	`trace`	Nivel de detalle de los logs. Uno de `test`, `trace`, `debug`, `information`, `notice`, `warning`, `error`, `critical`, `fatal`.
`size`	`1000M`	Tamaño máximo de un solo archivo de log antes de la rotación.
`count`	`50`	Número de archivos de log rotados que conserva el servidor.

El operador siempre mantiene activado el registro en consola para que kubectl logs funcione, y añade el registro en archivo cuando logToFile es true. Un clúster con los valores predeterminados genera este bloque logger:

logger:
  console: true
  level: trace
  log: /var/log/clickhouse-server/clickhouse-server.log
  errorlog: /var/log/clickhouse-server/clickhouse-server.err.log
  size: 1000M
  count: 50

El mismo bloque spec.settings.logger se aplica a un KeeperCluster; en ese caso, el operador escribe sus archivos en /var/log/clickhouse-keeper/.

El registro en consola permanece activado independientemente de logToFile, por lo que kubectl logs sigue funcionando incluso cuando desactivas el registro en archivos. Establece jsonLogs: true cuando envíes logs a un almacén de logs estructurados que procesa JSON.

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

Última modificación el 25 de junio de 2026

Almacenamiento y volúmenesCómo el operador aprovisiona almacenamiento persistente para clústeres de ClickHouse, incluido el volumen de datos principal, las configuraciones de varios discos (JBOD), la ampliación y lo que no se puede cambiar después de la creació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

​Dominio del clúster

​Almacenamiento multidisco (JBOD)

​Dominio del clúster

​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

​Secret externo

​Claves requeridas

​Política: Observe vs Manage

​Condición de estado y solución de problemas

​Puertos adicionales

​Ejemplo completo: MySQL wire protocol

​Restricciones de los campos

​Puertos y nombres reservados

​Sonda de versión y canal de actualización

​Elegir un canal de lanzamientos

​Condiciones de estado

​Sobrescritura del Job de la sonda de versión

​Controles globales del operador

​Configuración de ClickHouse

​Contraseña del usuario default

​Tipos de contraseña

​Ejemplo completo con un Secret

​Uso de un ConfigMap

​Usuarios personalizados en la configuración

​Sincronización de la base de datos

​Registro del servidor

​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

Dominio del clúster

Almacenamiento multidisco (JBOD)

Dominio del clúster

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

Secret externo

Claves requeridas

Política: Observe vs Manage

Condición de estado y solución de problemas

Puertos adicionales

Ejemplo completo: MySQL wire protocol

Restricciones de los campos

Puertos y nombres reservados

Sonda de versión y canal de actualización

Elegir un canal de lanzamientos

Condiciones de estado

Sobrescritura del Job de la sonda de versión

Controles globales del operador

Configuración de ClickHouse

Contraseña del usuario `default`

Tipos de contraseña

Ejemplo completo con un Secret

Uso de un ConfigMap

Usuarios personalizados en la configuración

Sincronización de la base de datos

Registro del servidor

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