Passer au contenu principal
Cette page ne concerne pas ClickHouse Cloud. La procédure décrite ici est automatisée dans les services ClickHouse Cloud.
ClickHouse Keeper fournit le système de coordination pour la réplication des données et l’exécution des requêtes distributed DDL. ClickHouse Keeper est compatible avec ZooKeeper.

​
Détails d’implémentation

ZooKeeper est l’un des premiers systèmes de coordination open source largement connus. Il est implémenté en Java et s’appuie sur un modèle de données simple et puissant. L’algorithme de coordination de ZooKeeper, ZooKeeper Atomic Broadcast (ZAB), n’offre pas de garanties de linéarisabilité pour les lectures, car chaque nœud ZooKeeper traite les lectures localement. Contrairement à ZooKeeper, ClickHouse Keeper est écrit en C++ et utilise l’algorithme RAFT et son implémentation. Cet algorithme permet la linéarisabilité des lectures et des écritures, et possède plusieurs implémentations open source dans différents langages. Par défaut, ClickHouse Keeper offre les mêmes garanties que ZooKeeper : des écritures linéarisables et des lectures non linéarisables. Il dispose d’un protocole client-serveur compatible, de sorte que n’importe quel client ZooKeeper standard peut être utilisé pour interagir avec ClickHouse Keeper. Les snapshots et les logs ont un format incompatible avec ZooKeeper, mais l’outil clickhouse-keeper-converter permet de convertir les données ZooKeeper en snapshots ClickHouse Keeper. Le protocole interserver de ClickHouse Keeper est lui aussi incompatible avec ZooKeeper ; un cluster mixte ZooKeeper / ClickHouse Keeper est donc impossible. ClickHouse Keeper prend en charge les listes de contrôle d’accès (ACL) de la même manière que ZooKeeper. ClickHouse Keeper prend en charge le même ensemble de permissions et dispose des mêmes schémas intégrés : world, auth et digest. Le schéma d’authentification digest utilise la paire username:password ; le mot de passe est encodé en Base64.
Les intégrations externes ne sont pas prises en charge.

​
Configuration

ClickHouse Keeper peut être utilisé comme alternative autonome à ZooKeeper ou comme composant interne de serveur ClickHouse. Dans les deux cas, le fichier de configuration .xml est quasiment le même.

​
Paramètres de configuration de Keeper

La balise principale de configuration de ClickHouse Keeper est <keeper_server> et comporte les paramètres suivants : Les autres paramètres courants sont hérités de la config du serveur ClickHouse (listen_host, logger, etc.).

​
Paramètres de coordination interne

Les paramètres de coordination interne se trouvent dans la section <keeper_server>.<coordination_settings> et comprennent les paramètres suivants : La configuration du quorum se trouve dans la section <keeper_server>.<raft_configuration> et contient la description des servers. Le seul paramètre pour l’ensemble du quorum est secure, qui active une connection chiffrée pour la communication entre les participants du quorum. Le paramètre peut être défini sur true si une connection SSL est requise pour la communication interne entre les nœuds, ou laissé non spécifié dans le cas contraire. Les principaux paramètres de chaque <server> sont :
  • id — Identifiant du serveur dans un quorum.
  • hostname — Nom d’hôte où ce serveur est hébergé.
  • port — Port sur lequel ce serveur écoute les connexions.
  • can_become_leader — Définissez false pour configurer le serveur comme learner. Si ce paramètre est omis, la valeur est true.
En cas de modification de la topologie de votre cluster ClickHouse Keeper (par ex., remplacement d’un serveur), veillez à conserver une association cohérente entre server_id et hostname, et évitez de permuter ou de réutiliser un server_id existant pour différents serveurs (par ex., cela peut se produire si vous utilisez des scripts d’automatisation pour déployer ClickHouse Keeper)Si l’hôte d’une instance Keeper est susceptible de changer, nous recommandons de définir et d’utiliser un nom d’hôte plutôt que des adresses IP brutes. Modifier le nom d’hôte revient à supprimer le serveur puis à l’ajouter de nouveau, ce qui peut dans certains cas être impossible (par ex., s’il n’y a pas assez d’instances Keeper pour atteindre le quorum).
async_replication est désactivé par défaut afin d’éviter de rompre la compatibilité descendante. Si toutes les instances Keeper de votre cluster exécutent une version prenant en charge async_replication (v23.9+), nous recommandons de l’activer, car cela peut améliorer les performances sans aucun inconvénient.
Des exemples de configuration pour un quorum à trois nœuds sont disponibles dans les tests d’intégration avec le préfixe test_keeper_. Exemple de configuration pour le serveur #1 :

