> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción al ClickHouse Operator

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

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

<div id="what-is-the-clickhouse-operator">
  ## Qué es el ClickHouse Operator
</div>

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

<div id="custom-resources">
  ## Recursos personalizados
</div>

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

<div id="clickhousecluster">
  ### ClickHouseCluster
</div>

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

```yaml theme={null}
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi
```

<div id="keepercluster">
  ### KeeperCluster
</div>

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

```yaml theme={null}
apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi
```

<div id="coordination">
  ## Coordinación
</div>

<div id="clickhouse-keeper-is-required">
  ### Se requiere ClickHouse Keeper
</div>

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.

<div id="one-to-one-keeper-relationship">
  ### Relación uno a uno con Keeper
</div>

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

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

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.

<div id="schema-replication">
  ## Replicación del esquema
</div>

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

<div id="what-gets-replicated">
  ### Qué se replica
</div>

El operador sincroniza:

* Definiciones de bases de datos [Replicated](/docs/es/reference/engines/database-engines/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)

<div id="recommended-use-replicated-database-engine">
  ### Recomendado: Use el motor de base de datos Replicated
</div>

<Tip>
  **Práctica recomendada**

  Utilice siempre el motor de base de datos [Replicated](/docs/es/reference/engines/database-engines/replicated) para implementaciones en producción.
</Tip>

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:

```sql theme={null}
CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;
```

<div id="avoid-non-replicated-engines">
  ### Evite los motores no Replicated
</div>

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

<div id="disable-schema-replication">
  ### Deshabilitar la replicación del esquema
</div>

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

<div id="storage-management">
  ## Gestión del almacenamiento
</div>

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

<div id="data-volume-configuration">
  ### Configuración del volumen de datos
</div>

Especifique los requisitos de almacenamiento en `dataVolumeClaimSpec`:

```yaml theme={null}
spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi
```

<div id="storage-lifecycle">
  ### Ciclo de vida del almacenamiento
</div>

* **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:

```bash theme={null}
# 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
```

<div id="default-configuration-highlights">
  ## Aspectos destacados de la configuración predeterminada
</div>

* **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)**

<div id="next-steps">
  ## Siguientes pasos
</div>

* [Guía de configuración](/docs/es/products/kubernetes-operator/guides/configuration) - Opciones de configuración detalladas
* [Referencia de la API](/docs/es/products/kubernetes-operator/reference/api-reference) - Documentación completa de la API