Skip to main content
Esta página no se aplica a ClickHouse Cloud. El procedimiento que se documenta aquí está automatizado en los servicios de ClickHouse Cloud.
ClickHouse Keeper proporciona el sistema de coordinación para la replicación de datos y la ejecución de consultas de DDL distribuido. ClickHouse Keeper es compatible con ZooKeeper.

​
Detalles de implementación

ZooKeeper es uno de los primeros sistemas de coordinación de código abierto ampliamente conocidos. Está implementado en Java y tiene un modelo de datos simple y potente. El algoritmo de coordinación de ZooKeeper, ZooKeeper Atomic Broadcast (ZAB), no ofrece garantías de linealizabilidad para las lecturas, porque cada nodo de ZooKeeper atiende las lecturas localmente. A diferencia de ZooKeeper, ClickHouse Keeper está escrito en C++ y utiliza la implementación del algoritmo RAFT. Este algoritmo permite la linealizabilidad tanto en lecturas como en escrituras, y cuenta con varias implementaciones de código abierto en distintos lenguajes. De forma predeterminada, ClickHouse Keeper ofrece las mismas garantías que ZooKeeper: escrituras linealizables y lecturas no linealizables. Tiene un protocolo cliente-servidor compatible, por lo que cualquier cliente estándar de ZooKeeper puede utilizarse para interactuar con ClickHouse Keeper. Las instantáneas y los logs tienen un formato incompatible con ZooKeeper, pero la herramienta clickhouse-keeper-converter permite convertir datos de ZooKeeper en instantáneas de ClickHouse Keeper. El protocolo entre servidores de ClickHouse Keeper también es incompatible con ZooKeeper, por lo que no es posible tener un cluster mixto de ZooKeeper / ClickHouse Keeper. ClickHouse Keeper admite listas de control de acceso (ACL) del mismo modo que ZooKeeper. ClickHouse Keeper admite el mismo conjunto de permissions y tiene los mismos esquemas integrados: world, auth y digest. El esquema de authentication digest usa la pareja username:password; la contraseña se codifica en Base64.
No se admiten integrations externas.

​
Configuración

ClickHouse Keeper puede usarse como reemplazo independiente de ZooKeeper o como parte interna de ClickHouse server. En ambos casos, la configuración se realiza prácticamente en el mismo archivo .xml.

​
Parámetros de configuración de Keeper

La etiqueta principal de configuración de ClickHouse Keeper es <keeper_server> y tiene los siguientes parámetros: Otros parámetros comunes se heredan de la configuración del ClickHouse server (listen_host, logger, etc.).

​
Configuración de coordinación interna

La configuración de coordinación interna se encuentra en la sección <keeper_server>.<coordination_settings> y tiene los siguientes parámetros: La configuración del quórum se encuentra en la sección <keeper_server>.<raft_configuration> y contiene la descripción de los servidores. El único parámetro para todo el quórum es secure, que habilita una conexión cifrada para la comunicación entre los participantes del quórum. El parámetro puede establecerse en true si se requiere una conexión SSL para la comunicación interna entre nodos, o dejarse sin especificar en caso contrario. Los parámetros principales de cada <server> son:
  • id — Identificador del servidor en un quórum.
  • hostname — Nombre de host donde está ubicado este servidor.
  • port — Puerto en el que este servidor escucha conexiones.
  • can_become_leader — Establézcalo en false para configurar el servidor como learner. Si se omite, el valor es true.
Si cambia la topología de su clúster de ClickHouse Keeper (por ejemplo, al sustituir un servidor), asegúrese de mantener coherente la asignación de server_id a hostname y evite reorganizar o reutilizar un server_id existente para servidores distintos (por ejemplo, esto puede ocurrir si utiliza scripts de automatización para desplegar ClickHouse Keeper).Si el host de una instancia de Keeper puede cambiar, recomendamos definir y usar un nombre de host en lugar de direcciones IP sin procesar. Cambiar el nombre de host equivale a quitar y volver a añadir el servidor, lo que en algunos casos puede ser imposible (por ejemplo, si no hay suficientes instancias de Keeper para alcanzar el quórum).
async_replication está deshabilitado de forma predeterminada para evitar romper la compatibilidad con versiones anteriores. Si todas las instancias de Keeper de su clúster ejecutan una versión compatible con async_replication (v23.9+), recomendamos habilitarlo, ya que puede mejorar el rendimiento sin inconvenientes.
Puede encontrar ejemplos de configuración para un quórum de tres nodos en las pruebas de integración con el prefijo test_keeper_. Configuración de ejemplo para el servidor n.º 1:

​
Cómo ejecutarlo

ClickHouse Keeper está incluido en el paquete de ClickHouse server; solo agrega la configuración de <keeper_server> a tu /etc/your_path_to_config/clickhouse-server/config.xml e inicia ClickHouse server como siempre. Si quieres ejecutar ClickHouse Keeper en modo standalone, puedes iniciarlo de forma similar con:
Si no tiene el enlace simbólico (clickhouse-keeper), puede crearlo o indicar keeper como argumento de clickhouse:

