Commandes de base NiFi avec exemples pratiques

Ce guide présente les commandes NiFi essentielles pour les opérations quotidiennes, avec des exemples pratiques prêts à copier que vous pouvez exécuter en toute sécurité. Vous apprendrez à démarrer et arrêter NiFi, vérifier l'état de santé, collecter des diagnostics, définir les identifiants en mode mono-utilisateur et valider les résultats via l'API REST et les journaux. Les exemples mettent l'accent sur des étapes à faible risque que vous pouvez valider localement avant d'appliquer dans des environnements partagés. Au fil des sections, vous verrez les sorties attendues, les modes de défaillance courants et comment revenir en arrière rapidement si nécessaire.

Un petit ensemble de commandes NiFi claires et correctes réduit le temps de résolution des incidents, accélère le retour d'information lors des modifications de flux et établit une base reproductible que vous pouvez enseigner à vos collègues. Un projet pilote ciblé et étroit est le moyen le plus rapide de prouver la valeur et de réduire les retouches.

Inventaire des versions et de l'environnement

Avant d'exécuter toute commande, capturez un inventaire. Cela accélère le dépannage et réduit les conjectures au sein de l'équipe.

Enregistrez les éléments suivants :

• Version de NiFi : par exemple 1.x.y (disponible via la boîte de dialogue « À propos » de l'interface utilisateur ou l'API REST ci-dessous).
• Environnement d'exécution Java : sortie de java -version.
• Système d'exploitation et noyau : uname -a (Linux/Unix) ou systeminfo (Windows Server).
• Topologie : autonome vs cluster, nombre de nœuds, équilibreur de charge le cas échéant.
• Emplacement d'installation : NIFI_HOME, par exemple /opt/nifi ou C:\nifi.
• Répertoires de données : référentiels de contenu, de flowfile, de provenance et chemin des journaux.
• Réseau : port d'entrée UI/API, noms d'hôte et tout proxy inverse.
• Mode d'authentification : mono-utilisateur, LDAP/SAML/OIDC ou aucun (développement uniquement).

Conservez ces informations dans un document partagé et versionné pour votre équipe. Lorsque vous observez un comportement inhabituel, les différences dans cet inventaire l'expliquent souvent rapidement.

Parcours de configuration sécurisé

Adoptez un parcours étroit et à faible risque pour votre premier passage, puis élargissez au fur et à mesure que la confiance grandit.

Approche de projet pilote recommandée :

• Environnement : un NiFi mono-nœud, non-production, sans données critiques. Utilisez des jeux de données de test.
• Accès : si possible, utilisez l'authentification mono-utilisateur pendant le projet pilote afin que les commandes de base soient faciles à vérifier.
• Périmètre : validez d'abord start/stop/status, journaux, diagnostics et vérifications API en lecture seule. Ce n'est qu'ensuite que vous testerez les actions d'écriture (par exemple, modification des identifiants) dans une fenêtre contrôlée.
• Sauvegardes : avant toute modification, copiez conf/flow.xml.gz et conf/bootstrap.conf dans un dossier de sauvegarde daté.
• Plan de retour arrière : définissez les étapes exactes (arrêter NiFi, restaurer les fichiers de sauvegarde, démarrer NiFi) pour pouvoir revenir rapidement.

Ce parcours vous permet d'inspecter les modifications localement et de mesurer les résultats sans risquer la production. Une fois que vous obtenez des résultats prévisibles, vous pouvez répéter ces étapes en préproduction et, plus tard, dans les fenêtres de production.

Aide-mémoire des commandes de base NiFi

Ces commandes supposent une installation typique avec NIFI_HOME défini sur le répertoire racine de NiFi. Exécutez-les depuis NIFI_HOME ou préfixez avec le chemin complet, par exemple /opt/nifi/bin/nifi.sh.

Parcours des commandes avec exemples pratiques

Les scénarios suivants démontrent des commandes sûres avec les résultats attendus et les étapes de vérification. Adaptez les chemins et ports à votre environnement.

Prérequis :

• Vous avez un accès au système de fichiers vers NIFI_HOME (exemple : /opt/nifi).
• Votre PATH inclut Java et JAVA_HOME est défini.
• Si sécurisé, vous pouvez vous authentifier auprès de l'UI/API NiFi.

Note sur les invites et sorties : remplacez l'hôte exemple 127.0.0.1 et les ports 8443 / 8080 par vos valeurs.