​
Comment l’exécuter

ClickHouse Keeper est inclus dans le paquet du serveur ClickHouse ; il vous suffit d’ajouter la configuration de <keeper_server> à votre fichier /etc/your_path_to_config/clickhouse-server/config.xml et de démarrer le serveur ClickHouse comme d’habitude. Si vous souhaitez exécuter ClickHouse Keeper en mode standalone, vous pouvez le démarrer de manière similaire avec :
Si vous ne disposez pas du lien symbolique (clickhouse-keeper), vous pouvez le créer ou passer keeper en argument à clickhouse :

​
Commandes à quatre lettres

ClickHouse Keeper fournit également des commandes 4lw, presque identiques à celles de ZooKeeper. Chaque commande se compose de quatre lettres, comme mntr, stat, etc. Parmi les commandes les plus utiles : stat fournit des informations générales sur le serveur et les clients connectés, srvr fournit des détails supplémentaires sur le serveur, et cons fournit des détails supplémentaires sur les connexions. Les commandes 4lw utilisent une configuration de liste blanche, four_letter_word_white_list, dont la valeur par défaut est conf,cons,crst,envi,ruok,srst,srvr,stat,wchs,dirs,mntr,isro,rcvr,apiv,csnp,lgif,rqld,ydld. Vous pouvez envoyer ces commandes à ClickHouse Keeper via telnet ou nc, sur le port client.
Vous trouverez ci-dessous les commandes 4lw détaillées :
  • ruok : teste si le serveur est en cours de fonctionnement et ne se trouve pas dans un état d’erreur. Le serveur répond par imok s’il est en cours d’exécution. Sinon, il ne répond pas du tout. Une réponse imok n’indique pas nécessairement que le serveur a rejoint le quorum, mais seulement que le processus serveur est actif et lié au port client spécifié. Utilisez “stat” pour obtenir des détails sur l’état vis-à-vis du quorum et les informations de connexion du client.
  • mntr : affiche une liste de variables pouvant être utilisées pour surveiller l’état du cluster.
  • srvr : affiche les informations détaillées du serveur.
  • stat : Affiche des informations succinctes sur le serveur et les clients connectés.
  • srst : Réinitialise les statistiques du serveur. Cette commande a une incidence sur le résultat de srvr, mntr et stat.
  • conf : Affiche des détails sur la configuration du service.
  • cons : Répertorie les informations détaillées sur la connexion/session de tous les clients connectés à ce serveur. Inclut des informations sur le nombre de paquets reçus/envoyés, l’identifiant de session, les latences des opérations, la dernière opération effectuée, etc…
  • crst : Réinitialise les statistiques de connexion et de session pour toutes les connexions.
  • envi: Afficher les détails de l’environnement d’exécution
  • dirs : Affiche la taille totale des snapshots et des fichiers de log, en octets
  • isro : vérifie si le serveur est en mode lecture seule. Le serveur renvoie ro s’il est en mode lecture seule, ou rw dans le cas contraire.
  • wchs : Affiche de brèves informations sur les watches du serveur.
  • wchc : Liste les informations détaillées sur les watches du serveur, par session. Cette commande affiche une liste de sessions (connexions) avec les watches associées (chemins). Notez que, selon le nombre de watches, cette opération peut être coûteuse (et affecter les performances du serveur) ; utilisez-la avec précaution.
  • wchp : répertorie des informations détaillées sur les watches du serveur, par chemin. La commande renvoie une liste de chemins (znodes) avec les sessions associées. Notez que, selon le nombre de watches, cette opération peut être coûteuse (c.-à-d. affecter les performances du serveur) ; utilisez-la avec précaution.
  • dump : répertorie les sessions ouvertes et les nœuds éphémères. Cette commande fonctionne uniquement sur le leader.
  • csnp : planifie une tâche de création de snapshot. Renvoie le dernier index de journal validé du snapshot planifié en cas de succès, ou Failed to schedule snapshot creation task. en cas d’échec. La commande lgif peut vous aider à déterminer si le snapshot est terminé.
  • lgif : Informations sur le journal de Keeper. first_log_idx : mon premier index de journal dans le stockage de journaux ; first_log_term : mon premier terme de journal ; last_log_idx : mon dernier index de journal dans le stockage de journaux ; last_log_term : mon dernier terme de journal ; last_committed_log_idx : mon dernier index de journal validé dans la machine à états ; leader_committed_log_idx : l’index de journal validé du leader, de mon point de vue ; target_committed_log_idx : l’index de journal cible qui doit être validé ; last_snapshot_idx : le plus grand index de journal validé dans le dernier snapshot.
  • rqld : Demande pour devenir le nouveau leader. Renvoie Sent leadership request to leader. si la demande est envoyée, ou Failed to send leadership request to leader. si l’envoi de la demande échoue. Si le nœud est déjà leader, le résultat est le même que lorsque la demande est envoyée.
  • ftfl : dresse la liste de tous les feature flags et indique s’ils sont activés pour l’instance Keeper.
  • ydld : requête visant à abandonner le rôle de leader pour devenir follower. Si le serveur qui reçoit la requête est leader, il suspend d’abord les opérations d’écriture, attend que le successeur (le leader actuel ne peut jamais être le successeur) ait terminé le rattrapage du journal le plus récent, puis se retire. Le successeur est choisi automatiquement. Renvoie Sent yield leadership request to leader. si la requête a été envoyée, ou Failed to send yield leadership request to leader. si elle ne l’a pas été. Si le nœud est déjà follower, le résultat est le même que si la requête avait été envoyée.
  • pfev : renvoie les valeurs de tous les événements collectés. Pour chaque événement, la fonction renvoie son nom, sa valeur et sa description.