​
Comandos de cuatro letras

ClickHouse Keeper también proporciona comandos 4lw que son casi iguales a los de ZooKeeper. Cada comando está compuesto por cuatro letras, como mntr, stat, etc. Hay algunos comandos especialmente interesantes: stat proporciona información general sobre el servidor y los clientes conectados, srvr proporciona detalles ampliados sobre el servidor y cons proporciona detalles ampliados sobre las conexiones. Los comandos 4lw tienen una configuración de lista blanca, four_letter_word_white_list, cuyo valor predeterminado es conf,cons,crst,envi,ruok,srst,srvr,stat,wchs,dirs,mntr,isro,rcvr,apiv,csnp,lgif,rqld,rclc,clrs,ftfl,ydld,bpon,bpof,pfev,lgrq, al que se añaden jmst,jmfp,jmep,jmdp en las compilaciones con jemalloc. La lista se lee una sola vez durante el inicio, por lo que modificarla requiere reiniciar. Puede enviar los comandos a ClickHouse Keeper mediante telnet o nc, en el puerto del cliente.
A continuación se detallan los comandos 4lw:
  • ruok: Comprueba si el servidor está en ejecución y sin errores. El servidor responderá con imok si está en ejecución. De lo contrario, no responderá en absoluto. Una respuesta de imok no indica necesariamente que el servidor se haya unido al quórum, sino únicamente que el proceso del servidor está activo y vinculado al puerto cliente especificado. Use “stat” para obtener más detalles sobre el estado con respecto al quórum y la información de conexión del cliente.
  • mntr: Muestra una lista de variables que pueden usarse para supervisar el estado del clúster.
