Dépannage réseau MongoDB : exemples pratiques pour développeurs et DevOps

Introduction

Un déploiement MongoDB qui ne peut pas accepter de connexions est opérationnellement mort, même si le processus de base de données est sain sur son hôte. Les pannes réseau se manifestent par des délais d'attente dans votre application, des messages « connection refused » des pilotes ou un retard de réplication mystérieux. Ce guide présente une approche structurée pour dépanner le réseau MongoDB, du premier symptôme à la correction confirmée.

Vous apprendrez à :

• Inventorier la version de MongoDB, la topologie de déploiement et les liaisons réseau avant de faire des changements.
• Utiliser des commandes en lecture seule pour observer l'état actuel sans perturber le trafic de production.
• Diagnostiquer les problèmes de résolution DNS, d'accessibilité des ports, d'authentification et de configuration du pilote.
• Appliquer le plus petit changement sûr pour corriger les problèmes de connectivité.
• Vérifier la correction et récupérer en toute confiance si quelque chose tourne mal.

Chaque exemple inclut des commandes concrètes, les résultats attendus et les signaux d'échec. Utilisez des espaces réservés (<host>, <port>, <user>) pour votre environnement. N'exposez jamais de véritables identifiants ou identifiants de production dans les scripts ou la documentation.

Inventaire de la version et de l'environnement

Avant de toucher à toute configuration, collectez les faits concernant le déploiement. Cela évite les suppositions erronées, comme essayer de se connecter au mauvais port ou utiliser une option de pilote qui n'existe pas dans votre version de MongoDB.

Identifier la version et la topologie de MongoDB

Exécutez cette commande en lecture seule depuis le shell mongosh (ou le shell hérité mongo si vous utilisez MongoDB 4.0 ou antérieur) :

mongosh "mongodb://<user>:<password>@<host>:<port>/admin" --quiet --eval "db.version()"

Résultat attendu pour MongoDB 6.0 :

6.0.5

Si la connexion échoue, la commande elle-même devient un diagnostic. Un délai d'attente peut indiquer un problème réseau, tandis qu'une erreur d'authentification signifie que le chemin réseau est bon mais que les identifiants sont erronés.

Pour vérifier la topologie d'un ensemble de réplicas ou d'un cluster partitionné, exécutez :

mongosh "mongodb://<host>:<port>/admin" --quiet --eval "rs.status().members.map(m => ({name: m.name, stateStr: m.stateStr}))"

Résultat attendu (abrégé) :

[
  { name: "mongo1:27017", stateStr: "PRIMARY" },
  { name: "mongo2:27017", stateStr: "SECONDARY" },
  { name: "mongo3:27017", stateStr: "SECONDARY" }
]

Un membre affichant "stateStr": "UNKNOWN" ou n'apparaissant pas du tout suggère une partition réseau ou un problème de configuration.

Capturer les liaisons réseau actuelles

MongoDB écoute sur les interfaces définies par le paramètre bindIp dans mongod.conf ou l'option de ligne de commande --bind_ip. Pour voir ce sur quoi le processus serveur est réellement lié, exécutez sur l'hôte MongoDB :

sudo netstat -tlnp | grep mongod

Exemple de sortie lorsque bindIp est défini sur 127.0.0.1 :

tcp        0      0 127.0.0.1:27017         0.0.0.0:*               LISTEN      1234/mongod

Si la ligne ne montre que 127.0.0.1, les clients distants ne peuvent pas se connecter. Une ligne avec 0.0.0.0 ou une adresse IP LAN spécifique signifie que le serveur est accessible depuis ces interfaces.

Pour inspecter la configuration sans redémarrer, utilisez db.adminCommand({getCmdLineOpts:1}) dans mongosh :

db.adminCommand({getCmdLineOpts:1}).parsed.net

Résultat attendu :

{ "port": 27017, "bindIp": "127.0.0.1" }

Définir les signaux attendus et d'échec

Avant de changer quoi que ce soit, notez à quoi ressemble « corrigé ». Pour chaque problème, définissez :

• Symptôme observé : par exemple, les journaux d'application montrent ECONNREFUSED 127.0.0.1:27017.
• Résultat attendu après correction : l'application se connecte et les requêtes renvoient des données.
• Signal d'échec : la même erreur persiste, ou une nouvelle erreur apparaît.

Un modèle de liste de contrôle à copier dans votre runbook :

Ne placez jamais de véritables identifiants, jetons, clés privées ou identifiants de production dans un article ou un runbook partagé.

Chemin de configuration sûr

Une fois que vous comprenez l'état actuel, effectuez un petit changement à la fois. Pour le réseau, les changements les plus courants consistent à ajuster bindIp, modifier les règles de pare-feu ou corriger les entrées DNS.

Modifier bindIp pour autoriser les connexions distantes