1) Démarrer NiFi et confirmer le statut

Commandes :

cd /opt/nifi
bin/nifi.sh start
sleep 5
bin/nifi.sh status

Résultats attendus :

• start affiche un court message comme « NiFi has started. » et revient rapidement.
• status affiche quelque chose comme « NiFi is running with PID 12345. » Sinon, il affiche « NiFi is not running. »

Étapes de vérification :

• Suivez le journal pour les messages de démarrage :

  tail -n 200 -f logs/nifi-app.log

• Dans le journal, recherchez les lignes indiquant que le serveur web a démarré et sur quel port il écoute.
• Visitez l'UI dans un navigateur, par exemple https://127.0.0.1:8443/ ou http://127.0.0.1:8080/ selon votre configuration.

Variantes courantes :

• Pour exécuter en avant-plan avec les journaux console pour un débogage rapide :

  bin/nifi.sh run

Utilisez Ctrl+C pour arrêter. N'utilisez pas ce mode comme démon en production.

2) Arrêter NiFi en toute sécurité

Commandes :

cd /opt/nifi
bin/nifi.sh stop
sleep 5
bin/nifi.sh status

Résultats attendus :

• stop revient rapidement.
• Après un court délai, status indique que NiFi ne tourne pas.

Étapes de vérification :

• Vérifiez logs/nifi-app.log pour les messages d'arrêt gracieux.
• Assurez-vous que le PID a disparu. Sur les systèmes de type Unix :

  ps -ef | grep nifi | grep -v grep

Un résultat vide signifie que le processus s'est terminé.

Notes :

• Si NiFi est lent à s'arrêter, accordez du temps supplémentaire. NiFi vide le travail en cours pour maintenir l'intégrité des données.

3) Collecter des diagnostics pour un incident

La commande dump rassemble un paquet d'artefacts de diagnostic qui peut accélérer l'analyse des causes racines.

Commande :

cd /opt/nifi
bin/nifi.sh dump

Résultats attendus :

• La sortie indique le chemin vers un zip généré sous logs/ (par exemple logs/diagnostics-YYYYMMDD-HHMMSS.zip).

Étapes de vérification :

• Listez le fichier et inspectez son horodatage :

  ls -lh logs | grep diagnostics

• Stockez le paquet selon le processus de votre équipe.

4) Afficher l'environnement pour le dépannage

Lorsque des problèmes de JVM ou d'environnement surviennent, confirmer les arguments d'exécution aide à circonscrire les causes.

Commande :

cd /opt/nifi
bin/nifi.sh env

Résultats attendus :

• La commande affiche JAVA_HOME, les options JVM, les paramètres de mémoire et les variables d'environnement utiles.

Étapes de vérification :

• Confirmez que les drapeaux de mémoire (-Xms, -Xmx) correspondent à votre plan de dimensionnement.
• Vérifiez l'absence de surcharges inattendues provenant de l'environnement shell.

5) Définir les identifiants mono-utilisateur (pour un projet pilote de développement)

Si vous utilisez l'authentification mono-utilisateur (courante lors des tests locaux), définissez ou faites pivoter les identifiants en toute sécurité. Effectuez cela uniquement en non-production ou dans une fenêtre planifiée.

Commande (exemple construit) :

cd /opt/nifi
bin/nifi.sh set-single-user-credentials devadmin S3cur3P@ssw0rd!

Résultats attendus :

• Le script met à jour les fichiers de configuration appropriés pour l'accès mono-utilisateur.
• Un redémarrage est généralement requis pour que le changement prenne effet.

Redémarrage sécurisé :

bin/nifi.sh restart

Étapes de vérification :

• Connectez-vous à l'UI avec les nouveaux identifiants.
• Testez un appel API en lecture seule (voir la section API ci-dessous) pour confirmer l'accès authentifié si votre instance est sécurisée.

Plan de retour arrière :

• Arrêtez NiFi.
• Restaurez les identifiants précédents si vous avez une sauvegarde de la configuration (par exemple, conf/users.xml le cas échéant) ou relancez la commande avec les valeurs précédentes.
• Démarrez NiFi et vérifiez.

6) Vérifications de santé basées sur les journaux pendant les opérations

Les journaux sont la fenêtre la plus rapide sur le comportement de NiFi pendant l'exécution des commandes.

Exemples :