zk_sum_leader_unavailable_time, zk_cnt_leader_unavailable_time, zk_sum_election_time y zk_cnt_election_time son métricas acumulativas exclusivas del líder. Son observaciones por servidor, no mediciones de disponibilidad de todo el clúster: el seguimiento comienza cuando ese servidor deja de observar un líder activo. Durante una partición de red, esto puede incluir el tiempo durante el cual un líder anterior sigue activo en otra partición. Las métricas de elección registran únicamente una elección exitosa posterior a una ventana sin líder observada localmente; una transferencia de liderazgo que no expone un estado sin líder muestreado no se cuenta intencionadamente. Keeper toma una muestra de su estado de líder local de NuRaft una vez por cada heart_beat_interval_ms, pero nunca con una frecuencia superior a una vez cada 100 milisegundos. Cada límite puede diferir de esa transición de estado local hasta en el intervalo efectivo, y pueden omitirse ventanas más cortas que ese intervalo. Keeper registra la finalización de la elección local en BecomeLeader de NuRaft. srst restablece los cuatro valores. La duración de la ventana observada localmente más reciente de cada tipo también se exporta a system.asynchronous_metrics como KeeperLastLeaderElectionTime y KeeperLastLeaderUnavailableTime, en milisegundos. KeeperLastLeaderElectionTime sigue la misma definición de ventana sin líder que zk_sum_election_time. Ambos también son exclusivos del líder: un nodo que no es el líder activo o que aún no ha completado una ventana informa 0. srst los restablece junto con los contadores acumulativos.
  • srvr: Muestra todos los detalles del servidor.
  • stat: Muestra información breve sobre el servidor y los clientes conectados.
  • srst: Reinicia las estadísticas del servidor. El comando afectará al resultado de srvr, mntr y stat.
  • conf: Imprime detalles de la configuración del servicio.
  • cons: Enumera todos los detalles de conexión/sesión de todos los clientes conectados a este servidor. Incluye información sobre la cantidad de paquetes recibidos/enviados, el ID de sesión, las latencias de las operaciones, la última operación realizada, etc…
  • crst: Reinicia las estadísticas de conexión/sesión para todas las conexiones.
  • envi: Imprime detalles del entorno de servicio
  • dirs: Muestra el tamaño total de las instantáneas y los archivos de log en bytes
  • isro: Comprueba si el servidor está en modo de solo lectura. El servidor responderá con ro si está en modo de solo lectura o con rw en caso contrario.
  • wchs: Muestra información breve sobre los watches del servidor.
  • wchc: Muestra información detallada sobre los watches del servidor por sesión. Esto muestra una lista de sesiones (conexiones) con los watches asociados (rutas). Ten en cuenta que, dependiendo del número de watches, esta operación puede ser costosa (y afectar al rendimiento del servidor); úsala con cuidado.
  • wchp: Enumera información detallada sobre los watches del servidor por ruta. Muestra una lista de rutas (znodes) con las sesiones asociadas. Ten en cuenta que, según el número de watches, esta operación puede resultar costosa (es decir, afectar al rendimiento del servidor), así que úsala con cuidado.
  • dump: Enumera las sesiones activas y los nodos efímeros. Solo funciona en el líder.
  • csnp: Programa una tarea de creación de instantánea. Devuelve el índice de log confirmado más reciente de la instantánea programada si la operación se completa correctamente, o Failed to schedule snapshot creation task. si falla. El comando lgif puede ayudarle a determinar si la instantánea ya está lista.
  • lgif: Información del log de Keeper. first_log_idx : mi primer índice de log en el almacén de logs; first_log_term : mi primer término de log; last_log_idx : mi último índice de log en el almacén de logs; last_log_term : mi último término de log; last_committed_log_idx : mi último índice de log confirmado en la máquina de estados; leader_committed_log_idx : índice de log confirmado del líder desde mi perspectiva; target_committed_log_idx : índice de log de destino que debe confirmarse; last_snapshot_idx : el índice de log confirmado más alto de la última instantánea.
  • rqld: Solicitud para convertirse en el nuevo líder. Devuelve Sent leadership request to leader. si se envía la solicitud o Failed to send leadership request to leader. si no se envía. Si el nodo ya es el líder, el resultado es el mismo que si se hubiera enviado la solicitud.
  • ftfl: Enumera todos las banderas de funcionalidad e indica si están enabled en la instancia de Keeper.
  • bpon: Pide al líder que espere a las réplicas que no consiguen seguir el ritmo. Mientras está activado, el líder no avanza el índice de commit más allá de ninguna réplica que pueda alcanzar, de modo que una réplica que se ha quedado atrás puede recuperar el terreno perdido en lugar de irse desviando hasta necesitar una instantánea. Las escrituras se confirman entonces a la velocidad de la réplica votante alcanzable más lenta, así que actívalo de forma deliberada, observa cómo las réplicas se ponen al día y vuelve a desactivarlo con bpof. No hay umbral de retraso: se espera a todas las réplicas votantes que el líder pueda alcanzar, por muy atrasadas que estén, incluida una que esté recibiendo una instantánea. Una réplica con can_become_leader establecido en false no vota y nunca se la espera, por lo que puede seguir desviándose hasta necesitar una instantánea: la contrapresión no la protege. Si lo único que se pretende es que una réplica no lidere, asígnale priority 0 en su lugar: seguirá votando, por lo que se la seguirá esperando, mientras que can_become_leader false la deja fuera del quórum por completo. Una réplica solo queda fuera cuando esperarla no conduce a nada: su última solicitud falló, no hizo ningún progreso dentro de slow_member_backpressure_no_progress_timeout_ms, todavía no ha respondido en absoluto en una nueva conexión y tampoco hay ninguna instantánea en camino hacia ella, lo que deja al líder sin saber en qué punto se encuentra, o bien está fuera del rango de log del líder, de modo que ni el log ni una instantánea pueden recuperarla; y esto es así porque esperar a una réplica de ese tipo congelaría el índice de commit para nada. Establece también slow_member_backpressure_max_uncommitted_log_entries. Retener el índice de commit no impide que el líder siga añadiendo entradas, así que sin este ajuste el log seguirá creciendo mientras se espera a la réplica. El comando puede enviarse a cualquier nodo: un seguidor lo reenvía al líder actual y no cambia nada localmente, por lo que solo el líder mantiene el ajuste. Compruébalo con zk_slow_member_backpressure en mntr en el líder, que zk_server_state identifica. El ajuste dura un único liderazgo (se desactiva tanto cuando un nodo se convierte en líder como cuando deja de serlo) y no se persiste, por lo que un nodo reiniciado arranca con él desactivado. Solo el líder puede responder por el ajuste, así que solo la respuesta del líder lo confirma. Un seguidor informa de que ha reenviado la solicitud, y nada más: el líder rechaza la que llega después de haber dejado de liderar.
  • bpof: Solicita al líder que deje de esperar a las réplicas que no logran mantener el ritmo. Puede enviarse a cualquier nodo y llega al líder de la misma forma que bpon.
  • ydld: Solicitud para ceder el liderazgo y convertirse en seguidor. Si el server que recibe la solicitud es el líder, primero pausará las operaciones de escritura, esperará hasta que el sucesor (el líder actual nunca puede ser el sucesor) complete el catch-up del log más reciente y luego renunciará. El sucesor se elegirá automáticamente. Devuelve Sent yield leadership request to leader. si la solicitud se envió, o Failed to send yield leadership request to leader. si no se envió. Si el nodo ya es un seguidor, el resultado es el mismo que cuando se envía la solicitud.
  • pfev: Devuelve los valores de todos los eventos recopilados. Para cada evento devuelve su nombre, su valor y su descripción.

​
Control HTTP

ClickHouse Keeper proporciona una interfaz HTTP para comprobar si una réplica está lista para recibir tráfico. Puede utilizarse en entornos en la nube, como Kubernetes. Ejemplo de configuración que habilita el endpoint /ready:

​
Banderas de funcionalidad