Si bindIp est défini sur 127.0.0.1, les applications distantes ne peuvent pas se connecter. Pour autoriser les connexions sur toutes les interfaces IPv4, modifiez mongod.conf (généralement à /etc/mongod.conf sous Linux) :

net:
  port: 27017
  bindIp: 0.0.0.0

Alternativement, liez à une adresse IP spécifique :

net:
  port: 27017
  bindIp: 192.168.1.100,127.0.0.1

Prérequis : Vous avez besoin d'un accès sudo sur l'hôte MongoDB. Le changement affecte toutes les connexions, prévoyez donc un bref redémarrage ou un redémarrage progressif dans un ensemble de réplicas.

Rayon d'impact : Ouvrir bindIp sur 0.0.0.0 expose MongoDB à toutes les interfaces réseau. Combinez cela avec des règles de pare-feu qui restreignent l'accès aux plages d'adresses IP de confiance uniquement.

Appliquez le changement avec un redémarrage :

sudo systemctl restart mongod

Vérifiez la nouvelle liaison :

sudo netstat -tlnp | grep mongod

Résultat attendu :

tcp        0      0 0.0.0.0:27017            0.0.0.0:*               LISTEN      1234/mongod

Récupération si le changement cause des problèmes : Revenez sur bindIp à 127.0.0.1, redémarrez et vérifiez avec netstat. Documentez cette étape de retour en arrière dans votre runbook avant d'effectuer le changement.

Mettre à jour les règles de pare-feu

Les pare-feu bloquent souvent les ports MongoDB. Sur Ubuntu avec UFW, autorisez l'accès uniquement depuis l'adresse IP de votre serveur d'application (par exemple, 203.0.113.5) :

sudo ufw allow from 203.0.113.5 to any port 27017 proto tcp

Vérifiez la règle :

sudo ufw status numbered

La sortie attendue inclut :

[ 1] 203.0.113.5 27017/tcp       ALLOW IN    Anywhere

Testez la connectivité depuis le serveur d'application :

nc -zv <mongo_host> 27017

Résultat attendu :

