Dépannage réseau Kafka avec exemples pratiques : guide pratique

Introduction

Les problèmes réseau de Kafka peuvent se manifester par des producteurs qui échouent à publier, des consommateurs qui se bloquent ou des courtiers qui quittent le cluster. La cause racine se situe souvent dans une mauvaise configuration DNS, des ports bloqués ou des écouteurs annoncés incorrects. Ce guide fournit une approche systématique et pratique pour diagnostiquer et résoudre les problèmes réseau de Kafka à l'aide de commandes concrètes et de scénarios réalistes.

Vous apprendrez à inventorier votre environnement Kafka, vérifier la connectivité réseau à chaque couche, interpréter les sorties de diagnostic et récupérer en toute sécurité des défaillances courantes. L'accent est mis sur la sécurité opérationnelle : observez avant de modifier, limitez le rayon d'impact, protégez les données sensibles et vérifiez toujours les résultats.

Que vous soyez développeur, ingénieur DevOps ou membre d'une startup technique, les techniques présentées ici s'appliquent aux déploiements Kafka de toute taille. Nous couvrons les considérations spécifiques aux versions, les commandes de dépannage essentielles et les meilleures pratiques pour documenter votre base de référence réseau.

Inventaire des versions et de l'environnement

Avant de dépanner un problème réseau Kafka, établissez une image claire de votre déploiement. Connaître la version exacte de Kafka, le runtime Java, le système d'exploitation et la topologie réseau vous évite d'appliquer des conseils obsolètes ou d'exécuter des commandes incompatibles.

Étape 1 : Identifier la version de Kafka et le runtime

Exécutez les commandes en lecture seule suivantes sur un hôte de courtier pour capturer les versions de Kafka et de Java :

# Version de Kafka (depuis le répertoire d'installation)
ls /opt/kafka/libs | grep 'kafka_[0-9]'
# Exemple de sortie : kafka_2.13-3.6.1.jar

# Version de Java
java -version 2>&1 | head -1
# Exemple de sortie : openjdk version "17.0.9" 2023-10-17 LTS

Documentez ces versions car le comportement réseau et les paramètres de configuration peuvent différer considérablement entre les versions de Kafka. Par exemple, le paramètre advertised.listeners a été introduit dans Kafka 0.10 et est désormais critique pour la connectivité des clients.

Étape 2 : Cartographier la topologie réseau

Enregistrez comment les courtiers, ZooKeeper (si utilisé) et les clients sont répartis sur les réseaux. Utilisez cette liste de contrôle et remplissez vos valeurs réelles (des valeurs d'exemple sont fournies à titre d'illustration) :

Si vous exécutez Kafka en mode KRaft (Kafka 3.3+ sans ZooKeeper), notez plutôt les points de terminaison du quorum de contrôleurs.

Étape 3 : Capturer la configuration actuelle en toute sécurité

Extrayez les paramètres réseau pertinents du courtier sans rien altérer :

# Sur un courtier, recherchez les paramètres d'écouteur et d'annonce dans server.properties
grep -E 'listeners|advertised|host.name|port' /etc/kafka/server.properties

Exemple de sortie :

listeners=PLAINTEXT://0.0.0.0:9092
advertised.listeners=PLAINTEXT://broker1.example.com:9092

Si la valeur de advertised.listeners est manquante ou définie sur une IP privée que les clients ne peuvent pas atteindre, la connectivité échouera. C'est l'une des erreurs de configuration les plus courantes.

Enregistrez également l'état actuel avec un horodatage afin de pouvoir comparer après tout changement :

date -u > /tmp/kafka_network_baseline.txt
grep -E 'listeners|advertised|host.name|port' /etc/kafka/server.properties >> /tmp/kafka_network_baseline.txt

Conservez cette base de référence en lieu sûr. N'incluez pas de secrets dans vos notes. Si vous devez référencer un mot de passe ou une clé, utilisez un espace réservé comme <redacted>.

Chemin de configuration sûr

Une fois que vous avez une base de référence, vous pouvez effectuer le plus petit changement nécessaire pour résoudre le problème réseau. Suivez cette séquence : modifier, valider, redémarrer si nécessaire et vérifier. Sachez toujours comment revenir en arrière.

Correctif courant : Corriger les écouteurs annoncés

Scénario : Les producteurs extérieurs au réseau local du courtier ne peuvent pas se connecter au cluster, mais les connexions locales fonctionnent.

Étapes :

1. Sauvegardez le fichier de configuration avant de le modifier :

   sudo cp /etc/kafka/server.properties /etc/kafka/server.properties.backup.$(date +%Y%m%d)

1. Modifiez la propriété advertised.listeners pour refléter le nom d'hôte ou l'IP accessible de l'extérieur :

   advertised.listeners=PLAINTEXT://broker1.example.com:9092