Keeper es totalmente compatible con ZooKeeper y sus clientes, pero también incorpora algunas funcionalidades y tipos de solicitud propios que puede usar el cliente de ClickHouse. Como estas funcionalidades pueden introducir cambios incompatibles con versiones anteriores, la mayoría están deshabilitadas de forma predeterminada y pueden habilitarse mediante la configuración keeper_server.feature_flags. Todas las funcionalidades pueden deshabilitarse explícitamente. Si desea habilitar una nueva funcionalidad en su clúster de Keeper, le recomendamos primero actualizar todas las instancias de Keeper del clúster a una versión que admita esa funcionalidad y, después, habilitar la funcionalidad en sí. Ejemplo de configuración de banderas de funcionalidad que deshabilita multi_read y habilita check_not_exists:
Las siguientes funcionalidades están disponibles:
Algunas de las banderas de funcionalidad están habilitadas de forma predeterminada a partir de la versión 25.7. La forma recomendada de actualizar Keeper a 25.7+ es actualizar primero a la versión 24.9+.

​
Migración desde ZooKeeper

No es posible realizar una migración sin interrupciones de ZooKeeper a ClickHouse Keeper. Debe detener su clúster de ZooKeeper, convertir los datos e iniciar ClickHouse Keeper. La herramienta clickhouse-keeper-converter convierte los logs y instantáneas de ZooKeeper en una instantánea de ClickHouse Keeper. Requiere ZooKeeper 3.4 o posterior.

​
Preparación previa a la migración

La migración requiere detener la ingestión de datos. Planifique una ventana de mantenimiento antes de empezar. Antes de detener ZooKeeper, detenga las tareas en segundo plano de ClickHouse que modifican los metadatos de coordinación. Por ejemplo:
Registre métricas comparativas antes de la migración para poder verificar la consistencia después.

​
Pasos de migración

  1. Detenga la ingestión de datos en todos los nodos de ClickHouse.
  2. Detenga todas las tareas en segundo plano en todos los nodos de ClickHouse (consulte más arriba).
  3. Detenga todos los nodos de ZooKeeper.
  4. Opcional, pero recomendable: identifique el nodo líder de ZooKeeper, inícielo y vuelva a detenerlo. Esto obliga a ZooKeeper a escribir una instantánea coherente en disco antes de la conversión.
  5. Ejecute clickhouse-keeper-converter en el nodo líder. Si tiene instalado el binario completo de ClickHouse, use en su lugar el subcomando keeper-converter (clickhouse keeper-converter). Si no dispone de ninguno de los dos, descargue el binario.
  1. Copie la instantánea en todos los nodos de ClickHouse Keeper. La instantánea debe estar presente en cada nodo antes de que se inicie cualquiera de ellos; si un nodo se inicia sin una instantánea, puede elegirse a sí mismo como líder con un estado vacío.
  2. Actualice la configuración de ClickHouse para que apunte al nuevo clúster de Keeper.
  3. Inicie ClickHouse Keeper en todos los nodos y, a continuación, reinicie ClickHouse.
  4. Compare las métricas con la referencia previa a la migración para verificar la consistencia.
  5. Reanude las tareas en segundo plano y reinicie la ingestión de datos.

​
Consolidación de varios clústeres de ZooKeeper

Si ejecuta varios clústeres de ZooKeeper —por ejemplo, uno por grupo de segmentos—, puede consolidarlos en un único clúster de ClickHouse Keeper. La herramienta oficial clickhouse-keeper-converter solo admite conversiones uno a uno (un clúster de ZooKeeper a una instantánea de Keeper), por lo que la consolidación requiere modificar el código fuente del convertidor para fusionar varias instantáneas:
  1. Ejecute clickhouse-keeper-converter por separado en cada clúster de ZooKeeper y escriba cada salida en un directorio distinto.
  2. Deserialice los archivos de instantánea de forma secuencial. Al fusionarlos, recalcule los valores de numChildren para evitar conflictos de ID de nodo entre espacios de nombres de distintos clústeres de origen.
  3. Escriba la salida fusionada en el directorio de instantáneas de ClickHouse Keeper de destino.

​
Gestión del cifrado y las ACL

ClickHouse Keeper admite los mismos esquemas de ACL que ZooKeeper (world, auth, digest). La forma de gestionar las ACL durante la conversión depende de su configuración de ZooKeeper:
  • Completamente cifrado o completamente sin cifrar: Convierta directamente. El convertidor conserva la información existente de las ACL.
  • Parcialmente cifrado: Antes de convertir, conceda privilegios de superadministrador a una cuenta y borre las ACL con setAcl -R en las rutas afectadas. Convierta y, después, vuelva a habilitar el cifrado en ClickHouse Keeper si es necesario.

​
Verificación de la migración

Después de iniciar ClickHouse Keeper y reiniciar ClickHouse, compare sus métricas clave con la referencia previa a la migración para confirmar que esta se completó correctamente. Al consolidar varios clústeres de ZooKeeper, distinga entre:
  • Rutas comunes: rutas presentes en varios clústeres de origen con datos idénticos; deben deduplicarse en el resultado combinado.
  • Rutas diferenciadas: rutas que existen solo en clústeres específicos (por ejemplo, en /clickhouse/tables para cada grupo de segmentos); deben conservarse del origen correcto.