​
Contrôle HTTP

ClickHouse Keeper fournit une interface HTTP permettant de vérifier si une réplique est prête à recevoir du trafic. Elle peut être utilisée dans des environnements cloud, comme Kubernetes. Exemple de configuration activant le point de terminaison /ready :

​
Feature flags

Keeper est entièrement compatible avec ZooKeeper et ses clients, mais il introduit également certaines fonctionnalités et certains types de requêtes spécifiques qui peuvent être utilisés par le client ClickHouse. Comme ces fonctionnalités peuvent entraîner des changements incompatibles avec les versions précédentes, la plupart sont désactivées par défaut et peuvent être activées à l’aide de la config keeper_server.feature_flags. Toutes les fonctionnalités peuvent aussi être désactivées explicitement. Si vous souhaitez activer une nouvelle fonctionnalité pour votre cluster Keeper, nous vous recommandons de commencer par mettre à jour toutes les instances Keeper du cluster vers une version qui prend en charge cette fonctionnalité, puis d’activer la fonctionnalité elle-même. Exemple de config de feature flag qui désactive multi_read et active check_not_exists :
Les fonctionnalités suivantes sont disponibles :
Certains feature flags sont activés par défaut à partir de la version 25.7. La méthode recommandée pour mettre à niveau Keeper vers la version 25.7+ consiste à commencer par effectuer la mise à niveau vers la version 24.9+.

​
Migration depuis ZooKeeper

Une migration fluide de ZooKeeper vers ClickHouse Keeper n’est pas possible. Vous devez arrêter votre cluster ZooKeeper, convertir les données, puis démarrer ClickHouse Keeper. L’outil clickhouse-keeper-converter convertit les logs et snapshots ZooKeeper en un snapshot ClickHouse Keeper. Il nécessite ZooKeeper 3.4 ou une version ultérieure.

​
Préparation avant la migration

La migration nécessite d’interrompre l’ingestion des données. Prévoyez une fenêtre de maintenance avant de commencer. Avant d’arrêter ZooKeeper, stoppez les tâches d’arrière-plan de ClickHouse qui modifient les métadonnées de coordination. Par exemple :
Consignez des métriques de comparaison avant la migration afin de pouvoir vérifier la cohérence ensuite.

​
Étapes de la migration

  1. Arrêtez l’ingestion de données sur tous les nœuds ClickHouse.
  2. Arrêtez toutes les tâches en arrière-plan sur tous les nœuds ClickHouse (voir ci-dessus).
  3. Arrêtez tous les nœuds ZooKeeper.
  4. Facultatif, mais recommandé : identifiez le nœud leader de ZooKeeper, démarrez-le, puis arrêtez-le à nouveau. Cela force ZooKeeper à écrire un snapshot cohérent sur le disque avant la conversion.
  5. Exécutez clickhouse-keeper-converter sur le nœud leader. Si vous avez installé le binaire complet de ClickHouse, utilisez plutôt la sous-commande keeper-converter (clickhouse keeper-converter). Si aucun des deux n’est disponible, téléchargez le binaire.
  1. Copiez le snapshot sur tous les nœuds ClickHouse Keeper. Le snapshot doit être présent sur chaque nœud avant qu’aucun nœud ne démarre — si un nœud démarre sans snapshot, il peut s’élire leader avec un état vide.
  2. Mettez à jour votre configuration ClickHouse afin qu’elle pointe vers le nouveau cluster Keeper.
  3. Démarrez ClickHouse Keeper sur tous les nœuds, puis redémarrez ClickHouse.
  4. Comparez les métriques à votre référence pré-migration pour vérifier leur cohérence.
  5. Reprenez les tâches en arrière-plan et redémarrez l’ingestion des données.

