Dépannage réseau NiFi avec exemples pratiques : un guide de terrain

Introduction

Quand un flux NiFi cesse de déplacer des données, la cause profonde est souvent un problème réseau : un nom DNS qui ne se résout plus, un port bloqué ou un certificat TLS mal configuré. Ce guide présente une méthodologie de dépannage systématique, de l'observation initiale à la récupération vérifiée. Vous apprendrez à identifier les problèmes réseau dans NiFi à l'aide de commandes concrètes, de sorties attendues et de points de décision clairs. L'accent est mis sur des étapes pratiques et à faible risque qu'un opérateur peut exécuter dans un environnement de développement ou de production contrôlé. Chaque section comprend un scénario réel, des commandes de diagnostic et un chemin de récupération testable.

Cet article s'adresse aux développeurs, aux ingénieurs DevOps et aux équipes techniques de startups qui exploitent des clusters NiFi ou des instances autonomes. Il couvre la configuration DNS, l'affectation des ports, les vérifications de connectivité et le dépannage réseau. Bien que les exemples utilisent des commandes shell et l'API REST de NiFi, les mêmes principes s'appliquent aux déploiements conteneurisés et à Kubernetes.

La sécurité opérationnelle est un thème récurrent : toujours observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés au lieu de secrets réels, vérifier le résultat et documenter comment revenir en arrière si l'état attendu n'est pas atteint.

Inventaire de la version et de l'environnement

Avant de toucher à toute configuration, établissez exactement avec quoi vous travaillez. Cela évite d'appliquer un correctif destiné à NiFi 1.x à un cluster 2.x, ou de mal interpréter une entrée de journal en supposant une mauvaise topologie de déploiement.

Scénario : Un flux signale « Impossible de communiquer avec le service de contrôleur ». Vous soupçonnez un problème réseau, mais avez besoin de faits d'abord.

Étape 1 : Identifier la version de NiFi

Exécutez la commande suivante depuis l'hôte NiFi, ou utilisez kubectl exec si vous êtes dans Kubernetes :

nifi.sh --version
# ou, si vous utilisez l'image conteneur
/opt/nifi/nifi-current/bin/nifi.sh --version

Sortie attendue pour un NiFi 2.x récent :

Apache NiFi Version: 2.3.0

Si la commande échoue ou signale une version que vous ne reconnaissez pas, notez le chemin d'installation et si NiFi a été installé à partir d'une archive tar, d'un RPM ou d'une image conteneur. Cela affecte l'emplacement des journaux et des fichiers de configuration.

Étape 2 : Déterminer la topologie

Demandez :

• S'agit-il d'une instance autonome ou d'un cluster ?
• Y a-t-il un ensemble ZooKeeper externe, ou NiFi utilise-t-il son ZooKeeper embarqué (NiFi 2.x uniquement) ?
• Les nœuds sont-ils dans le même centre de données, dans plusieurs régions ou dans le cloud ?

Pour un cluster, listez les nœuds depuis l'interface utilisateur à https://<hôte-nifi>:8443/nifi -> Cluster. Sinon, utilisez l'API (le port par défaut pour HTTPS est 8443, HTTP est 8080) :

curl -k -u admin:password https://nifi.example.com:8443/nifi-api/controller/cluster

La sortie attendue est un objet JSON avec un tableau nodes. Vérifiez l'address et le status de chaque nœud. Si un nœud apparaît comme déconnecté, c'est un indice réseau.

Étape 3 : Observation en lecture seule

Capturez l'état actuel sans rien changer :

• Pour chaque nœud, enregistrez son adresse IP et son nom DNS :

  hostname -I
  hostname -f

• Vérifiez le journal NiFi pour les erreurs réseau récentes :

  tail -n 200 $NIFI_HOME/logs/nifi-app.log | grep -i -E 'connection|timeout|refused|network'

• Sauvegardez la sortie dans un fichier avec horodatage pour comparaison ultérieure.