Evite recorrer directamente árboles grandes de ZooKeeper para compararlos. En su lugar, imprima todas las rutas convertidas en un archivo durante la conversión.

​
Ajustes posteriores a la migración

Después de la migración, considere ajustar estos parámetros para clústeres más grandes o un mayor rendimiento: Estos parámetros se configuran en coordination_settings de su configuración de Keeper.

​
Recuperación tras perder el quórum

Como ClickHouse Keeper usa Raft, puede tolerar una cierta cantidad de fallos de nodos en función del tamaño del clúster. Por ejemplo, en un clúster de 3 nodos, seguirá funcionando correctamente si solo falla 1 nodo. La configuración del clúster se puede cambiar dinámicamente, pero hay algunas limitaciones. La reconfiguración también depende de Raft, por lo que, para añadir o eliminar un nodo del clúster, necesitas tener quórum. Si pierdes demasiados nodos del clúster al mismo tiempo y no hay posibilidad de volver a iniciarlos, Raft dejará de funcionar y no te permitirá reconfigurar el clúster de la forma convencional. No obstante, ClickHouse Keeper tiene un modo de recuperación que te permite reconfigurar el clúster de forma forzada con solo 1 nodo. Esto debe hacerse solo como último recurso si no puedes volver a iniciar los nodos o arrancar una nueva instancia en el mismo endpoint. Aspectos importantes que debes tener en cuenta antes de continuar:
  • Asegúrate de que los nodos fallidos no puedan volver a conectarse al clúster.
  • No inicies ninguno de los nodos nuevos hasta que se indique en los pasos.
Una vez que hayas confirmado lo anterior, debes hacer lo siguiente:
  1. Elige un único nodo de Keeper para que sea tu nuevo líder. Ten en cuenta que los datos de ese nodo se usarán para todo el clúster, por lo que recomendamos usar un nodo con el estado más actualizado.
  2. Antes de hacer cualquier otra cosa, haz una copia de seguridad de las carpetas log_storage_path y snapshot_storage_path del nodo elegido.
  3. Reconfigura el clúster en todos los nodos que quieras usar.
  4. Envía el comando de cuatro letras rcvr al nodo que elegiste, lo que pondrá ese nodo en modo de recuperación, O bien detén la instancia de Keeper en el nodo elegido y vuelve a iniciarla con el argumento --force-recovery.
  5. Uno por uno, inicia las instancias de Keeper en los nodos nuevos y asegúrate de que mntr devuelva follower para zk_server_state antes de iniciar el siguiente.
  6. Mientras esté en modo de recuperación, el nodo líder devolverá un mensaje de error para el comando mntr hasta que alcance quórum con los nodos nuevos, y rechazará cualquier solicitud del cliente y de los seguidores.
  7. Cuando se alcance el quórum, el nodo líder volverá al modo de funcionamiento normal y aceptará todas las solicitudes usando Raft; verifícalo con mntr, que debería devolver leader para zk_server_state.

​
Uso de discos con Keeper

Keeper admite un subconjunto de discos externos para almacenar instantáneas, archivos de registro y el archivo de estado. Los tipos de discos compatibles son:
  • s3_plain
  • s3
  • local
A continuación se muestra un ejemplo de definiciones de discos incluidas en una configuración.
Para usar un disco para los logs, la configuración keeper_server.log_storage_disk debe establecerse con el nombre del disco. Para usar un disco para las instantáneas, la configuración keeper_server.snapshot_storage_disk debe establecerse con el nombre del disco. Además, keeper_server.latest_log_storage_disk puede usarse para los logs más recientes y keeper_server.latest_snapshot_storage_disk para las instantáneas más recientes. En ese caso, Keeper moverá automáticamente los archivos a los discos correspondientes cuando se creen nuevos logs o instantáneas. Para usar un disco para el archivo de estado, la configuración keeper_server.state_storage_disk debe establecerse con el nombre del disco. Mover archivos entre discos es seguro y no hay riesgo de pérdida de datos si Keeper se detiene en mitad de la transferencia. Hasta que el archivo se haya movido por completo al nuevo disco, no se elimina del disco anterior. Keeper con keeper_server.coordination_settings.force_sync establecido en true (true de forma predeterminada) no puede ofrecer ciertas garantías en todos los tipos de disco. En este momento, solo los discos de tipo local admiten sincronización persistente. Si se usa force_sync, log_storage_disk debe ser un disco local si no se usa latest_log_storage_disk. Si se usa latest_log_storage_disk, siempre debe ser un disco local. Si force_sync está deshabilitado, pueden usarse discos de cualquier tipo en cualquier configuración. Una posible configuración de almacenamiento para una instancia de Keeper podría ser la siguiente:
Esta instancia almacenará todos los logs, salvo el más reciente, en el disco log_s3_plain, mientras que el log más reciente estará en el disco log_local. La misma lógica se aplica a las instantáneas: todas las instantáneas, salvo la más reciente, se almacenarán en snapshot_s3_plain, mientras que la instantánea más reciente estará en el disco snapshot_local.