​
Consolidation de plusieurs clusters ZooKeeper

Si vous exécutez plusieurs clusters ZooKeeper — par exemple, un par groupe de shards — vous pouvez les consolider en un seul cluster ClickHouse Keeper. L’outil officiel clickhouse-keeper-converter ne prend en charge que les conversions un à un (un cluster ZooKeeper vers un snapshot Keeper) ; la consolidation exige donc de modifier le code source du convertisseur pour fusionner plusieurs snapshots :
  1. Exécutez clickhouse-keeper-converter séparément sur chaque cluster ZooKeeper, en enregistrant chaque sortie dans un répertoire distinct.
  2. Désérialisez les fichiers de snapshot successivement. Lors de la fusion, recalculez les valeurs numChildren pour éviter les conflits d’ID de nœud entre les espaces de noms provenant de différents clusters source.
  3. Écrivez la sortie fusionnée dans le répertoire cible des snapshots ClickHouse Keeper.

​
Gestion du chiffrement et des ACL

ClickHouse Keeper prend en charge les mêmes schémas d’ACL que ZooKeeper (world, auth, digest). La façon de gérer les ACL pendant la conversion dépend de votre configuration ZooKeeper :
  • Entièrement chiffré ou entièrement non chiffré : convertissez directement. Le convertisseur conserve les informations d’ACL existantes.
  • Partiellement chiffré : avant la conversion, accordez des privilèges de super-administrateur à un compte, puis supprimez les ACL avec setAcl -R sur les chemins concernés. Convertissez, puis réactivez le chiffrement dans ClickHouse Keeper si nécessaire.

​
Vérification de la migration

Après avoir démarré ClickHouse Keeper et redémarré ClickHouse, comparez vos métriques clés au niveau de référence d’avant la migration pour confirmer que celle-ci a réussi. Lors de la consolidation de plusieurs clusters ZooKeeper, faites la distinction entre :
  • Chemins communs : chemins présents dans plusieurs clusters sources avec des données identiques — ils doivent être dédupliqués dans la sortie fusionnée.
  • Chemins distincts : chemins qui n’existent que dans des clusters spécifiques (par exemple, sous /clickhouse/tables pour chaque groupe de shards) — ils doivent être conservés depuis la source appropriée.
Évitez de parcourir directement de grands arbres ZooKeeper pour les comparer. À la place, écrivez tous les chemins convertis dans un fichier pendant la conversion.

​
Ajustements après migration

Après la migration, pensez à ajuster ces paramètres pour les clusters de plus grande taille ou un débit plus élevé : Ces paramètres se configurent sous coordination_settings dans votre configuration de Keeper.

​
Récupération après la perte du quorum

Comme ClickHouse Keeper utilise Raft, il peut tolérer un certain nombre de pannes de nœuds en fonction de la taille du cluster. Par exemple, pour un cluster de 3 nœuds, il continuera à fonctionner correctement si un seul nœud tombe en panne. La configuration du cluster peut être modifiée dynamiquement, mais il existe certaines limitations. La reconfiguration repose elle aussi sur Raft. Ainsi, pour ajouter ou supprimer un nœud du cluster, vous devez disposer d’un quorum. Si vous perdez trop de nœuds de votre cluster en même temps, sans possibilité de les redémarrer, Raft cessera de fonctionner et ne vous permettra plus de reconfigurer votre cluster de manière classique. Néanmoins, ClickHouse Keeper dispose d’un mode de récupération qui vous permet de reconfigurer de force votre cluster avec un seul nœud. Vous ne devez y recourir qu’en dernier recours si vous ne pouvez pas redémarrer vos nœuds ni lancer une nouvelle instance sur le même point de terminaison. Points importants à noter avant de continuer :
  • Assurez-vous que les nœuds défaillants ne puissent plus se reconnecter au cluster.
  • Ne démarrez aucun des nouveaux nœuds tant que cela n’est pas indiqué dans les étapes.