Prérequis : Vous devez avoir un accès shell à l'hôte NiFi et les permissions appropriées pour lire les journaux. Si NiFi s'exécute dans un conteneur, utilisez docker exec -it <conteneur> bash ou kubectl exec -it <pod> -- bash pour y entrer.

Rayon d'impact : Ces commandes sont en lecture seule et sûres à exécuter sur un système de production.

Vérification : Après la collecte, confirmez que vous avez la version, la topologie, les adresses IP et les lignes de journal pertinentes. Sans cela, tout changement est un pari.

Chemin de configuration sûr

Avec la base de l'environnement établie, vous pouvez maintenant ajuster en toute sécurité les paramètres liés au réseau. Cette section se concentre sur les fichiers de configuration les plus courants : nifi.properties, bootstrap.conf et authorizers.xml (pour TLS). Le principe est de changer une chose à la fois et de toujours savoir comment revenir en arrière.

Scénario : NiFi démarre mais l'interface utilisateur n'est pas accessible via HTTPS. Vous soupçonnez que le port web ou les paramètres TLS sont erronés.

Comprendre les propriétés réseau clés

Dans nifi.properties, les propriétés suivantes contrôlent l'interface HTTP/HTTPS :

nifi.web.http.host=
nifi.web.http.port=8080
nifi.web.https.host=
nifi.web.https.port=8443
nifi.remote.input.host=
nifi.remote.input.secure=true
nifi.remote.input.socket.port=10000

• nifi.web.http.host et nifi.web.https.host : Laissez vide pour se lier à toutes les interfaces. Définissez une IP seulement si vous devez restreindre.
• nifi.web.http.port : Par défaut 8080, souvent désactivé en production en le mettant vide.
• nifi.web.https.port : Par défaut 8443. Si vous le changez, mettez à jour tout proxy inverse ou équilibreur de charge.
• nifi.remote.input.socket.port : Utilisé pour la communication site-à-site. Doit être ouvert entre les nœuds du cluster.

Procédure : Changer le port HTTPS en toute sécurité

Prérequis : NiFi est arrêté. Vous avez des sauvegardes de nifi.properties. Vous savez que le port actuel (par ex., 8443) et le nouveau port (par ex., 9443) n'est pas utilisé.

1. Observer l'état actuel :

   grep -E 'nifi.web.https.port|nifi.web.http.port' $NIFI_HOME/conf/nifi.properties

Sortie attendue :

   nifi.web.http.port=8080
   nifi.web.https.port=8443

1. Modifier le fichier en utilisant sed ou un éditeur de texte. Changez nifi.web.https.port en 9443.

   sed -i 's/nifi.web.https.port=8443/nifi.web.https.port=9443/' $NIFI_HOME/conf/nifi.properties

1. Vérifier le changement sans démarrer NiFi :

   grep 'nifi.web.https.port' $NIFI_HOME/conf/nifi.properties
   # Attendu : nifi.web.https.port=9443

1. Démarrer NiFi et vérifier que le nouveau port écoute :

   $NIFI_HOME/bin/nifi.sh start
   # Attendre quelques secondes
   ss -tulpn | grep 9443

Ligne de sortie attendue :

   LISTEN 0 50 *:9443 *:* users:(('java',pid=1234,fd=45))

1. Revenir en arrière si nécessaire : Arrêtez NiFi, annulez le changement, redémarrez.

Rayon d'impact : Changer le port HTTPS affecte tous les clients (interface utilisateur, API, site-à-site). Assurez-vous que les règles d'accès externes sont mises à jour. Si derrière un équilibreur de charge, coordonnez le changement.

Vérification : Accédez à l'interface utilisateur à https://<hôte>:9443/nifi et confirmez la connexion. Vérifiez le journal utilisateur NiFi pour les erreurs.

Erreur courante : Modifier la configuration sans sauvegarde