​
Cambio de la configuración de discos

Antes de aplicar una nueva configuración de discos, haga manualmente una copia de seguridad de todos los logs y las instantáneas de Keeper.
Si se define una configuración de discos por niveles (usando discos independientes para los archivos más recientes), Keeper intentará mover automáticamente los archivos a los discos correctos al iniciarse. Se mantiene la misma garantía que antes: hasta que el archivo se haya movido por completo al nuevo disco, no se elimina del disco anterior, por lo que se pueden realizar varios reinicios de forma segura. Si es necesario mover archivos a un disco completamente nuevo (o pasar de una configuración de 2 discos a una de un solo disco), es posible usar varias definiciones de keeper_server.old_snapshot_storage_disk y keeper_server.old_log_storage_disk. La siguiente configuración muestra cómo pasar de la configuración anterior de 2 discos a una configuración completamente nueva de un solo disco:
Al arrancar, todos los archivos de registro se moverán de log_local y log_s3_plain al disco log_local2. Además, todos los archivos de instantánea se moverán de snapshot_local y snapshot_s3_plain al disco snapshot_local2.

​
Configuración de la caché de registros

Para minimizar la cantidad de datos leídos del disco, Keeper almacena en caché las entradas de registro en memoria. Si las solicitudes son grandes, las entradas de registro consumirán demasiada memoria, por lo que se limita la cantidad de registros almacenados en caché. Los límites de la caché de los registros más recientes se controlan mediante:
  • latest_logs_cache_size_threshold - memoria ocupada por los registros más recientes almacenados en caché
  • latest_logs_cache_entry_count_threshold - cuántas entradas puede contener la caché
El límite que se alcance primero restringe la caché; si se establece uno en 0, solo queda vigente el otro. El umbral de tamaño contabiliza la memoria que realmente ocupa una entrada en caché, no solo el tamaño de la propia entrada de registro: cada entrada en caché también incluye los objetos que la mantienen accesible, y su asignación se redondea al alza hasta una clase de tamaño del allocator. Para entradas pequeñas, ese overhead es varias veces el tamaño de la entrada, por lo que el número de entradas que la caché puede contener puede ser mucho menor de lo que sugiere dividir el umbral entre el tamaño de la entrada. KeeperLatestLogsCacheSize informa de la misma cantidad que el umbral limita. Si los valores predeterminados son demasiado altos, puede reducir el uso de memoria disminuyendo estas configuraciones. Las entradas de registro necesarias para el siguiente commit se sirven mediante un lector de lectura anticipada decodificado, cuyo tamaño se define mediante log_readahead_commit_window_bytes (0 desactiva la lectura anticipada para commits). Esta configuración reemplaza las configuraciones obsoletas commit_logs_cache_size_threshold y commit_logs_cache_entry_count_threshold, que se mantienen únicamente por compatibilidad de configuración (la primera sigue asignándose a log_readahead_commit_window_bytes si no se ha definido; la segunda no tiene ningún efecto). El mismo mecanismo de lectura anticipada también atiende las lecturas de puesta al día de la replicación de seguidores cuando log_readahead_enabled es true; consulte log_readahead_window_bytes, log_readahead_max_peer_readers, log_readahead_eviction_timeout_ms, log_readahead_pool_threads, log_readahead_serve_wait_timeout_ms y log_readahead_chunk_size en la configuración de coordinación interna para conocer los parámetros de ajuste del lado del par.
Puede usar el comando pfev para comprobar la cantidad de registros leídos de cada caché y de un archivo. También puede usar las métricas del endpoint de Prometheus para realizar un seguimiento del tamaño actual de ambas cachés.

​
Prometheus

Keeper puede exponer datos de métricas para su recopilación por Prometheus. Ajustes:
  • endpoint – endpoint HTTP para la recopilación de métricas por parte del servidor Prometheus. Debe comenzar con ’/’.
  • port – Puerto de endpoint.
  • metrics – Indicador que habilita la exposición de métricas de la tabla system.metrics.
  • events – Indicador que habilita la exposición de métricas de la tabla system.events.
  • asynchronous_metrics – Indicador que habilita la exposición de los valores actuales de las métricas de la tabla system.asynchronous_metrics.
Ejemplo
Verifique (reemplace 127.0.0.1 por la dirección IP o el nombre de host de su servidor de ClickHouse):
Consulte también la integración de Prometheus de ClickHouse Cloud.

​
Guía de usuario de ClickHouse Keeper

Esta guía proporciona una configuración sencilla y mínima para ClickHouse Keeper, con un ejemplo de cómo probar operaciones distribuidas. Este ejemplo se realiza con 3 nodos en Linux.
1

