Dépannage des échecs de connexion SSH dans les playbooks Ansible

Ansible repose exclusivement sur le protocole Secure Shell (SSH) pour communiquer avec les nœuds gérés. Lorsqu'un playbook Ansible échoue avec une erreur de connectivité, cela pointe presque toujours vers un problème sous-jacent dans la configuration SSH standard entre la machine de contrôle et l'hôte cible. Comprendre comment diagnostiquer systématiquement ces échecs est crucial pour maintenir une automatisation fiable.

Ce guide fournit une méthodologie étape par étape pour diagnostiquer et résoudre les échecs de connexion SSH les plus courants rencontrés lors de l'exécution de playbooks Ansible, garantissant ainsi le bon déroulement de votre gestion de configuration.

Phase 1 : Activation de la verbosité et vérifications initiales

L'outil le plus important dans le dépannage Ansible est l'augmentation de la verbosité de la sortie. Les erreurs SSH sont souvent masquées, mais une verbosité maximale révèle les paramètres exacts qu'Ansible utilise et le message d'erreur spécifique renvoyé par le client OpenSSH sous-jacent.

Utiliser les indicateurs de verbosité

Exécutez votre commande de test ou votre playbook avec trois ou quatre indicateurs de verbosité (-v, -vv, -vvv, -vvvv). La plupart des problèmes de connexion sont résolus en examinant la sortie de -vvv.

# Tester la connectivité à un hôte nommé 'webserver' défini dans votre inventaire
ansible webserver -m ansible.builtin.ping -vvv

# Exécuter un playbook avec un débogage maximal
ansible-playbook site.yml -i inventory.ini -vvvv

Vérifier l'inventaire et l'état de l'hôte

Assurez-vous que l'hôte que vous ciblez est correctement défini et accessible.

Le nom d'hôte est-il correct ? Vérifiez l'orthographe dans votre fichier d'inventaire (/etc/ansible/hosts ou inventaire personnalisé).
La cible est-elle allumée ? Assurez-vous que le nœud géré est allumé et accessible sur le réseau.
Les variables d'inventaire sont-elles correctes ? Confirmez que les variables essentielles telles que ansible_host (adresse IP ou nom d'hôte) et ansible_user (nom d'utilisateur distant) sont correctement définies pour le groupe ou l'hôte cible.

# Extrait d'inventaire exemple
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

Phase 2 : Vérification de la connectivité manuelle de base

Si Ansible ne peut pas se connecter, la première étape doit toujours être de confirmer que SSH standard fonctionne manuellement, en utilisant exactement le même utilisateur, la même clé et le même port qu'Ansible est configuré pour utiliser.

Test SSH manuel

Si vous utilisez un utilisateur spécifique (ansible_user) et une clé privée spécifique (ansible_ssh_private_key_file), reproduisez cette connexion manuellement.

# Test SSH standard (si vous utilisez le port et la clé par défaut)
ssh <ansible_user>@<ansible_host>

# Tester en utilisant une clé privée et un port non standard
ssh -i /chemin/vers/cle/privee -p 2222 [email protected]

Si le test SSH manuel échoue, le problème est environnemental, pas Ansible. Résolvez le problème SSH principal avant de continuer avec Ansible.

Phase 3 : Diagnostic des échecs d'authentification

Les échecs d'authentification sont la cause la plus fréquente des problèmes de connexion Ansible. Ceux-ci se manifestent généralement par des erreurs Authentication failed ou Permission denied.

3.1 Permissions et emplacement des clés

Si Ansible utilise des clés SSH, assurez-vous que le fichier de clé privée a les permissions correctes et restreintes sur la machine de contrôle. SSH rejettera souvent les clés trop permissives.

# Définir les permissions correctes sur le fichier de clé privée
chmod 600 /chemin/vers/cle/privee

De plus, si vous utilisez un agent SSH, assurez-vous que votre clé est ajoutée :

# Démarrer l'agent si nécessaire
eval "$(ssh-agent -s)"
# Ajouter votre clé à l'agent
ssh-add /chemin/vers/cle/privee

3.2 Échecs d'invite de mot de passe (Délai d'attente/Mot de passe manquant)

Si votre configuration nécessite un mot de passe (non recommandé pour la production mais courant dans les laboratoires), Ansible doit en être pourvu. Si la connexion se bloque ou expire, Ansible attend probablement un mot de passe qui n'a jamais été fourni.

Utilisez l'indicateur --ask-pass ou -k pour être invité à entrer le mot de passe de connexion SSH :

ansible webserver -m ansible.builtin.ping -k

3.3 Clés autorisées distantes

Vérifiez que la clé publique correspondant à votre clé privée est correctement installée dans le fichier ~/.ssh/authorized_keys sur le nœud géré, et que les permissions du fichier et du répertoire du côté distant sont correctes (700 pour .ssh et 600 pour authorized_keys).

