## Introduction Exploiter Apache Kafka en production ne se limite pas à garder les nœuds en vie. Cela implique de connaître précisément la version utilisée, la configuration actuelle, l’apparence d’un cluster sain et la marche à suivre en cas de dérive par rapport à cette référence. Cette liste de contrôle fournit aux développeurs, aux ingénieurs DevOps et aux équipes de plateforme des startups un flux de travail reproductible, axé d’abord sur la lecture seule, pour les opérations Kafka. La liste est délibérément structurée autour de la sécurité : observer avant de modifier, limiter le rayon d’impact, utiliser des espaces réservés plutôt que de vrais secrets, vérifier le résultat avec une commande concrète et documenter un chemin de récupération avant qu’un incident ne l’impose. Chaque section comprend des exemples réutilisables de CLI Kafka avec des espaces réservés explicites, des signaux de sortie attendus et une étape de retour en arrière testée. À la fin de ce guide, vous devriez être capable d’auditer la version d’un cluster, de modifier un paramètre de courtier ou de sujet en toute sécurité, de diagnostiquer le retard des consommateurs, de récupérer après la défaillance d’un courtier et d’éviter les erreurs de production les plus courantes. ## Inventaire des versions et de l’environnement Avant de toucher à quoi que ce soit, établissez ce que vous exploitez. Plage de composants et de versions Saisissez la version du courtier pour chaque nœud. Les versions de Kafka ne sont pas toujours uniformes pendant les mises à niveau progressives, et le comportement de la CLI change entre les versions. Observation en lecture seule Exécutez la commande suivante sur n’importe quel hôte de courtier ou depuis un client ayant accès à bin : kafka-broker-api-versions.sh --bootstrap-server localhost:9092 | head -5 Sortie attendue (Kafka 3.0 - 3.6, tronquée) : localhost:9092 (id: 1 rack: us-east-1a) -> ( Produce(0): 0 to 9 [usable: 9], Fetch(1): 0 to 13 [usable: 13], ListOffsets(2): 0 to 7 [usable: 7], ... ) Si la commande renvoie org.apache.kafka.common.errors.TimeoutException , le courtier n’est pas joignable sur ce listener, ou il ne s’agit pas d’un point de terminaison de courtier. Vérifiez advertised.listeners dans server.properties et les ACL réseau. Topologie et identifiants Listez tous les courtiers et leurs rôles : kafka-broker-api-versions.sh --bootstrap-server localhost:9092 | grep -E '^\S+ \(id:' En mode KRaft (Kafka 3.3+), un nœud contrôleur affiche Controller(3) dans sa liste d’API. En mode ZooKeeper, exécutez : zookeeper-shell.sh localhost:2181 ls /brokers/ids Attendu : [0, 1, 2] (trois identifiants de courtiers). Prérequis pour une observation sûre - Accès réseau depuis la machine exécutant les outils CLI vers le listener annoncé de chaque courtier. - ACL en lecture seule pour DESCRIBE et DESCRIBE_CONFIGS si les ACL Kafka sont activées. - Une copie à jour de la distribution Kafka correspondant à la version mineure du cluster, ou au moins une version majeure en arrière pour une compatibilité ascendante. Plus petit changement justifié Ne changez rien pour l’instant. Enregistrez la sortie dans un runbook ou un système de gestion de configuration avec un horodatage. Si les versions diffèrent entre les courtiers, c’est un constat, pas un changement. Vérification du changement Réexécutez la même commande et comparez les sorties. Stockez la référence dans Git ou un ticket pour les post-mortems d’incident. ## Chemin de configuration sûr Les modifications de configuration sont la source la plus courante d’interruptions auto-infligées de Kafka. Suivez un chemin contrôlé. ### Changement de configuration du courtier : log.retention.hours État actuel Lisez la valeur existante : kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type brokers --entity-name 1 --describe Sortie attendue : Dynamic configs for broker 1 are: log.retention.hours=168 sensitive=false synonyms={DEFAULT_CONFIG:log.retention.hours=168} Description du changement Réduire la rétention des données de sujet de 168 heures (7 jours) à 72 heures pour un courtier spécifique uniquement, afin de libérer de l’espace disque avant une fenêtre de maintenance planifiée. Ce changement est dynamique et ne nécessite pas de redémarrage du courtier s’il est appliqué via kafka-configs.sh . Rayon d’impact Seul le courtier 1 est affecté. Les autres courtiers conservent les 168 heures par défaut. Les sujets avec des dérogations de rétention explicites par sujet ne sont pas affectés car les configurations au niveau du courtier agissent comme valeurs par défaut. Appliquer le changement kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type brokers --entity-name 1 --alter \ --add-config log.retention.hours=72 Sortie attendue : Completed updating config for broker 1. Vérifier kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type brokers --entity-name 1 --describe La sortie attendue inclut log.retention.hours=72 . Retour en arrière kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type brokers --entity-name 1 --alter \ --delete-config log.retention.hours Ou remettez explicitement 168 . La suppression de la dérogation dynamique revient à la valeur par défaut de server.properties . ### Changement de configuration du sujet : min.insync.replicas Augmenter min.insync.replicas peut bloquer les producteurs s’il n’y a pas assez de réplicas synchronisés. En production, effectuez ce changement uniquement après avoir vérifié la taille actuelle de l’ISR. État actuel kafka-topics.sh --bootstrap-server localhost:9092 \ --topic payments --describe Attendu : Topic: payments PartitionCount: 3 ReplicationFactor: 3 Partition: 0 Leader: 1 Replicas: 1,2,3 Isr: 1,2,3 ... Si une partition affiche moins d’ISR que de réplicas, n’augmentez pas min.insync.replicas avant d’avoir résolu ce problème. Changement Définissez min.insync.replicas=2 pour tolérer la défaillance d’un courtier tout en exigeant deux accusés de réception. kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type topics --entity-name payments --alter \ --add-config min.insync.replicas=2 Vérifier kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type topics --entity-name payments --describe Attendu : min.insync.replicas=2 . Retour en arrière Supprimez la dérogation : kafka-configs.sh --bootstrap-server localhost:9092 \ --entity-type topics --entity-name payments --alter \ --delete-config min.insync.replicas ### Garde-fous - Ne modifiez jamais server.properties sur un courtier en ligne sans un plan de redémarrage testé. La plupart des paramètres du courtier ne sont lus qu’au démarrage. - Utilisez kafka-configs.sh pour les changements dynamiques. Vérifiez quelles configurations sont dynamiques avec : kafka-configs.sh --bootstrap-server localhost:9092 --entity-type brokers \ --entity-name 1 --describe --all | grep 'sensitive=false' - Pour les configurations statiques, déployez un courtier à la fois, attendez que le cluster se rééquilibre et surveillez les métriques avant le courtier suivant. ## Vérification et diagnostics Un cluster Kafka sain est observable grâce à des métriques cohérentes et des sorties de commandes. ### Contrôle de santé du cluster Commande en lecture seule kafka-broker-api-versions.sh --bootstrap-server localhost:9092 \ --command-config client.properties 2>&1 | grep -c '^\S+ \(id:' Attendu : le nombre de courtiers (par exemple, 3 ). Si inférieur, un courtier est en panne ou mal annoncé. ### Partitions sous-répliquées kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions Attendu : sortie vide (aucune ligne). Toute ligne indique une partition dont les réplicas ne sont pas entièrement synchronisés. Examinez le disque, le réseau ou les fluctuations de l’ISR du courtier listé. ### Retard des consommateurs Pour un groupe de consommateurs orders-group : kafka-consumer-groups.sh --bootstrap-server localhost:9092 \ --group orders-group --describe Exemple de sortie : GROUP TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG orders-group orders 0 15234 15240 6 orders-group orders 1 30120 30120 0 Un retard supérieur à un seuil défini par l’entreprise (par exemple, 1 000 messages ou 5 minutes de latence) nécessite une action. Surveillez le retard avec Burrow, Datadog ou l’exportateur JMX Prometheus. ### Vérification du répertoire de journaux kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe --broker-list 0,1,2 Cela indique la taille de chaque répertoire de journaux et les répertoires hors ligne. Les répertoires de journaux hors ligne provoquent des échecs de réplication. ### Interprétation des signaux de défaillance - NotEnoughReplicasException à la production signifie que min.insync.replicas ne peut pas être satisfait. Vérifiez l’ISR et l’état du courtier. - OffsetOutOfRangeException signifie qu’un consommateur a tenté de lire un offset déjà supprimé. Réinitialisez l’offset du groupe de consommateurs. - LeaderNotAvailableException suit souvent une défaillance de courtier ou un réassignement de partition. Attendez l’élection du leader ou vérifiez les journaux du contrôleur. ## Modes de défaillance et récupération Planifiez pour les défaillances les plus probables, pas pour les exotiques. ### Disque plein du courtier Symptôme Les journaux du courtier montrent Failed to write to log ou Log directory ... is offline . Les producteurs reçoivent NOT_ENOUGH_REPLICAS . Diagnostic df -h /var/lib/kafka/data Si l’utilisation est de 90 % ou plus, vous êtes à risque. Vérifiez les plus gros sujets : kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe --broker-list 0,1,2 Triez par taille pour trouver le coupable. Récupération - Réduisez temporairement la rétention sur les plus gros sujets en utilisant kafka-configs.sh (comme indiqué ci-dessus). - Si nécessaire, rééquilibrez les partitions loin du courtier plein en utilisant kafka-reassign-partitions.sh . - Nettoyez les anciens segments : Kafka supprimera les segments au-delà de la rétention une fois que le nettoyeur s’exécutera. Vérification Surveillez l’utilisation du disque et les partitions sous-répliquées jusqu’à ce que les deux reviennent à la normale. ### Crash et redémarrage du courtier Symptôme Courtier absent de la sortie de kafka-broker-api-versions.sh ; les partitions perdent leur leadership. Diagnostic systemctl status kafka Ou vérifiez les journaux de kafka-server-start.sh dans /var/log/kafka/server.log . Récupération - Identifiez la cause racine (OOM, défaillance de disque, partition réseau). - Corrigez le problème sous-jacent. - Démarrez le courtier : systemctl start kafka - Attendez que le courtier rejoigne l’ISR pour toutes ses partitions. Surveillez kafka-topics.sh --describe pour les partitions sous-répliquées. - Si le courtier ne peut pas redémarrer en raison de journaux corrompus, supprimez le répertoire de journaux corrompu uniquement après avoir vérifié que les autres réplicas sont synchronisés. Vérification Le nombre de partitions sous-répliquées doit revenir à zéro sans changements de leadership non résolus. ### Délai d’attente du producteur dû à min.insync.replicas Symptôme Les producteurs reçoivent org.apache.kafka.common.errors.NotEnoughReplicasException . Diagnostic Vérifiez l’ISR pour le sujet : kafka-topics.sh --bootstrap-server localhost:9092 --topic high-value --describe Si l’ISR < min.insync.replicas , les producteurs devraient échouer avec cette exception à moins que acks=all ne soit pas défini. Récupération - Ramenez les réplicas manquants dans l’ISR (corrigez le courtier ou le réseau). - Si le temps presse, réduisez temporairement min.insync.replicas pour permettre les écritures, mais documentez le risque. ## Liste de contrôle des opérations Utilisez cette liste comme runbook pour les tâches de routine et la réponse aux incidents. ### Contrôle de santé quotidien (5 minutes) - [ ] Exécutez kafka-broker-api-versions.sh --bootstrap-server localhost:9092 | grep -c 'id:' et comparez au nombre attendu de courtiers. - [ ] Exécutez kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions et assurez-vous qu’il n’y a pas de sortie. - [ ] Vérifiez le retard des consommateurs pour tous les groupes critiques. Alertez si le retard dépasse le seuil. - [ ] Vérifiez l’utilisation du disque sur chaque courtier : df -h /var/lib/kafka/data . Alertez si > 85 %. ### Revue hebdomadaire (15 minutes) - [ ] Passez en revue les journaux des courtiers pour les avertissements ou erreurs répétés. - [ ] Vérifiez le leadership non équilibré : kafka-topics.sh --describe --topic '*' | grep -c 'Leader: 1' par rapport aux autres courtiers. - [ ] Validez le processus de sauvegarde et de restauration pour au moins un sujet. ### Vérification pré-changement Avant tout changement de configuration, répondez à ces questions : - Quel est le paramètre actuel ? (Exécutez la commande describe et enregistrez la sortie) - Quel est le nouveau paramètre attendu et pourquoi ? - Quels composants sont affectés (courtier, sujet, client) ? - Le changement est-il dynamique ou nécessite-t-il un redémarrage ? - Quelle est la commande ou procédure de retour en arrière ? - Quelle métrique prouvera que le changement a fonctionné ? ### Responsables - Contrôles de santé du cluster : ingénieur d’astreinte, revu quotidiennement lors du stand-up. - Changements de configuration : responsable de l’équipe plateforme (par exemple, Priya Shah, responsable ingénierie), approuvé via un ticket de changement et revu lors de la réunion hebdomadaire des opérations. - Retard des consommateurs et débit : propriétaire du pipeline de données (par exemple, responsable de l’ingénierie des données), surveillé en continu, revu hebdomadairement. - Planification de capacité disque/sujets : propriétaire de l’infrastructure (par exemple, responsable DevOps), revu mensuellement avec l’équipe plateforme. ## Pièges courants ### 1. Appliquer des changements de configuration sans vérifier le support de version Pourquoi cela arrive Les opérateurs utilisent une CLI obsolète ou supposent que toutes les configurations sont dynamiques. Comment éviter Exécutez toujours kafka-configs.sh --version pour confirmer que le client correspond au courtier. Consultez les notes de mise à niveau de Kafka pour la version spécifique avant de modifier des configurations statiques. Récupération Si un changement échoue, revenez immédiatement à la valeur de configuration précédente et vérifiez avec la commande describe. ### 2. Ignorer trop longtemps les partitions sous-répliquées Pourquoi cela arrive Elles sont silencieuses jusqu’à ce qu’un courtier tombe en panne, ce qui entraîne une perte de données. Comment éviter Définissez des alertes pour les partitions sous-répliquées > 0 pendant plus de 5 minutes. Utilisez la métrique de l’exportateur JMX Prometheus kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions . Récupération Examinez immédiatement le courtier affecté. Vérifiez les journaux, le disque et le réseau. Redémarrez si nécessaire et attendez le rattrapage de l’ISR. ### 3. Modifier min.insync.replicas sans vérifier l’ISR Pourquoi cela arrive Les équipes augmentent la durabilité sans réaliser que l’ISR actuel peut être inférieur. Comment éviter Exécutez toujours kafka-topics.sh --describe d’abord. Assurez-vous que l’ISR >= le min.insync.replicas souhaité pour chaque partition. Récupération Si les producteurs bloquent, réduisez immédiatement min.insync.replicas , corrigez le problème d’ISR, puis augmentez à nouveau après la récupération de l’ISR. ### 4. Utiliser kafka-topics.sh --delete sans nettoyer les offsets du sujet ou l’état du consommateur Pourquoi cela arrive Les opérateurs suppriment un sujet puis les groupes de consommateurs se bloquent. Comment éviter Avant de supprimer un sujet, arrêtez tous les consommateurs de ce sujet, supprimez le groupe de consommateurs ou réinitialisez les offsets, puis supprimez le sujet. Récupération Si les groupes de consommateurs sont bloqués, utilisez kafka-consumer-groups.sh --reset-offsets --to-latest --execute pour passer les messages manquants. ### 5. Ne pas sauvegarder server.properties et log4j.properties Pourquoi cela arrive Tout le monde suppose que les fichiers de configuration sont dans Git, mais certains changements sont effectués directement sur les serveurs pendant les urgences. Comment éviter Utilisez la gestion de configuration (par exemple, Ansible, Chef) et le contrôle de version. Diffusez périodiquement les configurations en direct par rapport au dépôt. Récupération Si une configuration est perdue, reconstruisez à partir de la sauvegarde et redémarrez le courtier de manière contrôlée. ## Conclusion Une liste de contrôle des opérations de production Kafka n’est utile que si elle est limitée à une version, observable et réversible là où la technologie le permet. Copier une commande sans vérifier les prérequis et la sortie attendue n’est pas une procédure d’exploitation ; c’est un pari. Commencez dès aujourd’hui par une vérification à faible risque sur votre cluster : exécutez la commande de version de l’API du courtier, enregistrez la sortie et comparez-la à votre référence attendue. Choisissez ensuite une configuration que vous vouliez auditer et suivez le chemin de configuration sûr de ce guide. Des opérations Kafka fiables rendent les défaillances visibles, protègent les valeurs sensibles, limitent les changements à la ressource visée et définissent la vérification de récupération avant qu’un incident ne force la décision. Gardez cette liste dans votre runbook et révisez-la après chaque incident pour combler les lacunes.