Configure los nodos con la configuración de Keeper

  1. Instale 3 instancias de ClickHouse en 3 hosts (chnode1, chnode2, chnode3). (Consulte la Quick Start para obtener más información sobre cómo instalar ClickHouse.)
  2. En cada nodo, agregue la siguiente entrada para permitir la comunicación externa a través de la interfaz de red.
  3. Añada la siguiente configuración de ClickHouse Keeper a los tres servidores y actualice el parámetro <server_id> en cada uno; para chnode1 sería 1, chnode2 sería 2, etc.
    Estos son los ajustes básicos utilizados más arriba:
  4. Habilite el componente Zookeeper. Utilizará el motor ClickHouse Keeper:
    Estos son los ajustes básicos utilizados más arriba:
  5. Reinicie ClickHouse y verifique que cada instancia de Keeper esté en funcionamiento. Ejecute el siguiente comando en cada servidor. El comando ruok devuelve imok si Keeper se está ejecutando y está en buen estado:
  6. La base de datos system tiene una tabla llamada zookeeper que contiene los detalles de las instancias de ClickHouse Keeper. Veamos la tabla:
    La tabla se ve así:
2

Configurar un clúster en ClickHouse

  1. Configuremos un clúster simple con 2 segmentos y solo una réplica en 2 de los nodos. El tercer nodo se utilizará para alcanzar el quórum requerido en ClickHouse Keeper. Actualice la configuración en chnode1 y chnode2. El siguiente clúster define 1 segmento en cada nodo, para un total de 2 segmentos sin replicación. En este ejemplo, parte de los datos estará en un nodo y otra parte estará en el otro nodo:
  2. Reinicie ClickHouse y verifique que el clúster se haya creado:
    Debería ver su clúster:
3

Crear y probar una tabla distribuida

  1. Cree una nueva base de datos en el nuevo clúster con ClickHouse client en chnode1. La cláusula ON CLUSTER crea automáticamente la base de datos en ambos nodos.
  2. Cree una nueva tabla en la base de datos db1. Una vez más, ON CLUSTER crea la tabla en ambos nodos.
  3. En el nodo chnode1, agregue un par de filas:
  4. Agregue un par de filas en el nodo chnode2:
  5. Tenga en cuenta que ejecutar una instrucción SELECT en cada nodo solo muestra los datos de ese nodo. Por ejemplo, en chnode1:
    En chnode2:
  7. Puede crear una tabla Distributed para representar los datos de los dos segmentos. Las tablas con el motor de tabla Distributed no almacenan datos propios, pero permiten el procesamiento distribuido de consultas en varios servidores. Las lecturas abarcan todos los segmentos, y las escrituras pueden distribuirse entre ellos. Ejecute la siguiente consulta en chnode1:
  8. Observe que consultar dist_table devuelve las cuatro filas de datos de los dos segmentos:

​
Resumen

En esta guía se mostró cómo configurar un clúster con ClickHouse Keeper. Con ClickHouse Keeper, puede configurar clústeres y definir tablas distribuidas que pueden replicarse entre segmentos.

​
Configuración de ClickHouse Keeper con rutas únicas

Esta página no se aplica a ClickHouse Cloud. El procedimiento que se documenta aquí está automatizado en los servicios de ClickHouse Cloud.

​
Descripción

Este artículo describe cómo usar la configuración integrada de la macro {uuid} para crear entradas únicas en ClickHouse Keeper o ZooKeeper. Las rutas únicas son útiles cuando se crean y eliminan tablas con frecuencia, porque evitan tener que esperar varios minutos a que la recolección de basura de Keeper elimine las entradas de ruta, ya que cada vez que se crea una ruta se utiliza un nuevo uuid en ella; las rutas nunca se reutilizan.

​
Entorno de ejemplo

Un clúster de tres nodos que se configurará para ejecutar ClickHouse Keeper en los tres nodos y ClickHouse en dos de ellos. Esto proporciona a ClickHouse Keeper tres nodos (incluido un nodo de desempate) y un único segmento de ClickHouse compuesto por dos réplicas. Configuración de ejemplo para el clúster:

​
Procedimiento para configurar tablas para usar {uuid}

  1. Configure las macros en cada servidor ejemplo para el servidor 1:
Tenga en cuenta que definimos macros para shard y replica, pero {uuid} no está definido aquí; viene integrado y no es necesario definirlo.
  1. Crear una base de datos
  1. Cree una tabla en el clúster usando las macros y {uuid}
  1. Cree una tabla distribuida

​
Prueba

  1. Inserte datos en el primer nodo (p. ej., chnode1)
  1. Insertar datos en el segundo nodo (p. ej., chnode2)
  1. Ver registros mediante una tabla distribuida

​
Alternativas

La ruta de replicación predeterminada puede definirse de antemano mediante macros, usando también {uuid}
  1. Configure el valor predeterminado para las tablas en cada nodo
También puede definir una macro {database} en cada nodo si se usan nodos para determinadas bases de datos.
  1. Cree la tabla sin parámetros explícitos:
  1. Verifique que se haya utilizado la misma configuración que en la configuración predeterminada

​
Solución de problemas

Comando de ejemplo para obtener información de la tabla y el UUID:
Comando de ejemplo para obtener información sobre la tabla en ZooKeeper con el UUID de la tabla anterior
La base de datos debe ser Atomic; si está actualizando desde una versión anterior, es probable que la base de datos default sea de tipo Ordinary.
Para comprobarlo: Por ejemplo,