Phase 4 : Résolution des erreurs de clé d'hôte

Ansible respecte le fichier known_hosts, qui stocke l'empreinte numérique des serveurs distants. Si la clé d'hôte d'un nœud géré change (par exemple, en raison d'une reconstruction ou d'une réaffectation d'IP), les tentatives de connexion SSH échoueront avec un avertissement ressemblant à une attaque de l'homme du milieu.

L'erreur `Host key verification failed`

Lorsque cette erreur se produit, vous devez mettre à jour ou supprimer l'entrée de clé conflictuelle.

Identifiez le numéro de ligne dans ~/.ssh/known_hosts mentionné dans la sortie d'erreur.
Supprimez l'entrée à l'aide de ssh-keygen.

# Remplacez <hostname_or_ip> par l'hôte défaillant réel
ssh-keygen -R <hostname_or_ip>

⚠️ Avertissement de sécurité : Désactivation de la vérification d'hôte

Pour les tests temporaires ou dans des environnements de laboratoire hautement contrôlés où une instabilité de l'hôte est attendue, vous pouvez configurer Ansible pour ignorer la vérification de la clé d'hôte. Cela est fortement déconseillé pour les environnements de production car cela vous expose aux attaques MITM.

Dans votre ansible.cfg (ou variable d'environnement temporaire) :
ini [defaults] host_key_checking = False

Phase 5 : Problèmes de réseau, de pare-feu et d'environnement distant

Parfois, SSH se connecte, mais la connexion plante ou échoue en raison de la configuration réseau ou de restrictions sur la machine cible.

5.1 Blocage par le pare-feu

Si la connexion expire sans invite, un pare-feu bloque probablement la tentative de connexion. Vérifiez le pare-feu à trois points :

Local (Machine de contrôle) : Assurez-vous que le trafic sortant sur le port 22 (ou port personnalisé) est autorisé.
Chemin réseau : Assurez-vous qu'aucune ACL réseau intermédiaire ou pare-feu d'entreprise ne bloque le trafic.
Distant (Nœud géré) : Vérifiez que le pare-feu de l'hôte distant (firewalld, ufw, etc.) a le service SSH (généralement le port 22) ouvert et configuré pour la bonne interface réseau.

5.2 Erreurs d'interpréteur Python

Ansible nécessite un interpréteur Python sur le nœud géré pour exécuter des modules. Bien qu'il ne s'agisse pas strictement d'un échec SSH, la phase de connexion initiale d'Ansible implique la collecte de faits, qui est l'exécution d'un script Python. Si la machine cible est une installation minimale sans Python 3, la connexion peut échouer pendant la phase de configuration.

Si votre cible utilise Python 3 mais que le chemin de l'interpréteur est non standard (par exemple, python3.8 au lieu de python3), spécifiez le bon chemin dans votre inventaire :

[target_host]
ansible_python_interpreter=/usr/bin/python3.8

5.3 Contexte SELinux ou AppArmor

Dans de rares cas, des modules de sécurité trop stricts comme SELinux (sur RHEL/CentOS/Fedora) ou AppArmor (sur Ubuntu/Debian) peuvent empêcher l'accès correct au profil shell de l'utilisateur distant ou aux permissions de répertoire pendant la session SSH. Vérifiez les journaux d'audit de l'hôte distant (/var/log/audit/audit.log ou équivalent) pour les dénis AVC liés à SSH ou à l'accès au répertoire personnel de l'utilisateur.

Résumé des erreurs de connexion courantes et de leurs solutions

Message d'erreur	Cause probable	Correction actionnable
`Permission denied (publickey).`	Clé non reconnue ou mauvaises permissions de clé.	`chmod 600` sur la clé privée ; vérifiez la clé publique sur l'hôte distant.
`Host key verification failed.`	Clé d'hôte modifiée ou fichier known_hosts corrompu.	Utilisez `ssh-keygen -R hostname` pour supprimer l'ancienne entrée.
`Connection timed out.`	Blocage par pare-feu ou hôte hors service/inaccessible.	Vérifiez la connectivité manuelle (`ping`, `ssh`) ; vérifiez les règles de pare-feu sur l'hôte cible.
Connexion plantée/bloquée.	Attente de saisie de mot de passe non fournie.	Exécutez avec `-k` ou configurez l'authentification par clé.

Conclusion

Le dépannage des problèmes de connexion SSH dans Ansible est principalement un processus systématique de débogage de la configuration du client SSH sous-jacent. En commençant par des vérifications de connectivité manuelle de base, en augmentant la verbosité (-vvv), et en vérifiant méthodiquement l'authentification, les clés d'hôte et les chemins réseau, vous pouvez rapidement isoler et résoudre la plupart des échecs de connectivité, permettant à vos flux de travail d'automatisation de se poursuivre sans interruption.