Introducción al ClickHouse Operator

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

Qué es el 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

Recursos personalizados

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

ClickHouseCluster

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

KeeperCluster

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

Coordinación

Se requiere ClickHouse Keeper

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.

Relación uno a uno con Keeper

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

Los volúmenes persistentes no se eliminan automáticamente cuando se eliminan los recursos ClickHouseCluster o KeeperCluster.

Al volver a crear un clúster:

Elimine el recurso ClickHouseCluster
Elimine el recurso KeeperCluster
Espere a que todos los pods finalicen
Opcionalmente, elimine los PersistentVolumeClaims si desea empezar desde cero
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.

Replicación del esquema

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

Qué se replica

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)

Recomendado: Use el motor de base de datos Replicated

Práctica recomendadaUtilice siempre el motor de base de datos Replicated para implementaciones en producción.

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;

Evite los motores no 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

Deshabilitar la replicación del esquema

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

Gestión del almacenamiento

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

Configuración del volumen de datos

Especifique los requisitos de almacenamiento en dataVolumeClaimSpec:

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

Ciclo de vida del almacenamiento

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

Aspectos destacados de la configuración predeterminada

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)

Siguientes pasos

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

Instalar

Guías

Referencia

Qué es el ClickHouse Operator

Recursos personalizados

ClickHouseCluster

KeeperCluster

Coordinación

Se requiere ClickHouse Keeper

Relación uno a uno con Keeper

Replicación del esquema

Qué se replica

Recomendado: Use el motor de base de datos Replicated

Evite los motores no Replicated

Deshabilitar la replicación del esquema

Gestión del almacenamiento

Configuración del volumen de datos

Ciclo de vida del almacenamiento

Aspectos destacados de la configuración predeterminada

Siguientes pasos

​Qué es el ClickHouse Operator

​Recursos personalizados

​ClickHouseCluster

​KeeperCluster

​Coordinación

​Se requiere ClickHouse Keeper

​Relación uno a uno con Keeper

​Replicación del esquema

​Qué se replica

​Recomendado: Use el motor de base de datos Replicated

​Evite los motores no Replicated

​Deshabilitar la replicación del esquema

​Gestión del almacenamiento

​Configuración del volumen de datos

​Ciclo de vida del almacenamiento

​Aspectos destacados de la configuración predeterminada

​Siguientes pasos

Qué es el ClickHouse Operator

Recursos personalizados

ClickHouseCluster

KeeperCluster

Coordinación

Se requiere ClickHouse Keeper

Relación uno a uno con Keeper

Replicación del esquema

Qué se replica

Recomendado: Use el motor de base de datos Replicated

Evite los motores no Replicated

Deshabilitar la replicación del esquema

Gestión del almacenamiento

Configuración del volumen de datos

Ciclo de vida del almacenamiento

Aspectos destacados de la configuración predeterminada

Siguientes pasos