Une erreur fréquente est de modifier nifi.properties en ligne sans copie. Si le changement casse le démarrage, vous pourriez ne pas vous souvenir de la valeur d'origine. Faites toujours une sauvegarde horodatée :

cp $NIFI_HOME/conf/nifi.properties $NIFI_HOME/conf/nifi.properties.$(date +%Y%m%d-%H%M%S)

Si NiFi ne démarre pas, restaurez la sauvegarde et redémarrez.

Vérification et diagnostics

Maintenant que les changements sont faits, vous devez vérifier que le chemin réseau fonctionne réellement de bout en bout. Cette section couvre l'utilisation des outils intégrés du système d'exploitation et des API propres à NiFi pour confirmer la connectivité.

Scénario : Un processeur ne parvient pas à se connecter à un service HTTP externe. Les journaux du processeur montrent ConnectException: Connection refused.

Diagnostic pas à pas

Prérequis : Le processeur s'exécute sur un nœud NiFi, et vous connaissez le nom d'hôte et le port cibles (par ex., api.external.com:443). Vous pouvez accéder au shell du nœud.

1. Reproduire la tentative de connexion en utilisant curl depuis l'hôte NiFi :

curl -v --connect-timeout 5 https://api.external.com:443/

Interprétez la sortie :

• Connected to api.external.com (192.0.2.10) port 443 -> la connexion réseau a réussi ; le problème peut être TLS ou l'authentification.
• Could not resolve host: api.external.com -> problème DNS.
• Connection timed out -> problème de pare-feu ou de routage.
• Connection refused -> le service cible n'écoute pas sur ce port.

2. Vérifier la résolution DNS :

dig +short api.external.com
# ou
nslookup api.external.com

Sortie attendue si le DNS fonctionne :

192.0.2.10

Si l'adresse IP est vide ou diffère des attentes, vérifiez /etc/resolv.conf et le serveur DNS. NiFi utilise la résolution DNS de la JVM, qui suit le système d'exploitation. Vous pouvez également tester avec un extrait Java, mais les outils du système d'exploitation sont plus simples.

3. Vérifier le port avec nc ou telnet :

nc -zvw5 api.external.com 443

Sortie attendue en cas de succès :

Connection to api.external.com 443 port [tcp/https] succeeded!

Si cela échoue, le port est bloqué ou le service est arrêté. Vérifiez les règles du groupe de sécurité, le pare-feu (iptables/firewalld) et si le service écoute sur l'hôte distant.

4. Vérifier les journaux propres de NiFi pour plus de contexte :

grep -i 'api.external.com' $NIFI_HOME/logs/nifi-app.log | tail -20

Cela peut montrer l'exception exacte et l'heure de l'échec.

Commande de diagnostic : ss pour l'utilisation des ports locaux

Si l'on soupçonne que NiFi n'écoute pas sur un port, utilisez :

ss -tulpn | grep java

La sortie liste tous les ports TCP/UDP sur lesquels les processus Java (y compris NiFi) écoutent. Vérifiez que les ports NiFi attendus (8080, 8443, 10000, etc.) sont présents.

Rayon d'impact : Toutes les commandes de cette section sont en lecture seule.

Vérification : Vous devriez pouvoir répondre : Le DNS résout-il ? Le port est-il accessible ? Le service répond-il ? Si une réponse est non, vous avez isolé la couche et pouvez procéder au correctif approprié.

Modes de défaillance et récupération

Les problèmes réseau se manifestent de manière prévisible. Cette section décrit les modes de défaillance courants, leurs symptômes, causes profondes et la récupération pas à pas.

Défaillance 1 : Échecs de résolution DNS

Symptômes : Les processeurs qui appellent des services externes échouent avec UnknownHostException ; les connexions site-à-site montrent Failed to resolve address ; les nœuds du cluster ne se trouvent pas.

Pourquoi cela arrive : Le serveur DNS est en panne, mal configuré, ou le nom d'hôte a été changé. Dans Kubernetes, les politiques DNS peuvent être trop restrictives. Dans les environnements cloud, les zones DNS privées peuvent ne pas être liées au VPC.