Connection to <mongo_host> 27017 port [tcp/*] succeeded!

Si la connexion échoue, revérifiez la règle de pare-feu et l'adresse de liaison du serveur. Supprimez une règle indésirable avec sudo ufw delete <rule_number>.

Vérification et diagnostics

Après tout changement, exécutez une batterie systématique de vérifications. Commencez du côté de l'application et avancez vers le serveur de base de données.

Tester la résolution DNS

Les pilotes MongoDB utilisent souvent un nom d'hôte. Si le DNS échoue, la connexion échoue avant qu'un paquet TCP ne soit envoyé. Utilisez nslookup ou dig pour résoudre le nom d'hôte :

nslookup mongo.example.com

Résultat attendu :

Server:         8.8.8.8
Address:        8.8.8.8#53

Name:   mongo.example.com
Address: 192.0.2.10

Si la sortie affiche NXDOMAIN ou une adresse IP incorrecte, corrigez l'enregistrement DNS ou utilisez temporairement une adresse IP. Vérifiez le fichier local /etc/hosts si une correspondance statique est nécessaire.

Tester l'accessibilité du port

Utilisez telnet ou nc pour tester la connectivité TCP vers le port MongoDB :

telnet <mongo_host> 27017

Si le port est ouvert, vous verrez un écran vide ou un message comme Connected to <mongo_host>. Appuyez sur Ctrl+] et tapez quit pour quitter. Un message Connection refused signifie que le serveur n'écoute pas sur cette interface ou qu'un pare-feu rejette la connexion.

Pour une analyse plus détaillée du chemin réseau, utilisez traceroute (ou tracert sous Windows) :

traceroute <mongo_host>

Recherchez les astérisques * indiquant des sauts bloqués ou des délais d'attente.

Vérifier les journaux du serveur MongoDB

MongoDB enregistre les tentatives de connexion et les erreurs. Sous Linux, le journal par défaut est /var/log/mongodb/mongod.log. Utilisez grep pour trouver les messages récents liés au réseau :

sudo grep -i "network" /var/log/mongodb/mongod.log | tail -20

Exemple de sortie :

2024-05-20T10:11:12.345+0000 I NETWORK  [listener] connection accepted from 203.0.113.5:52341 #123 (1 connection now open)
2024-05-20T10:11:12.456+0000 I NETWORK  [conn123] end connection 203.0.113.5:52341 (0 connections now open)

Si vous voyez des connection accepted répétés suivis d'un end connection immédiat, le client peut se déconnecter en raison d'un échec d'authentification ou d'une incompatibilité de version du pilote.

Vérifier l'authentification et l'autorisation

Utilisez mongosh pour tester une connexion avec des identifiants :

mongosh "mongodb://<user>:<password>@<host>:27017/admin?authSource=admin" --quiet --eval "db.runCommand({connectionStatus:1}).authInfo.authenticatedUsers"

Résultat attendu :

[ { user: "appUser", db: "admin" } ]

Si vous obtenez Authentication failed, vérifiez les identifiants de l'utilisateur et la authSource. De nombreux problèmes de connexion sont dus à des bases de données d'authentification mal configurées : un utilisateur créé dans admin doit s'authentifier contre admin même s'il a accès à d'autres bases de données.

Modes d'échec et récupération

Les problèmes de réseau MongoDB du monde réel ont tendance à se répartir en quelques schémas répétables. Les reconnaître accélère le diagnostic.

Échec : Connexion refusée depuis l'application

Symptôme : Les journaux d'application affichent ECONNREFUSED ou MongoNetworkError: connect ECONNREFUSED.

Causes possibles :

• MongoDB ne fonctionne pas.
• MongoDB est lié à 127.0.0.1 uniquement.
• Le pare-feu bloque le port.
• Mauvais port spécifié dans la chaîne de connexion.

Diagnostic et récupération :

1. Sur l'hôte MongoDB, vérifiez si le processus est en cours d'exécution : sudo systemctl status mongod.
2. S'il est en cours d'exécution, vérifiez l'adresse de liaison : sudo netstat -tlnp | grep mongod.
3. Depuis l'hôte de l'application, testez le port : nc -zv <mongo_host> 27017.
4. Si la connexion est refusée mais que MongoDB est lié à 0.0.0.0, vérifiez les règles de pare-feu.
5. Démarrez MongoDB s'il est arrêté : sudo systemctl start mongod.
6. Corrigez l'adresse de liaison comme décrit précédemment si nécessaire.
7. Re-testez depuis l'hôte de l'application.

Échec : Délai d'attente pendant la connexion

Symptôme : L'application se bloque pendant un moment puis renvoie Server selection timed out after 30000 ms.

Causes possibles :

• La route réseau est bloquée (pare-feu qui abandonne les paquets au lieu de les rejeter).
• La résolution DNS est lente ou échoue.
• MongoDB est surchargé et n'accepte pas de nouvelles connexions.

Diagnostic et récupération :

1. Testez la vitesse de résolution DNS : time nslookup <mongo_host>.
2. Vérifiez le chemin réseau avec traceroute.
3. Vérifiez le nombre de connexions MongoDB : dans mongosh, exécutez db.serverStatus().connections.

• Résultat attendu : { "current" : 12, "available" : 51188, "totalCreated" : 1234 }.
• Si available est proche de 0, le serveur a atteint sa limite de connexions. Augmentez maxIncomingConnections dans mongod.conf ou redémarrez les connexions inactives.

1. Si le DNS est lent, ajoutez une entrée dans /etc/hosts sur le serveur d'application pour l'hôte MongoDB.
2. Si le réseau abandonne des paquets, travaillez avec votre équipe réseau pour ouvrir les ports requis.

Échec : Échec d'authentification malgré des identifiants corrects

Symptôme : MongoServerError: Authentication failed.

Causes possibles :

• Mauvaise authSource dans la chaîne de connexion.
• L'utilisateur n'existe pas dans la base de données d'authentification spécifiée.
• Le mot de passe contient des caractères spéciaux qui nécessitent un encodage URL.
• Le compte utilisateur est verrouillé ou a expiré.

Diagnostic et récupération :

1. Listez les utilisateurs dans la base de données admin : use admin; db.getUsers().
2. Si l'utilisateur est dans une autre base de données, spécifiez cette base de données dans authSource.
3. Encodez les caractères spéciaux du mot de passe en utilisant le pourcentage d'encodage (par exemple, @ devient %40).
4. Réinitialisez le mot de passe si nécessaire : db.changeUserPassword("appUser", "NewStr0ngP@ss").
5. Testez la connexion avec mongosh en utilisant la chaîne de connexion exacte.

Échec : Les membres de l'ensemble de réplicas ne peuvent pas se voir

Symptôme : rs.status() montre un ou plusieurs membres comme UNKNOWN ou REMOVED, et le primaire peut avoir démissionné.

Causes possibles :

• Les règles de pare-feu bloquent le trafic entre les membres sur le port 27017.
• Le bindIp d'un membre n'inclut pas l'adresse IP utilisée par les autres membres.
• La résolution du nom d'hôte a échoué pour un membre.

Diagnostic et récupération :

1. Depuis chaque membre, essayez de vous connecter à tous les autres membres en utilisant mongosh "mongodb://<other_host>:27017/admin" --quiet --eval "db.runCommand({ping:1})".
2. Vérifiez les règles de pare-feu avec sudo ufw status ou sudo iptables -L.
3. Assurez-vous que le bindIp de chaque membre inclut l'adresse IP utilisée par les autres membres.
4. Vérifiez les entrées DNS ou /etc/hosts sur tous les membres.
5. Après avoir corrigé le réseau, les membres devraient se réassocier automatiquement. Vérifiez rs.status() pour confirmer que tous les membres affichent PRIMARY ou SECONDARY.

Pièges courants et comment les éviter

Des années d'expérience en support MongoDB révèlent une poignée d'erreurs récurrentes. Évitez-les pour gagner des heures de débogage.

Piège 1 : Modifier bindIp sans mettre à jour les règles de pare-feu

Pourquoi cela arrive : Les ingénieurs corrigent souvent une couche (la configuration MongoDB) mais oublient l'autre (le pare-feu). Le résultat est que MongoDB écoute désormais sur toutes les interfaces mais que le pare-feu bloque toujours le port 27017. Les applications ne peuvent toujours pas se connecter, et l'ingénieur est confus.

Comment éviter : Testez toujours la connectivité depuis l'hôte de l'application après avoir modifié bindIp. Si la connexion échoue, vérifiez le pare-feu avant de toucher à nouveau à MongoDB.

Piège 2 : Utiliser localhost dans la configuration de l'ensemble de réplicas

Pourquoi cela arrive : Dans un ensemble de réplicas, chaque membre est identifié par un nom d'hôte que les autres membres utilisent pour se connecter. Si vous utilisez localhost dans la configuration rs.initiate(), chaque membre se considère joignable à localhost, ce qui est faux pour les membres distants.

Comment éviter : Utilisez toujours des noms de domaine pleinement qualifiés ou des adresses IP résolubles depuis tous les membres. Par exemple :

rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1.example.com:27017" },
    { _id: 1, host: "mongo2.example.com:27017" },
    { _id: 2, host: "mongo3.example.com:27017" }
  ]
})

Piège 3 : Ignorer les paramètres de pool de connexions du pilote

Pourquoi cela arrive : La taille par défaut du pool de connexions du pilote peut être trop petite pour la concurrence de votre application, entraînant des erreurs de connection pool timeout. Les développeurs supposent qu'il s'agit d'un problème de serveur.

Comment éviter : Surveillez l'utilisation du pool de connexions et ajustez maxPoolSize dans les options du pilote. Pour Node.js avec le pilote MongoDB :

const { MongoClient } = require('mongodb');
const client = new MongoClient('mongodb://<user>:<password>@<host>:27017/admin', {
  maxPoolSize: 50,
  connectTimeoutMS: 5000,
  serverSelectionTimeoutMS: 5000
});

Piège 4 : Ne pas encoder les caractères spéciaux dans les chaînes de connexion

Pourquoi cela arrive : Les mots de passe contiennent souvent des caractères comme @, :, / ou ? qui cassent le format de la chaîne de connexion. Le pilote interprète mal la chaîne et échoue avec une erreur confuse.

Comment éviter : Encodez en pourcentage les caractères spéciaux du mot de passe. Par exemple, p@ss:word/ devient p%40ss%3Aword%2F. Utilisez un outil ou une bibliothèque pour construire la chaîne de connexion par programmation.

Piège 5 : Tester uniquement depuis l'hôte de la base de données

Pourquoi cela arrive : L'hôte de la base de données peut généralement se connecter à lui-même via localhost, donnant une fausse impression de sécurité que le réseau est bon.

Comment éviter : Testez toujours depuis l'hôte réel de l'application ou un hôte dans le même segment réseau. Utilisez nc -zv <mongo_host> 27017 depuis là pour vérifier l'accessibilité.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour chaque changement ou session de dépannage réseau MongoDB. Elle suit le schéma observer → changer → vérifier → récupérer.

Attribuez un seul propriétaire responsable pour chaque étape, pas un groupe. Le propriétaire s'assure que l'étape est effectuée et enregistre le résultat. Revisitez la liste de contrôle mensuellement pour intégrer les leçons apprises des incidents.

Conclusion

Le dépannage réseau MongoDB est un processus méthodique. Commencez par une base de faits : version, topologie, liaisons et règles de pare-feu. Utilisez des commandes en lecture seule pour observer avant d'intervenir. Effectuez un petit changement à la fois, vérifiez-le avec des contrôles concrets et ayez toujours un chemin de récupération.

Les outils et commandes de ce guide fonctionnent à travers les versions de MongoDB et les distributions Linux avec des variations mineures. Les principes restent les mêmes : observer, limiter le rayon d'impact, protéger les secrets et vérifier.

Comme prochaine étape, choisissez une vérification à faible risque de la liste de contrôle, comme tester la connectivité TCP depuis votre hôte d'application, et exécutez-la sur votre déploiement actuel. Enregistrez l'état actuel, comparez-le avec le signal attendu et corrigez tout écart en utilisant l'approche structurée décrite ici.

Un flux de travail technique fiable rend les échecs 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.