Une fois ces points vérifiés, vous devez procéder comme suit :
  1. Choisissez un seul nœud Keeper pour en faire votre nouveau leader. Gardez à l’esprit que les données de ce nœud seront utilisées pour l’ensemble du cluster. Nous vous recommandons donc d’utiliser un nœud dont l’état est le plus à jour possible.
  2. Avant toute autre action, effectuez une sauvegarde des répertoires log_storage_path et snapshot_storage_path du nœud sélectionné.
  3. Reconfigurez le cluster sur tous les nœuds que vous souhaitez utiliser.
  4. Envoyez la commande à quatre lettres rcvr au nœud choisi, ce qui fera passer le nœud en mode de récupération, OU arrêtez l’instance Keeper sur le nœud choisi et redémarrez-la avec l’argument --force-recovery.
  5. Démarrez ensuite, un par un, les instances Keeper sur les nouveaux nœuds, en vous assurant que mntr renvoie follower pour zk_server_state avant de démarrer le suivant.
  6. En mode de récupération, le nœud leader renverra un message d’erreur pour la commande mntr jusqu’à ce qu’il atteigne le quorum avec les nouveaux nœuds, et il refusera toutes les requêtes du client et des followers.
  7. Une fois le quorum atteint, le nœud leader reviendra à un fonctionnement normal et acceptera toutes les requêtes via Raft ; vérifiez-le avec mntr, qui doit renvoyer leader pour zk_server_state.

​
Utiliser des disques avec Keeper

Keeper prend en charge un sous-ensemble des disques externes pour stocker les snapshot, les fichier de log et le fichier d’état. Les types de disques pris en charge sont :
  • s3_plain
  • s3
  • local
Voici un exemple de définitions de disques contenues dans une configuration.
Pour utiliser un disque pour les logs, le paramètre keeper_server.log_storage_disk doit être défini sur le nom du disque. Pour utiliser un disque pour les snapshot, le paramètre keeper_server.snapshot_storage_disk doit être défini sur le nom du disque. De plus, keeper_server.latest_log_storage_disk peut être utilisé pour les logs les plus récents et keeper_server.latest_snapshot_storage_disk pour les snapshot les plus récents. Dans ce cas, Keeper déplacera automatiquement les fichiers vers les disques appropriés lors de la création de nouveaux logs ou snapshot. Pour utiliser un disque pour le fichier d’état, le paramètre keeper_server.state_storage_disk doit être défini sur le nom du disque. Le déplacement de fichiers entre disques est sûr et il n’y a aucun risque de perte de données si Keeper s’arrête au milieu du transfert. Tant que le fichier n’a pas été entièrement déplacé vers le nouveau disque, il n’est pas supprimé de l’ancien. Lorsque keeper_server.coordination_settings.force_sync est défini sur true (true par défaut), Keeper ne peut pas garantir certaines propriétés pour tous les types de disques. À l’heure actuelle, seuls les disques de type local prennent en charge la synchronisation persistante. Si force_sync est utilisé, log_storage_disk doit être un disque local si latest_log_storage_disk n’est pas utilisé. Si latest_log_storage_disk est utilisé, il doit toujours être un disque local. Si force_sync est désactivé, des disques de tout type peuvent être utilisés dans n’importe quelle configuration. Voici à quoi pourrait ressembler une configuration de stockage possible pour une instance Keeper :
Cette instance stockera tous les logs, sauf les plus récents, sur le disque log_s3_plain, tandis que le log le plus récent sera stocké sur le disque log_local. La même logique s’applique aux snapshot : tous les snapshot, sauf les plus récents, seront stockés sur le disque snapshot_s3_plain, tandis que le snapshot le plus récent sera stocké sur le disque snapshot_local.

​
Modifier la configuration des disques