Étapes de récupération :

1. Confirmez l'échec avec dig ou nslookup.
2. Vérifiez /etc/resolv.conf pour les bons serveurs de noms.
3. Vérifiez que le serveur DNS est joignable : ping -c 1 <ip-du-serveur-dns>.
4. Si vous utilisez une entrée de fichier hosts, assurez-vous qu'elle est correcte : cat /etc/hosts.
5. Pour Kubernetes, vérifiez la politique DNS du pod et la ConfigMap.
6. Comme solution de contournement immédiate, ajoutez une ligne à /etc/hosts mappant le nom d'hôte vers la bonne IP, mais documentez cela comme temporaire.
7. Correctif permanent : mettez à jour l'enregistrement DNS, redémarrez NiFi si les caches sont obsolètes. La JVM met en cache les recherches DNS pendant une période définie par networkaddress.cache.ttl (par défaut -1 pour toujours, sauf si défini). Ajoutez -Dnetworkaddress.cache.ttl=60 à bootstrap.conf pour des mises à jour plus rapides, puis redémarrez.

Vérification : Après la récupération, exécutez à nouveau dig et assurez-vous que l'IP attendue est retournée. Ensuite, testez une connexion réelle depuis NiFi.

Défaillance 2 : Port bloqué par le pare-feu

Symptômes : Les nœuds du cluster NiFi ne peuvent pas communiquer ; le site-à-site échoue avec Connection timed out ; l'interface utilisateur inaccessible depuis d'autres machines.

Pourquoi cela arrive : Les groupes de sécurité, les ACL réseau ou les pare-feu hôtes ne sont pas mis à jour après un changement de port ou l'ajout d'un nouveau nœud.

Étapes de récupération :

1. Identifiez les ports requis. Les principaux ports NiFi sont :

• 8080 (interface HTTP) - souvent désactivé en production
• 8443 (interface HTTPS)
• 10000 (socket brut site-à-site, si activé)
• 10001 (HTTPS site-à-site)
• Port de protocole de cluster (configuré dans nifi.properties comme nifi.cluster.node.protocol.port, par défaut 11443)
• ZooKeeper (2181 pour un ensemble externe, ou ports embarqués)

1. Testez la connectivité depuis un autre nœud en utilisant nc -zv <ip-cible> <port>.
2. Si la connexion échoue, vérifiez le pare-feu hôte : sudo iptables -L -n | grep <port> ou sudo firewall-cmd --list-ports.
3. Pour le cloud, vérifiez les règles entrantes du groupe de sécurité de l'instance. Ajoutez une règle pour le port requis depuis la plage d'IP source.
4. Après avoir ouvert le port, retestez avec nc ou en tentant la connexion réelle depuis NiFi.

Vérification : Le port doit être joignable depuis la source attendue. Utilisez telnet ou nc pour confirmer que la poignée de main TCP réussit.

Défaillance 3 : Discordance de certificat TLS

Symptômes : L'interface NiFi montre des avertissements de certificat ; le site-à-site échoue avec SSLHandshakeException ; les processeurs échouent avec PKIX path building failed.

Pourquoi cela arrive : Les certificats sont auto-signés et non approuvés, le nom d'hôte dans le certificat ne correspond pas, ou le certificat a expiré.

Étapes de récupération :

1. Examinez le certificat présenté par le serveur NiFi :

   openssl s_client -connect nifi.example.com:8443 -showcerts

Regardez subject et issuer et les dates d'expiration.

1. Si le certificat est expiré, renouvelez-le selon votre processus d'AC et importez-le dans le keystore de NiFi.
2. Si le nom d'hôte ne correspond pas, générez un nouveau certificat avec le bon SAN (Subject Alternative Name).
3. Mettez à jour nifi.properties pour pointer vers le nouveau keystore et truststore, puis redémarrez.
4. Pour la confiance côté client, importez le certificat de l'AC dans le truststore utilisé par NiFi.