Si les clients se connectent via SSL/SASL, utilisez le préfixe de protocole approprié (par exemple, SSL:// ou SASL_PLAINTEXT://).

1. Validez la syntaxe du fichier de propriétés (si votre distribution Kafka inclut un validateur de configuration, utilisez-le ; sinon, une simple vérification grep pour les clés en double) :

   grep -c 'advertised.listeners' /etc/kafka/server.properties
   # Sortie attendue : 1 (une seule occurrence)

1. Redémarrez le courtier Kafka pour appliquer les changements. Utilisez votre gestionnaire de services :

   sudo systemctl restart kafka

1. Vérifiez que le courtier écoute sur l'interface attendue (contrôle en lecture seule) :

   ss -ltnp | grep 9092
   # Sortie attendue : LISTEN  0  128  *:9092  *:*  users:(("java",pid=1234,fd=45))

1. Vérifiez le journal du courtier pour les erreurs pendant le démarrage :

   grep -i 'advertised' /var/log/kafka/server.log | tail -5

Si le changement provoque un comportement inattendu, revenez en arrière en restaurant le fichier de sauvegarde et en redémarrant :

sudo cp /etc/kafka/server.properties.backup.20250115 /etc/kafka/server.properties
sudo systemctl restart kafka

Changer de port en toute sécurité

Parfois, vous devez déplacer Kafka vers un port différent pour éviter les conflits. Cela nécessite des changements coordonnés sur tous les clients et courtiers.

Prérequis :

• Confirmez que le nouveau port (par exemple, 9093) n'est pas utilisé : sudo ss -ltnp | grep 9093 ne doit rien retourner.
• Assurez-vous que les règles de pare-feu autorisent le nouveau port.

Sur le courtier :

listeners=PLAINTEXT://0.0.0.0:9093
advertised.listeners=PLAINTEXT://broker1.example.com:9093

Mettez à jour les clients : Tous les producteurs et consommateurs doivent pointer vers le nouveau port. Par exemple, dans une configuration de client Java :

bootstrap.servers=broker1.example.com:9093,broker2.example.com:9093,broker3.example.com:9093

Vérifiez la connectivité depuis une machine cliente en utilisant nc ou telnet :

nc -zv broker1.example.com 9093
# Sortie attendue : Connection to broker1.example.com 9093 port [tcp/*] succeeded!

Si nc n'est pas disponible, utilisez telnet :

telnet broker1.example.com 9093
# Une connexion réussie affiche : Trying 10.0.0.11... Connected to broker1.example.com.

Documentez le nouveau port dans votre système de gestion de configuration et informez toutes les parties prenantes.

Vérification et diagnostics

Diagnostiquer les problèmes réseau de Kafka nécessite de vérifier la connectivité à plusieurs couches : résolution DNS, connexion TCP et prise de contact du protocole Kafka.

Vérifications de la résolution DNS

Les clients Kafka s'appuient sur le DNS pour résoudre les noms d'hôte des courtiers. Une entrée DNS obsolète ou incorrecte peut rompre silencieusement la connectivité.

Vérifiez la résolution DNS depuis une machine cliente :

nslookup broker1.example.com
# Sortie attendue :
# Server:         10.0.0.2
# Address:        10.0.0.2#53
#
# Non-authoritative answer:
# Name:   broker1.example.com
# Address: 10.0.0.11

Si l'IP retournée est incorrecte ou si la recherche échoue, vérifiez la configuration du serveur DNS et l'enregistrement DNS du courtier. Pour tester la résolution en utilisant temporairement des serveurs DNS alternatifs (lecture seule) :

nslookup broker1.example.com 8.8.8.8

Vérifiez le DNS inverse (si votre configuration repose sur des enregistrements PTR) :

dig -x 10.0.0.11 +short
# Sortie attendue : broker1.example.com.

Tests de connectivité TCP

Utilisez nc (netcat) ou telnet pour vérifier la connectivité TCP vers le port Kafka.

Depuis une machine cliente, testez la connexion au courtier sur le port 9092 :

nc -zv broker1.example.com 9092
# Attendu : Connection to broker1.example.com 9092 port [tcp/*] succeeded!

Si la connexion échoue, vérifiez :

• Le courtier écoute (déjà vérifié avec ss).
• Les règles de pare-feu : sudo iptables -L -n | grep 9092 ou sudo firewall-cmd --list-ports.
• Le routage réseau : traceroute broker1.example.com.

Prise de contact du protocole Kafka

Une connexion TCP peut réussir mais le protocole Kafka peut échouer. Utilisez kafka-broker-api-versions.sh (si disponible) pour tester le niveau du protocole.

# Depuis un nœud client Kafka avec les binaires Kafka
/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server broker1.example.com:9092

La sortie attendue inclut des lignes comme :

broker1.example.com:9092 (id: 1 rack: null) -> (
  Produce(0): 0 to 9 [usable: 9],
  Fetch(1): 0 to 13 [usable: 13],
  ...
)

Cela confirme que le client peut atteindre le courtier et parler le protocole Kafka.

Vérification des journaux du courtier pour les erreurs réseau

Inspectez les journaux du courtier pour les exceptions réseau courantes :

grep -i 'network\|connection\|socket\|timeout' /var/log/kafka/server.log | tail -20

Recherchez des motifs comme Connection refused, SocketTimeoutException ou Unable to resolve address. Ceux-ci indiquent des problèmes réseau spécifiques.

Modes de défaillance et récupération

Comprendre les modes de défaillance courants vous aide à diagnostiquer et à récupérer rapidement des problèmes. Voici des scénarios détaillés avec des étapes de récupération.

Mode de défaillance 1 : Échec de la résolution DNS

Symptôme : Les journaux du producteur affichent java.net.UnknownHostException: broker1.example.com.

Diagnostic :

nslookup broker1.example.com
# Sortie : ** server can't find broker1.example.com: NXDOMAIN

Récupération :

1. Vérifiez que le nom d'hôte est correct dans la configuration du client.
2. Vérifiez la configuration du serveur DNS et assurez-vous que l'enregistrement A existe.
3. Si vous utilisez /etc/hosts comme solution de secours, ajoutez l'entrée :

   10.0.0.11   broker1.example.com

(Utilisez cela uniquement comme solution temporaire ; la correction permanente est de mettre à jour le DNS.)

1. Vérifiez que la résolution est corrigée :

   nslookup broker1.example.com
   # Attendu : Address: 10.0.0.11

Mode de défaillance 2 : Pare-feu bloquant le port

Symptôme : Les clients ne parviennent pas à se connecter avec Connection timed out ou Connection refused. Le courtier écoute (confirmé avec ss).

Diagnostic :

• Depuis le client : nc -zv broker1.example.com 9092 expire.
• Sur l'hôte du courtier : vérifiez les règles de pare-feu :

  sudo iptables -L -n | grep 9092

Si rien n'apparaît, le port peut être bloqué par une politique de refus par défaut.

Récupération :

1. Ajoutez une règle de pare-feu pour autoriser le trafic sur le port Kafka (exemple pour firewalld) :

   sudo firewall-cmd --permanent --add-port=9092/tcp
   sudo firewall-cmd --reload

Pour iptables :

   sudo iptables -A INPUT -p tcp --dport 9092 -j ACCEPT
   sudo service iptables save

1. Vérifiez depuis le client : nc -zv broker1.example.com 9092 devrait réussir.

Mode de défaillance 3 : Écouteurs annoncés mal configurés

Symptôme : Le courtier démarre correctement, mais les clients échouent à se connecter lorsqu'ils utilisent le nom d'hôte de la réponse de métadonnées. Les messages d'erreur incluent souvent Connection to node -1 (broker1.example.com/10.0.0.11:9092) could not be established.

Diagnostic : Vérifiez les écouteurs annoncés effectifs en vous connectant avec kafka-console-producer.sh en utilisant le débogage côté client. Alternativement, inspectez les journaux du courtier :

grep -i 'advertised' /var/log/kafka/server.log

Vous pouvez voir le courtier annoncer une IP interne comme 192.168.1.10:9092 au lieu de l'IP publique.

Récupération :

1. Corrigez advertised.listeners comme décrit dans la section Chemin de configuration sûr.
2. Redémarrez le courtier.
3. Vérifiez en exécutant une connexion client de test et en vérifiant que les métadonnées retournent le bon nom d'hôte.

Mode de défaillance 4 : Partition réseau

Symptôme : Les courtiers se retirent par intermittence du cluster, l'ISR (in-sync replicas) diminue ou les producteurs reçoivent NotEnoughReplicasException.

Diagnostic :

• Vérifiez les journaux du courtier pour les messages répétés d'élection de leader et de déconnexion.
• Testez la connectivité entre les courtiers en utilisant ping et nc sur le port inter-courtiers (généralement 9092 ou un port séparé si inter.broker.listener.name est configuré).
• Vérifiez la latence réseau : ping -c 10 broker2.example.com et observez la perte de paquets.

Récupération :

1. Travaillez avec l'équipe réseau pour rétablir la connectivité ou augmenter la redondance.
2. Si la partition est due à une erreur de configuration, corrigez le pare-feu ou le routage.
3. Une fois la connectivité rétablie, vérifiez le statut de l'ISR :

   /opt/kafka/bin/kafka-topics.sh --bootstrap-server broker1.example.com:9092 --describe --topic your_topic
   # Recherchez un nombre ISR correspondant au facteur de réplication

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant, pendant et après le dépannage pour maintenir la discipline et assurer une récupération complète.

Liste de contrôle pré-dépannage

• [ ] Confirmez la version exacte de Kafka et le runtime Java sur tous les nœuds affectés.
• [ ] Cartographiez la topologie réseau : courtiers, clients, pare-feu, équilibreurs de charge.
• [ ] Capturez les configurations Kafka actuelles dans un fichier horodaté, en excluant les secrets.
• [ ] Vérifiez que vous avez un accès en lecture aux journaux et aux métriques du courtier (par exemple, JMX).
• [ ] Identifiez une fenêtre de maintenance si un redémarrage est nécessaire.
• [ ] Préparez les étapes de retour en arrière (sauvegardes de configuration, notez les versions actuelles).

Liste de contrôle de diagnostic

• [ ] Testez la résolution DNS du client vers chaque nom d'hôte de courtier.
• [ ] Testez la connectivité TCP vers chaque port de courtier en utilisant nc ou telnet.
• [ ] Vérifiez que le courtier écoute sur l'interface attendue avec ss.
• [ ] Vérifiez les règles de pare-feu sur les réseaux des courtiers et des clients.
• [ ] Exécutez kafka-broker-api-versions.sh pour confirmer la prise de contact du protocole.
• [ ] Passez en revue les journaux du courtier pour les exceptions réseau.
• [ ] Si vous utilisez SSL/TLS, vérifiez la validité du certificat et la correspondance du nom d'hôte : openssl s_client -connect broker1.example.com:9093 -showcerts.

Liste de contrôle de vérification post-changement

• [ ] Confirmez que le changement de configuration est actif (grep sur la propriété).
• [ ] Redémarrez le service et vérifiez que les journaux de démarrage sont propres.
• [ ] Validez à nouveau la connectivité réseau en utilisant les mêmes tests qu'avant.
• [ ] Exécutez un producteur et un consommateur de test pour confirmer le flux de bout en bout.
• [ ] Surveillez les métriques du courtier pendant quelques minutes pour détecter des baisses inattendues.
• [ ] Documentez le changement, y compris l'horodatage, la justification et le chemin de retour en arrière.
• [ ] Si le changement n'a pas fonctionné, revenez à la sauvegarde et restaurez le service.

Exemple : Session de dépannage structurée

Supposons qu'un cluster Kafka (trois courtiers, Kafka 3.5.1) cesse soudainement d'accepter les connexions d'une application productrice. Utilisez cette séquence :

1. Inventaire : Kafka 3.5.1, Java 17, courtiers à 10.0.0.11, .12, .13. Producteur à 172.16.0.10.
2. Observation : Les journaux du producteur affichent Connection refused en essayant d'atteindre broker1.
3. Vérification DNS : nslookup broker1.example.com retourne l'IP correcte.
4. Vérification TCP : nc -zv 10.0.0.11 9092 échoue avec connexion refusée.
5. Statut du courtier : systemctl status kafka montre que le service est en cours d'exécution. ss -ltnp | grep 9092 ne montre aucun écouteur.
6. Cause racine : Le courtier a été redémarré par un opérateur, mais le nouveau fichier de configuration avait une faute de frappe : listeners=PLAINTEXT://0.0.0.0:909 (il manque le dernier chiffre).
7. Correctif : Corrigez la faute de frappe en 9092, redémarrez le courtier.
8. Vérification : ss montre l'écouteur, nc -zv réussit, le producteur se connecte.
9. Plan de retour en arrière : Si le correctif de la faute de frappe n'avait pas fonctionné, restaurez la configuration précédente à partir de la sauvegarde.

Conclusion

Le dépannage réseau de Kafka nécessite une approche méthodique qui combine la connaissance des versions, des changements de configuration sûrs, des diagnostics approfondis et des procédures de récupération testées. En suivant les étapes décrites dans ce guide, vous pouvez identifier et résoudre des problèmes tels que les erreurs de configuration DNS, les blocages de pare-feu, les écouteurs annoncés incorrects et les partitions réseau sans causer de perturbations supplémentaires.

Commencez toujours par l'observation et la documentation. Capturez votre état actuel, définissez le résultat attendu avant d'apporter des modifications et vérifiez les résultats avec des commandes concrètes. Protégez les informations sensibles et maintenez des plans de retour en arrière clairs.

Pour votre prochaine étape, choisissez une vérification à faible risque de ce guide, comme la vérification de la résolution DNS ou de la connectivité TCP, et exécutez-la sur votre cluster Kafka. Enregistrez l'état actuel, exécutez le diagnostic et comparez le résultat avec le signal attendu. Cette pratique proactive renforcera votre confiance et vous aidera à résoudre rapidement les futurs problèmes réseau.

Un flux de travail opérationnel fiable rend les défaillances visibles, protège les valeurs sensibles, limite les changements à la ressource visée et définit la vérification de récupération avant qu'un incident ne force la décision.