Avant d’appliquer une nouvelle configuration des disques, sauvegardez manuellement tous les logs et snapshots de Keeper.
Si une configuration de disques hiérarchisée est définie (avec des disques distincts pour les fichiers les plus récents), Keeper essaiera de déplacer automatiquement les fichiers vers les disques appropriés au démarrage. La même garantie s’applique que précédemment : tant que le fichier n’a pas été entièrement déplacé vers le nouveau disque, il n’est pas supprimé de l’ancien. Il est donc possible d’effectuer plusieurs redémarrages en toute sécurité. S’il est nécessaire de déplacer des fichiers vers un disque entièrement nouveau (ou de passer d’une configuration à 2 disques à une configuration à disque unique), il est possible d’utiliser plusieurs définitions de keeper_server.old_snapshot_storage_disk et keeper_server.old_log_storage_disk. La configuration suivante montre comment passer de la précédente configuration à 2 disques à une toute nouvelle configuration à disque unique :
Au démarrage, tous les fichiers de log seront déplacés depuis log_local et log_s3_plain vers le disque log_local2. De même, tous les fichiers d’instantané seront déplacés depuis snapshot_local et snapshot_s3_plain vers le disque snapshot_local2.

​
Configuration du cache des logs

Pour réduire la quantité de données lues sur le disque, Keeper met en cache les entrées de log en mémoire. Si les requêtes sont volumineuses, les entrées de log consomment trop de mémoire ; la quantité de logs mis en cache est donc plafonnée. Cette limite est définie par les deux configs suivantes :
  • latest_logs_cache_size_threshold - taille totale des logs les plus récents stockés dans le cache
  • commit_logs_cache_size_threshold - taille totale des logs suivants à valider
Si les valeurs par défaut sont trop élevées, vous pouvez réduire l’utilisation de la mémoire en diminuant ces deux configs.
Vous pouvez utiliser la commande pfev pour vérifier la quantité de logs lus à partir de chaque cache et d’un fichier. Vous pouvez également utiliser les métriques du Prometheus endpoint pour suivre la taille actuelle des deux caches.

​
Prometheus

Keeper peut exposer des métriques pour leur collecte par Prometheus. Paramètres :
  • endpoint – Endpoint HTTP de collecte des métriques par le serveur Prometheus. Doit commencer par ’/’.
  • port – Port de endpoint.
  • metrics – Indicateur qui active l’exposition des métriques de la table system.metrics.
  • events – Indicateur qui active l’exposition des métriques de la table system.events.
  • asynchronous_metrics – Indicateur qui active l’exposition des valeurs actuelles des métriques de la table system.asynchronous_metrics.
Exemple
Vérifiez (remplacez 127.0.0.1 par l’adresse IP ou le nom d’hôte de votre serveur ClickHouse) :
Voir aussi l’intégration Prometheus de ClickHouse Cloud.

​
Guide d’utilisation de ClickHouse Keeper

Ce guide présente une configuration simple et minimale de ClickHouse Keeper, ainsi qu’un exemple montrant comment tester des opérations distribuées. Cet exemple s’appuie sur 3 nœuds sous Linux.

​
1. Configurer les nœuds avec les paramètres Keeper

  1. Installez 3 instances de ClickHouse sur 3 hôtes (chnode1, chnode2, chnode3). (Consultez le Quick Start pour plus de détails sur l’installation de ClickHouse.)
  2. Sur chaque nœud, ajoutez l’entrée suivante pour permettre les communications externes via l’interface réseau.
  3. Ajoutez la configuration ClickHouse Keeper suivante sur les trois serveurs en mettant à jour le paramètre <server_id> pour chacun d’eux ; pour chnode1, la valeur serait 1, pour chnode2, ce serait 2, etc.
    Voici les paramètres de base utilisés ci-dessus :
  4. Activez le composant Zookeeper. Il utilisera le moteur ClickHouse Keeper :
    Voici les paramètres de base utilisés ci-dessus :
  5. Redémarrez ClickHouse et vérifiez que chaque instance de Keeper est en fonctionnement. Exécutez la commande suivante sur chaque serveur. La commande ruok renvoie imok si Keeper est en fonctionnement et sain :
  6. La base de données system comporte une table nommée zookeeper, qui contient les détails de vos instances ClickHouse Keeper. Affichons la table :
    Le tableau ressemble à ceci :

​
2. Configurer un cluster dans ClickHouse

  1. Configurons un cluster simple avec 2 shards et une seule réplique sur 2 des nœuds. Le troisième nœud sera utilisé pour atteindre le quorum requis par ClickHouse Keeper. Mettez à jour la configuration sur chnode1 et chnode2. Le cluster suivant définit 1 shard sur chaque nœud, pour un total de 2 shards sans réplication. Dans cet exemple, une partie des données sera sur un nœud et l’autre partie sur l’autre nœud :
  2. Redémarrez ClickHouse et vérifiez que le cluster a bien été créé :
    Vous devriez voir votre cluster :

