Introducción al ClickHouse Operator

Este documento ofrece una visión general de los conceptos clave y los patrones de uso de ClickHouse Operator.

El ClickHouse Operator es un operador de Kubernetes que automatiza la implementación y la administración de clústeres de ClickHouse en Kubernetes. Basado en el patrón de operador, amplía la API de Kubernetes con recursos personalizados que representan clústeres de ClickHouse y sus dependencias.

El operador se encarga de:

• La gestión del ciclo de vida del clúster (creación, actualizaciones, escalado y eliminación)
• La coordinación del clúster de ClickHouse Keeper
• La generación automática de configuración
• La sincronización del esquema de la base de datos
• Las actualizaciones graduales y de versión
• El aprovisionamiento de almacenamiento

El operador proporciona dos definiciones principales de recursos personalizados (CRD):

Representa un clúster de bases de datos de ClickHouse con réplicas y segmentos configurables.

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi

Representa un clúster de ClickHouse Keeper para la coordinación distribuida (sustituto de ZooKeeper).

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

Cada ClickHouseCluster requiere un clúster de ClickHouse Keeper para la coordinación distribuida. Se debe hacer referencia al clúster de Keeper en la especificación de ClickHouseCluster mediante keeperClusterRef. De forma predeterminada, el operador busca en el espacio de nombres de ClickHouseCluster, pero también puede configurar keeperClusterRef.namespace para que apunte a un KeeperCluster en otro espacio de nombres supervisado.

Cada ClickHouseCluster debe tener su propio KeeperCluster dedicado. No es posible compartir un único KeeperCluster entre varios ClickHouseClusters.

¿Por qué? El operador genera automáticamente una clave de autenticación única para que cada ClickHouseCluster acceda a su Keeper. Esta clave se almacena en un Secret y no puede compartirse.

Consecuencias:

• Varios ClickHouseClusters no pueden hacer referencia al mismo KeeperCluster
• Volver a crear un ClickHouseCluster requiere volver a crear su KeeperCluster

Al volver a crear un clúster:

1. Elimine el recurso ClickHouseCluster
2. Elimine el recurso KeeperCluster
3. Espere a que todos los pods finalicen
4. Opcionalmente, elimine los PersistentVolumeClaims si desea empezar desde cero
5. Vuelva a crear conjuntamente el KeeperCluster y el ClickHouseCluster

Para evitar errores de autenticación, elimine manualmente los Persistent Volumes o vuelva a crear ambos clústeres a la vez con almacenamiento nuevo.

El ClickHouse Operator replica automáticamente las definiciones de las bases de datos en todas las réplicas de un clúster.

El operador sincroniza:

• Definiciones de bases de datos Replicated
• Motores de bases de datos de integración (PostgreSQL, MySQL, etc.)

El operador no sincroniza:

• Bases de datos no replicadas (Atomic, Ordinary, etc.)
• Tablas locales en bases de datos no replicadas
• Datos de tablas (gestionados por la replicación de ClickHouse)

Beneficios:

• Replicación automática del esquema en todos los nodos
• Gestión simplificada de las tablas
• El operador puede sincronizarse con las nuevas réplicas
• Esquema coherente en todo el clúster

Cree bases de datos con DDL distribuido:

CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;

Los motores de base de datos no replicados (Atomic, Lazy, SQLite, Ordinary) requieren una gestión manual del esquema:

• Las tablas deben crearse individualmente en cada réplica
• Puede producirse una desviación del esquema entre nodos
• El operador no puede sincronizar automáticamente las réplicas nuevas

Para deshabilitar la replicación automática del esquema, establece spec.settings.enableDatabaseSync en false dentro del recurso ClickHouseCluster.

El operador gestiona el almacenamiento a través de PersistentVolumeClaims (PVC) de Kubernetes.

Especifique los requisitos de almacenamiento en dataVolumeClaimSpec:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi

• Creación: Los PVCs se crean automáticamente con el clúster
• Expansión: Se admite si la StorageClass permite la expansión de volúmenes
• Retención: Los PVCs no se eliminan automáticamente al eliminar el clúster
• Reutilización: Los PVCs existentes pueden reutilizarse si el clúster se vuelve a crear con el mismo nombre

Para eliminar por completo el almacenamiento:

# Delete cluster
kubectl delete clickhousecluster my-cluster

# Wait for pods to terminate
kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse

# Delete PVCs
kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse

• Clúster preconfigurado: clúster llamado 'default' que contiene todos los nodos de ClickHouse.
• Macros predeterminadas: algunas macros útiles ya están predefinidas:
  • {cluster}: nombre del clúster (default)
  • {shard}: número de segmento
  • {replica}: número de réplica
• Almacenamiento replicado para entidades de control de acceso basado en roles (RBAC)
• Almacenamiento replicado para funciones definidas por el usuario (UDF)

• Guía de configuración - Opciones de configuración detalladas
• Referencia de la API - Documentación completa de la API