• Suivez le journal d'application pendant le redémarrage :

  tail -f logs/nifi-app.log

• Inspectez le journal de bootstrap pour les détails de lancement JVM :

  tail -n 200 logs/nifi-bootstrap.log

• Vérifiez rapidement les avertissements des référentiels de provenance et de contenu :

  grep -E "ERROR|WARN" logs/nifi-app.log | tail -n 50

Résultats attendus :

• Au démarrage, le serveur web se lie au port configuré et signale sa disponibilité.
• À l'arrêt, les journaux indiquent que les processeurs se sont arrêtés et que les référentiels se sont fermés proprement.

Vérification et diagnostics

Utilisez une combinaison de vérifications UI, journaux et appels API REST. Les appels API suivants sont en lecture seule et sûrs.

Remplacez le schéma/hôte/port par votre environnement. Pour les instances sécurisées, incluez un en-tête d'authentification ou utilisez un cookie/session d'une connexion préalable et ajoutez un en-tête minimal comme :

-H "X-Requested-By: nifi"

Exemple : confirmer la version et l'état du nœud

curl -s http://127.0.0.1:8080/nifi-api/flow/about | jq .

Attendu : JSON qui inclut la chaîne de version NiFi. Si jq n'est pas installé, supprimez le pipe vers jq et visualisez le JSON brut.

Exemple : récupérer les 10 derniers bulletins pour repérer rapidement les erreurs

curl -s http://127.0.0.1:8080/nifi-api/flow/bulletin-board?limit=10 | jq '.bulletinBoard.bulletins[] | {level: .bulletin.level, msg: .bulletin.message}'

Attendu : Une courte liste de messages récents. Les entrées ERROR ou WARN doivent être investiguées.

Exemple : vérifier le résumé du cluster (fonctionne aussi pour le mode autonome)

curl -s http://127.0.0.1:8080/nifi-api/flow/cluster/summary | jq .clusterSummary

Attendu : Comptages et statuts des nœuds. Pour un nœud unique, les comptages devraient être 1 en ligne et 0 déconnecté.

Note : Dans les environnements sécurisés (HTTPS), ajoutez -k pour les certificats auto-signés en test et utilisez https://hote:8443/ selon le cas. Assurez-vous de respecter la politique de sécurité de votre organisation.

Modes de défaillance et récupération

Les problèmes suivants sont courants lors des opérations de base NiFi. Chacun inclut un chemin de récupération sûr.

1. NiFi ne démarre pas

• Symptômes : status indique « not running » ; UI inaccessible ; journaux montrent des échecs de liaison ou erreurs de référentiel.
• Vérifications :
• Le port est-il déjà utilisé ? netstat ou ss peut confirmer.
• logs/nifi-app.log montre-t-il une corruption de référentiel ou des problèmes de permissions ?
• JAVA_HOME est-il valide et compatible avec votre version de NiFi ?
• Récupération :
• Libérez le port ou changez le port configuré, puis relancez start.
• Corrigez les permissions de fichiers pour que l'utilisateur NiFi puisse lire/écrire les référentiels et journaux.
• Si une corruption de référentiel est indiquée pour une instance de développement non critique, arrêtez NiFi et videz uniquement les répertoires de test affectés ; pour la production, escaladez et préservez les données pour analyse.
• Capturez un paquet de diagnostics avec bin/nifi.sh dump avant d'apporter des modifications majeures.

1. NiFi est lent à s'arrêter

• Symptômes : stop revient, mais le processus persiste pendant des minutes.
• Vérifications :
• Suivez les journaux pour voir quels processeurs attendent de terminer le travail.
• Confirmez que les systèmes externes (ex. Kafka, HDFS) sont accessibles ; une E/S bloquée peut retarder l'arrêt.
• Récupération :
• Accordez du temps supplémentaire pour un arrêt gracieux afin d'éviter la perte de données.
• Si requis, une fenêtre de service contrôlée peut inclure une terminaison forcée, mais privilégiez l'arrêt gracieux pour maintenir l'intégrité des flowfiles.

1. Les modifications d'authentification n'ont pas pris effet

• Symptômes : identifiants mono-utilisateur mis à jour mais impossible de se connecter.
• Vérifications :
• Avez-vous redémarré NiFi après avoir exécuté set-single-user-credentials ?
• Pointez-vous vers le bon hôte/port et protocole (http vs https) ?
• Récupération :
• Arrêtez NiFi, relancez la commande d'identifiants, vérifiez que les fichiers de configuration sont mis à jour, démarrez NiFi.
• Si vous avez des sauvegardes, restaurez la configuration précédente et démarrez NiFi.