​
3. Créer et tester une table distribuée

  1. Créez une nouvelle base de données sur le nouveau cluster à l’aide du client ClickHouse sur chnode1. La clause ON CLUSTER crée automatiquement la base de données sur les deux nœuds.
  2. Créez une nouvelle table dans la base de données db1. Là encore, ON CLUSTER crée la table sur les deux nœuds.
  3. Sur le nœud chnode1, ajoutez deux lignes :
  4. Ajoutez deux lignes sur le nœud chnode2 :
  5. Notez que l’exécution d’une instruction SELECT sur chaque nœud n’affiche que les données présentes sur ce nœud. Par exemple, sur chnode1 :
    Sur chnode2 :
  7. Vous pouvez créer une table Distributed pour représenter les données sur les deux shards. Les tables utilisant le moteur de table Distributed ne stockent pas leurs propres données, mais permettent le traitement distribué des requêtes sur plusieurs serveurs. Les lectures interrogent tous les shards, et les écritures peuvent être réparties entre les shards. Exécutez la requête suivante sur chnode1 :
  8. Notez qu’interroger dist_table renvoie les quatre lignes provenant des deux shards :

​
Résumé

Ce guide a montré comment configurer un cluster à l’aide de ClickHouse Keeper. Avec ClickHouse Keeper, vous pouvez configurer des clusters et définir des tables distribuées qui peuvent être répliquées sur plusieurs shards.

​
Configuration de ClickHouse Keeper avec des chemins uniques

Cette page ne concerne pas ClickHouse Cloud. La procédure décrite ici est automatisée dans les services ClickHouse Cloud.

​
Description

Cet article explique comment utiliser la macro intégrée {uuid} pour créer des entrées uniques dans ClickHouse Keeper ou ZooKeeper. Des chemins uniques sont utiles lorsque vous créez et supprimez des tables fréquemment, car cela évite d’avoir à attendre plusieurs minutes que le nettoyage automatique de Keeper supprime les entrées de chemin, puisque chaque fois qu’un chemin est créé, un nouveau uuid est utilisé dans ce chemin ; les chemins ne sont jamais réutilisés.

​
Environnement d’exemple

Un cluster à trois nœuds, configuré avec ClickHouse Keeper sur les trois nœuds et ClickHouse sur deux d’entre eux. Cela donne à ClickHouse Keeper trois nœuds (y compris un nœud d’arbitrage), ainsi qu’un seul shard ClickHouse composé de deux répliques. Exemple de configuration du cluster :

​
Procédures pour configurer les tables afin d’utiliser {uuid}

  1. Configurez les macros sur chaque serveur exemple pour le serveur 1 :
Notez que nous définissons des macros pour shard et replica, mais que {uuid} n’est pas défini ici — il est intégré et n’a pas besoin d’être défini.
  1. Créer une base de données
  1. Créez une table sur le cluster à l’aide des macros et de {uuid}
  1. Créez une table distribuée

​
Test

  1. Insérez des données dans le premier nœud (par exemple chnode1)
  1. Insérez des données sur le deuxième nœud (par ex., chnode2)
  1. Consulter les enregistrements à l’aide d’une table distribuée

​
Alternatives

Le chemin de réplication par défaut peut être défini à l’avance à l’aide de macros, en utilisant également {uuid}
  1. Définir le chemin par défaut pour les tables sur chaque nœud
Vous pouvez également définir une macro {database} sur chaque nœud si certains nœuds sont utilisés pour des bases de données spécifiques.
  1. Créez la table sans paramètres explicites :
  1. Vérifiez qu’il a bien repris les paramètres de la configuration par défaut

​
Dépannage

Exemple de commande pour obtenir des informations sur la table et son UUID :
Exemple de commande pour obtenir des informations sur la table dans ZooKeeper à l’aide de l’UUID de la table ci-dessus
La base de données doit être Atomic ; lors d’une mise à niveau depuis une version précédente, la base de données default est probablement de type Ordinary.
Pour vérifier : Par exemple,

​
Reconfiguration dynamique de ClickHouse Keeper

Cette page ne concerne pas ClickHouse Cloud. La procédure décrite ici est automatisée dans les services ClickHouse Cloud.

​
Description