Vérification : Après les changements, exécutez curl -v https://nifi.example.com:8443 et assurez-vous qu'il n'y a pas d'erreurs TLS. Testez une connexion site-à-site.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle comme référence rapide avant et pendant le dépannage. Chaque élément inclut le propriétaire et la fréquence de révision, suivant le principe de responsabilité claire.

Pour chaque élément, le propriétaire est une seule personne ou un rôle, pas un groupe. La fréquence de révision garantit que la liste reste à jour. Lorsqu'un incident survient, commencez par l'élément 1 et descendez ; ne sautez pas directement au changement de configuration.

Pièges courants à éviter

Même les opérateurs expérimentés tombent dans des pièges. Voici des erreurs récurrentes et comment les éviter.

Piège 1 : Modifier plusieurs paramètres réseau à la fois

Pourquoi cela arrive : Sous pression, vous pouvez modifier nifi.properties, les règles de pare-feu et les enregistrements DNS simultanément.

Comment éviter : Respectez le chemin de configuration sûr. Changez un paramètre, vérifiez, et seulement ensuite passez au suivant. Si quelque chose casse, vous savez exactement quoi annuler.

Piège 2 : Ignorer le cache DNS de la JVM

Pourquoi cela arrive : Vous mettez à jour le DNS, mais NiFi utilise toujours l'ancienne IP, ce qui crée de la confusion.

Comment éviter : Définissez networkaddress.cache.ttl à une valeur raisonnable (par ex., 60 secondes) dans bootstrap.conf en ajoutant java.arg.XX=-Dnetworkaddress.cache.ttl=60 (où XX est le prochain numéro de propriété). Documentez que les changements DNS prennent jusqu'à une minute pour se propager à NiFi.

Piège 3 : Utiliser des adresses IP au lieu de noms d'hôte

Pourquoi cela arrive : Les adresses IP semblent plus directes, mais elles cassent lorsque les instances sont remplacées ou déplacées.

Comment éviter : Utilisez des noms DNS stables dans les configurations NiFi. Si vous utilisez un équilibreur de charge cloud, utilisez son nom DNS. Cela simplifie la gestion des certificats et le basculement.

Piège 4 : Ne pas vérifier les deux sens de la connectivité

Pourquoi cela arrive : Vous vérifiez que NiFi peut atteindre la base de données, mais pas que la base de données peut accepter des connexions depuis l'IP du nœud NiFi.

Comment éviter : Testez toujours depuis l'hôte NiFi vers la cible. Si la cible a son propre pare-feu, assurez-vous que l'IP du nœud NiFi est autorisée en entrée.

Piège 5 : Négliger les ports site-à-site

Pourquoi cela arrive : L'interface fonctionne, donc vous supposez que tout le réseau va bien. Mais le site-à-site utilise des ports séparés qui peuvent être bloqués.

Comment éviter : Testez explicitement les ports 10000 et 10001 entre les nœuds du cluster en utilisant nc ou telnet. Incluez-les dans votre liste de contrôle régulière.

Conclusion

Le dépannage réseau NiFi est un processus discipliné : observez d'abord, changez minimalement, vérifiez soigneusement. Ce guide a parcouru l'inventaire de l'environnement, les changements de configuration sûrs, les commandes de diagnostic, les défaillances courantes et une liste de contrôle opérationnelle. En suivant ces étapes, vous réduirez les temps d'arrêt et éviterez la frustration des suppositions.

La prochaine fois qu'un flux s'arrête, commencez par ss -tulpn et dig, pas par une modification de configuration. Documentez vos constatations avec des horodatages, et ayez toujours un plan de retour en arrière. Impliquez le bon propriétaire pour chaque couche : ingénieur plateforme pour les internes de NiFi, administrateur réseau pour les règles de pare-feu et agent de sécurité pour les certificats.

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