​
Reconfiguración dinámica de ClickHouse Keeper

Esta página no se aplica a ClickHouse Cloud. El procedimiento que se documenta aquí está automatizado en los servicios de ClickHouse Cloud.

​
Descripción

ClickHouse Keeper admite parcialmente el comando reconfig de ZooKeeper para la reconfiguración dinámica del clúster si keeper_server.enable_reconfiguration está habilitado.
Si esta configuración está deshabilitada, puede reconfigurar el clúster modificando manualmente la sección raft_configuration de la réplica. Asegúrese de editar los archivos en todas las réplicas, ya que solo el líder aplicará los cambios. Como alternativa, puede enviar una consulta reconfig a través de cualquier cliente compatible con ZooKeeper.
Un nodo virtual /keeper/config contiene la última configuración del clúster confirmada con el siguiente formato:
  • Cada entrada de servidor está delimitada por un salto de línea.
  • server_type es participant o learner (learner no participa en las elecciones de líder).
  • server_priority es un entero no negativo que indica qué nodos deben tener prioridad en las elecciones de líder. Una prioridad de 0 significa que el servidor nunca será líder.
Ejemplo:
Puede utilizar el comando reconfig para añadir nuevos servidores, eliminar los existentes y cambiar la prioridad de los servidores existentes; a continuación se muestran algunos ejemplos (con clickhouse-keeper-client):
Y aquí tienes ejemplos de kazoo:
Los servidores en joining deben estar en el formato de servidor descrito anteriormente. Las entradas de servidor deben estar delimitadas por comas. Al añadir nuevos servidores, puede omitir server_priority (el valor predeterminado es 1) y server_type (el valor predeterminado es participant). Si quiere cambiar la prioridad de un servidor existente, añádalo a joining con la prioridad de destino. El host, el puerto y el tipo del servidor deben coincidir con la configuración existente del servidor. Los servidores se añaden y se eliminan en el orden en que aparecen en joining y leaving. Todas las actualizaciones de joining se procesan antes que las actualizaciones de leaving. Hay algunas consideraciones que tener en cuenta en la implementación de la reconfiguración de Keeper:
  • Solo se admite la reconfiguración incremental. Se rechazan las solicitudes con new_members no vacío. La implementación de ClickHouse Keeper se basa en la API de NuRaft para cambiar la composición del clúster de forma dinámica. NuRaft permite añadir un solo servidor o eliminar un solo servidor, de uno en uno. Esto significa que cada cambio en la configuración (cada parte de joining, cada parte de leaving) debe decidirse por separado. Por lo tanto, no hay reconfiguración en bloque, ya que resultaría engañosa para los usuarios finales. Tampoco es posible cambiar el tipo de servidor (participant/learner), ya que NuRaft no lo admite, y la única forma sería eliminar y volver a añadir el servidor, lo que de nuevo sería engañoso.
  • No puede usar el valor znodestat devuelto.
  • El campo from_version no se usa. Se rechazan todas las solicitudes con from_version establecido. Esto se debe a que /keeper/config es un nodo virtual, lo que significa que no se almacena en almacenamiento persistente, sino que se genera sobre la marcha con la configuración del nodo especificado para cada solicitud. Esta decisión se tomó para no duplicar datos, ya que NuRaft ya almacena esta configuración.
  • A diferencia de ZooKeeper, no hay forma de esperar a que se complete la reconfiguración del clúster enviando un comando sync. La nueva configuración se aplicará con el tiempo, pero sin garantías de plazo.
  • El comando reconfig puede fallar por varios motivos. Puede comprobar el estado del clúster y ver si la actualización se aplicó.

​
Convertir un keeper de un solo nodo en un clúster

A veces es necesario ampliar un nodo keeper experimental hasta convertirlo en un clúster. A continuación se muestra un esquema de cómo hacerlo paso a paso para un clúster de 3 nodos:
  • IMPORTANTE: los nodos nuevos deben añadirse en lotes inferiores al quórum actual; de lo contrario, elegirán un líder entre ellos. En este ejemplo, se añaden de uno en uno.
  • El nodo keeper existente debe tener habilitado el parámetro de configuración keeper_server.enable_reconfiguration.
  • Inicia un segundo nodo con la nueva configuración completa del clúster de keeper.
  • Una vez iniciado, añádelo al nodo 1 mediante reconfig.
  • A continuación, inicia un tercer nodo y añádelo mediante reconfig.
  • Actualiza la configuración de clickhouse-server añadiendo el nuevo nodo keeper y reinícialo para aplicar los cambios.
  • Actualiza la configuración de Raft del nodo 1 y, opcionalmente, reinícialo.
Para familiarizarte con el proceso, aquí tienes un repositorio sandbox.

​
Funciones no compatibles

Aunque ClickHouse Keeper pretende ser totalmente compatible con ZooKeeper, hay algunas funciones que aún no están implementadas (aunque el desarrollo sigue en curso):
Última modificación el 28 de septiembre de 2026