ClickHouse Keeper prend en charge partiellement la commande ZooKeeper reconfig pour la reconfiguration dynamique du cluster si keeper_server.enable_reconfiguration est activé.
Si ce paramètre est désactivé, vous pouvez reconfigurer le cluster en modifiant manuellement la section raft_configuration de la réplique. Veillez à modifier les fichiers sur toutes les répliques, car seul le leader appliquera les modifications. Vous pouvez également envoyer une requête reconfig via n’importe quel client compatible avec ZooKeeper.
Un nœud virtuel /keeper/config contient la dernière configuration du cluster validée au format suivant :
Exemple :
Vous pouvez utiliser la commande reconfig pour ajouter de nouveaux serveurs, supprimer des serveurs existants et modifier la priorité de serveurs existants. Voici quelques exemples (avec clickhouse-keeper-client) :
Et voici des exemples pour kazoo :
Les serveurs dans joining doivent être au format de serveur décrit ci-dessus. Les entrées de serveur doivent être séparées par des virgules. Lors de l’ajout de nouveaux serveurs, vous pouvez omettre server_priority (la valeur par défaut est 1) et server_type (la valeur par défaut est participant). Si vous souhaitez modifier la priorité d’un serveur existant, ajoutez-le à joining avec la priorité cible. L’hôte, le port et le type du serveur doivent correspondre à ceux de la configuration du serveur existante. Les serveurs sont ajoutés et supprimés dans l’ordre d’apparition dans joining et leaving. Toutes les mises à jour de joining sont traitées avant celles de leaving. Il existe quelques points à connaître concernant l’implémentation de la reconfiguration de Keeper :
  • Seule la reconfiguration incrémentielle est prise en charge. Les requêtes avec un new_members non vide sont refusées. L’implémentation de ClickHouse Keeper s’appuie sur l’API NuRaft pour modifier dynamiquement les membres. NuRaft permet d’ajouter un seul serveur ou de supprimer un seul serveur, un à la fois. Cela signifie que chaque modification de la configuration (chaque partie de joining, chaque partie de leaving) doit être décidée séparément. Il n’existe donc pas de reconfiguration en bloc, car cela serait trompeur pour les utilisateurs finaux. Il n’est pas non plus possible de modifier le type de serveur (participant/learner), car NuRaft ne le prend pas en charge, et le seul moyen serait de supprimer puis de rajouter le serveur, ce qui serait là encore trompeur.
  • Vous ne pouvez pas utiliser la valeur znodestat renvoyée.
  • Le champ from_version n’est pas utilisé. Toutes les requêtes avec from_version défini sont refusées. Cela est dû au fait que /keeper/config est un nœud virtuel, ce qui signifie qu’il n’est pas stocké dans le stockage persistant, mais généré à la volée à partir de la configuration de nœud spécifiée pour chaque requête. Cette décision a été prise afin de ne pas dupliquer les données, puisque NuRaft stocke déjà cette configuration.
  • Contrairement à ZooKeeper, il n’existe aucun moyen d’attendre la reconfiguration du cluster en soumettant une commande sync. La nouvelle configuration sera à terme appliquée, mais sans aucune garantie de délai.
  • La commande reconfig peut échouer pour diverses raisons. Vous pouvez vérifier l’état du cluster et voir si la mise à jour a été appliquée.

​
Conversion d’un Keeper mono-nœud en cluster

Il est parfois nécessaire d’étendre un nœud Keeper expérimental pour en faire un cluster. Voici la procédure à suivre, étape par étape, pour un cluster de 3 nœuds :
  • IMPORTANT : les nouveaux nœuds doivent être ajoutés par lots inférieurs au quorum actuel, sinon ils éliront un leader entre eux. Dans cet exemple, ils sont ajoutés un par un.
  • Le nœud Keeper existant doit avoir le paramètre de configuration keeper_server.enable_reconfiguration activé.
  • Démarrez un deuxième nœud avec la nouvelle configuration complète du cluster Keeper.
  • Une fois démarré, ajoutez-le au nœud 1 à l’aide de reconfig.
  • Démarrez ensuite un troisième nœud et ajoutez-le de la même manière à l’aide de reconfig.
  • Mettez à jour la configuration de clickhouse-server en y ajoutant le nouveau nœud Keeper, puis redémarrez-le pour appliquer les modifications.
  • Mettez à jour la configuration Raft du nœud 1 et, si nécessaire, redémarrez-le.
Pour vous familiariser avec le processus, consultez ce dépôt sandbox.

​
Fonctionnalités non prises en charge

Bien que ClickHouse Keeper vise une compatibilité totale avec ZooKeeper, certaines fonctionnalités ne sont pas encore implémentées (même si leur développement est en cours) :
Dernière modification le 2 juillet 2026