Comment récupérer après un snapshot Keeper corrompu

Des snapshots ClickHouse Keeper corrompus ou défectueux peuvent provoquer une forte instabilité du système, notamment des incohérences de métadonnées, des tables en lecture seule, un épuisement des ressources ou des échecs de sauvegarde. Cet article couvre :

• Ce que sont les snapshots et où les trouver
• Comment le problème se manifeste
• Les stratégies de récupération possibles et ce que chacune d’elles implique

Un snapshot est un état sérialisé des données internes de Keeper (comme les métadonnées sur les clusters, les chemins de coordination des tables et les configurations) à un instant donné. Les snapshots sont essentiels pour resynchroniser les nœuds Keeper au sein d’un cluster, restaurer les métadonnées en cas de défaillance, ainsi que pour les processus de démarrage ou de redémarrage qui s’appuient sur un état valide connu de Keeper.

Les snapshots sont stockés sous forme de fichiers sur le système de fichiers local des nœuds Keeper. Par défaut, ils sont enregistrés dans /var/lib/clickhouse/coordination/snapshots/, ou dans le chemin personnalisé défini par snapshot_storage_path dans votre fichier keeper_server.xml. Les snapshots sont numérotés de manière incrémentielle (par exemple, snapshot.23), les plus récents portant des numéros plus élevés.

Dans les clusters multinœuds, chaque nœud Keeper possède son propre répertoire de snapshots.

Le tableau ci-dessous présente quelques symptômes et manifestations courants de snapshots Keeper corrompus :

Indicateurs dans les logs :

Avant de diagnostiquer une corruption de snapshot, vérifiez les logs Keeper afin d'identifier des motifs d'erreur spécifiques :

Avant de toucher aux fichiers, veillez toujours à :

1. Arrêter tous les nœuds Keeper pour éviter toute corruption supplémentaire
2. Sauvegarder l’ensemble en copiant l’intégralité du répertoire de coordination dans un emplacement sûr
3. Vérifier le quorum du cluster afin de vous assurer qu’au moins un nœud dispose de données intactes

Suivez cette procédure si :

• La corruption des métadonnées de Keeper ou d’un snapshot rend les données actuelles irrécupérables.
• Une sauvegarde existe avec un état Keeper connu comme sain.

Suivez les étapes ci-dessous pour restaurer une sauvegarde existante :

1. Repérez et validez la sauvegarde la plus récente afin de vérifier la cohérence des métadonnées.
2. Arrêtez les services ClickHouse et Keeper.
3. Remplacez les snapshots et les logs défectueux par ceux du répertoire de sauvegarde.
4. Redémarrez le cluster Keeper et vérifiez la synchronisation des métadonnées.

Suivez cette procédure dans les cas suivants :

• Des snapshots récents sont corrompus, mais d’anciens snapshots restent exploitables.
• Les logs incrémentiels sont intacts, ce qui permet une restauration cohérente.

Suivez les étapes ci-dessous pour revenir à un snapshot plus ancien :

1. Identifiez et sélectionnez un ancien snapshot valide (par exemple, snapshot.19) dans le répertoire Keeper.
2. Supprimez les snapshots et les logs plus récents.
3. Redémarrez Keeper afin qu’il rejoue les logs pour reconstruire l’état des métadonnées.

Vous devez suivre ce processus dans les cas suivants :

• les métadonnées de Keeper sont perdues ou corrompues, mais les données de la table existent toujours sur le disque
• les tables sont passées en mode lecture seule en raison de métadonnées ZooKeeper/Keeper manquantes
• vous devez recréer les métadonnées dans Keeper à partir des parties de données disponibles localement

Suivez les étapes ci-dessous pour restaurer les métadonnées :

1. Vérifiez que les données de la table existent localement dans le chemin de données de votre clickhouse-server, défini par <path> dans votre configuration. (/var/lib/clickhouse/data/ par défaut)

2. Pour chaque table concernée, exécutez :

SYSTEM RESTART REPLICA [db.]table_name;
SYSTEM RESTORE REPLICA [db.]table_name;

3. Pour une récupération au niveau de la base de données (si vous utilisez le moteur de base de données Replicated) :

SYSTEM RESTORE DATABASE REPLICA db_name;

4. Attendez la fin de la synchronisation :

SYSTEM SYNC REPLICA [db.]table_name;

5. Vérifiez la récupération en vérifiant que system.replicas a is_readonly = 0 et en surveillant system.detached_parts

Vous devez suivre cette procédure dans les cas suivants :

• L'erreur se produit sur une seule réplique du cluster et les métadonnées correspondantes dans Keeper sont corrompues ou incohérentes
• Vous rencontrez des erreurs du type "Part XXXXX intersects previous part YYYYY"
• Vous devez réinitialiser complètement les métadonnées d'une réplique dans Keeper tout en conservant les données locales

Suivez les étapes ci-dessous pour supprimer et recréer les métadonnées :

1. Sur la réplique affectée, détachez la table :

DETACH TABLE [db.]table_name;

2. Supprimez de Keeper les métadonnées de la réplique (à exécuter sur n’importe quelle réplique) :

SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/clickhouse/tables/{shard}/table_name';

Pour trouver le bon chemin ZooKeeper :

SELECT zookeeper_path, replica_name FROM system.replicas WHERE table = 'table_name';

3. Réattachez la table (elle sera en mode lecture seule) :

ATTACH TABLE [db.]table_name;

4. Restaurez les métadonnées de la réplique :

SYSTEM RESTORE REPLICA [db.]table_name;

5. Synchronisez-vous avec les autres répliques :

SYSTEM SYNC REPLICA [db.]table_name;

6. Vérifiez system.detached_parts sur toutes les répliques après la récupération

Alternative : utiliser le flag force_restore_data

Pour récupérer automatiquement toutes les tables répliquées au démarrage du serveur :

1. Arrêtez le serveur ClickHouse
2. Créez le flag de récupération :

sudo -u clickhouse touch /var/lib/clickhouse/flags/force_restore_data

3. Démarrez le serveur ClickHouse
4. Le serveur supprimera automatiquement le flag et restaurera toutes les tables répliquées
5. Surveillez les logs pour suivre la progression de la restauration

Cette approche est utile lorsque plusieurs tables doivent être restaurées simultanément.

Vous devez suivre ce processus lorsque :

• Ni snapshots, ni logs, ni sauvegardes valides ne sont disponibles pour la restauration.
• Vous devez recréer l’intégralité du cluster Keeper et de ses métadonnées.

Suivez les étapes ci-dessous pour reconstruire le cluster Keeper :

1. Arrêtez complètement les clusters ClickHouse et Keeper.
2. Réinitialisez chaque nœud Keeper en nettoyant les répertoires de snapshots et de logs.
3. Initialisez un nœud Keeper comme leader, puis ajoutez progressivement les autres nœuds.
4. Réimportez les métadonnées si elles sont disponibles depuis des enregistrements externes.