1. CPU ou mémoire élevés après redémarrage

• Symptômes : l'UI est réactive mais les ressources système grimpent en flèche.
• Vérifications :
• Examinez les bulletins et diagnostics système via l'API pour la contre-pression ou les erreurs.
• Vérifiez les drapeaux JVM avec bin/nifi.sh env et validez le dimensionnement du tas.
• Récupération :
• Ajustez -Xms et -Xmx dans la configuration bootstrap ou d'environnement de NiFi selon votre plan de capacité.
• Mettez en pause les processeurs ou sources de données lourdes, puis reprenez progressivement en surveillant les diagnostics.

1. La dérive de configuration cause un comportement inattendu

• Symptômes : un nœud se comporte différemment des autres.
• Vérifications :
• Comparez les horodatages et hachages de conf/flow.xml.gz entre les nœuds.
• Confirmez que les versions Java et OS correspondent à votre base de référence.
• Récupération :
• Arrêtez le nœud affecté, restaurez le dernier conf/flow.xml.gz connu bon depuis la sauvegarde, démarrez le nœud et vérifiez.

Conseils généraux de retour arrière :

• Arrêtez toujours NiFi avant de restaurer les fichiers de configuration.
• Gardez des sauvegardes datées de conf/flow.xml.gz et conf/bootstrap.conf au minimum.
• Après le retour arrière, vérifiez avec status, les journaux, la disponibilité de l'UI et les vérifications API en lecture seule.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour les opérations quotidiennes et hebdomadaires. Ajustez l'intervalle selon la charge de travail et les SLA.

Quotidien

• Confirmez que NiFi tourne : bin/nifi.sh status
• Vérifiez les 50 dernières lignes WARN/ERROR : grep -E "WARN|ERROR" logs/nifi-app.log | tail -n 50
• Examinez les bulletins via l'API et l'UI pour les nouveaux avertissements
• Vérifiez l'espace disque disponible pour le contenu, flowfile, provenance et journaux
• Si en cluster, confirmez que tous les nœuds sont connectés via le résumé du cluster

Hebdomadaire

• Capturez un paquet de diagnostics : bin/nifi.sh dump et archivez-le de manière sécurisée
• Examinez les paramètres de mémoire Java et NiFi avec bin/nifi.sh env par rapport à l'utilisation observée
• Faites pivoter ou archivez les journaux si ce n'est pas géré automatiquement
• Sauvegardez conf/flow.xml.gz et conf/bootstrap.conf avec des copies datées

Fenêtre de changement (planifiée)

• Annoncez le timing et l'impact
• Avant changement : bin/nifi.sh status ; prenez des sauvegardes des fichiers de configuration critiques
• Appliquez le changement : utilisez start/stop/restart selon les besoins
• Après changement : vérifiez l'UI, les journaux et les contrôles API ; documentez les résultats
• En cas de problèmes : exécutez le plan de retour arrière et re-vérifiez

Réponse aux incidents

• Stabilisez d'abord : arrêtez ou mettez en pause les sources lourdes si pertinent
• Rassemblez les faits : journaux, bulletins, diagnostics API
• Capturez bin/nifi.sh dump pour analyse ultérieure
• Appliquez des correctifs ciblés ; vérifiez après chaque étape

Conclusion

Avec une poignée de commandes de base NiFi et des étapes de vérification claires, vous pouvez exploiter NiFi en toute confiance et récupérer rapidement des problèmes courants. Commencez par un projet pilote étroit et sûr : apprenez start/stop/status, surveillez les journaux, collectez les diagnostics et effectuez de petits changements réversibles. Utilisez les vérifications API pour confirmer la santé sans devinettes. Ensuite, standardisez vos routines quotidiennes et hebdomadaires avec la liste de contrôle pour que chaque opérateur puisse obtenir des résultats cohérents. Capturez votre inventaire d'environnement et établissez la base des commandes dans une instance de développement. Pratiquez les scénarios de défaillance et de récupération avec des données de test. Intégrez les vérifications dans les manuels d'exploitation de votre équipe pour qu'ils soient faciles à exécuter lors des opérations de routine et des incidents.