Risoluzione dei problemi di connessione SSH nelle playbook Ansible

Ansible si affida esclusivamente al protocollo Secure Shell (SSH) per comunicare con i nodi gestiti. Quando una playbook Ansible fallisce con un errore di connettività, quasi sempre indica un problema sottostante nella configurazione SSH standard tra la macchina di controllo e l'host di destinazione. Comprendere come diagnosticare sistematicamente questi errori è fondamentale per mantenere un'automazione affidabile.

Questa guida fornisce una metodologia passo passo per diagnosticare e risolvere i problemi di connessione SSH più comuni riscontrati durante l'esecuzione delle playbook Ansible, garantendo che la gestione della configurazione proceda senza intoppi.

Fase 1: Abilitazione della verbosità e controlli iniziali

Lo strumento più importante nella risoluzione dei problemi di Ansible è l'aumento della verbosità dell'output. Gli errori SSH sono spesso mascherati, ma la massima verbosità rivela i parametri esatti che Ansible sta utilizzando e il messaggio di errore specifico restituito dal client OpenSSH sottostante.

Utilizzo dei flag di verbosità

Esegui il tuo comando di test o la tua playbook con tre o quattro flag di verbosità (-v, -vv, -vvv, -vvvv). La maggior parte dei problemi di connessione viene risolta esaminando l'output da -vvv.

# Testa la connettività a un host denominato 'webserver' definito nel tuo inventario
ansible webserver -m ansible.builtin.ping -vvv

# Esegui una playbook con il debug massimo
ansible-playbook site.yml -i inventory.ini -vvvv

Verifica dell'inventario e dello stato dell'host

Assicurati che l'host che stai indirizzando sia definito correttamente e raggiungibile.

1. Il nome dell'host è corretto? Ricontrolla l'ortografia nel tuo file di inventario (/etc/ansible/hosts o inventario personalizzato).
2. Il target è attivo? Assicurati che il nodo gestito sia acceso e accessibile sulla rete.
3. Le variabili di inventario sono corrette? Conferma che le variabili essenziali come ansible_host (indirizzo IP o nome host) e ansible_user (nome utente remoto) siano impostate correttamente per il gruppo o l'host di destinazione.

# Esempio di snippet di inventario
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

Fase 2: Verifica della connettività manuale di base

Se Ansible non riesce a connettersi, il primo passo deve essere sempre quello di confermare che SSH standard funzioni manualmente, utilizzando esattamente lo stesso utente, chiave e porta che Ansible è configurato per utilizzare.

Test SSH manuale

Se stai utilizzando un utente specifico (ansible_user) e una chiave privata specifica (ansible_ssh_private_key_file), replica quella connessione manualmente.

# Test SSH standard (se si utilizza la porta e la chiave predefinite)
ssh <ansible_user>@<ansible_host>

# Test utilizzando una chiave privata e una porta non predefinite
ssh -i /path/to/private/key -p 2222 [email protected]

Se il test SSH manuale fallisce, il problema è ambientale, non di Ansible. Risolvi il problema SSH di base prima di procedere con Ansible.

Fase 3: Diagnosi dei fallimenti di autenticazione

I fallimenti di autenticazione sono la causa più comune dei problemi di connessione di Ansible. Questi di solito si manifestano come errori Authentication failed (Autenticazione fallita) o Permission denied (Permesso negato).

3.1 Autorizzazioni e posizione della chiave

Se Ansible utilizza chiavi SSH, assicurati che il file della chiave privata abbia le autorizzazioni corrette e limitate sulla macchina di controllo. SSH spesso rifiuta le chiavi troppo permissive.

# Imposta le autorizzazioni corrette sul file della chiave privata
chmod 600 /path/to/private/key

Inoltre, se utilizzi un agente SSH, assicurati che la tua chiave sia aggiunta:

# Avvia l'agente se necessario
eval "$(ssh-agent -s)"
# Aggiungi la tua chiave all'agente
ssh-add /path/to/private/key

3.2 Fallimenti di richiesta password (Timeout/Password mancante)

Se la tua configurazione richiede una password (non consigliata per la produzione ma comune nei laboratori), Ansible deve riceverla. Se la connessione si blocca o scade, Ansible è probabilmente in attesa di una password che non è mai stata fornita.

Utilizza il flag --ask-pass o -k per richiedere la password di connessione SSH:

ansible webserver -m ansible.builtin.ping -k

3.3 Chiavi autorizzate remote

Verifica che la chiave pubblica corrispondente alla tua chiave privata sia installata correttamente nel file ~/.ssh/authorized_keys sul nodo gestito e che le autorizzazioni del file e della directory sul lato remoto siano corrette (700 per .ssh e 600 per authorized_keys).

Fase 4: Risoluzione degli errori relativi alle chiavi host

Ansible rispetta il file known_hosts, che memorizza l'impronta digitale del server remoto. Se la chiave host di un nodo gestito cambia (ad esempio, a causa di una ricostruzione o di una riassegnazione dell'IP), i tentativi di connessione SSH falliranno con un avviso che assomiglia a un attacco Man-in-the-Middle.

Errore Host key verification failed (Verifica chiave host fallita)

Quando si verifica questo errore, è necessario aggiornare o rimuovere la voce chiave in conflitto.

1. Identifica il numero di riga in ~/.ssh/known_hosts menzionato nell'output dell'errore.
2. Rimuovi la voce usando ssh-keygen.

# Sostituisci <hostname_or_ip> con l'host con errore effettivo
ssh-keygen -R <hostname_or_ip>

⚠️ Avviso di sicurezza: Disabilitazione del controllo host

Per test temporanei o in ambienti di laboratorio altamente controllati in cui è prevista l'instabilità dell'host, è possibile configurare Ansible per ignorare il controllo delle chiavi host. Questa operazione è fortemente sconsigliata per gli ambienti di produzione poiché ti espone ad attacchi MITM.

Nel tuo ansible.cfg (o variabile d'ambiente temporanea):
ini [defaults] host_key_checking = False

Fase 5: Problemi di rete, firewall e ambiente remoto

A volte SSH si connette, ma la connessione si interrompe o fallisce a causa della configurazione di rete o delle restrizioni sulla macchina di destinazione.

5.1 Blocco del firewall

Se la connessione scade senza una richiesta, è probabile che un firewall stia bloccando il tentativo di connessione. Controlla il firewall su tre punti:

1. Locale (Macchina di controllo): Assicurati che il traffico in uscita sulla porta 22 (o porta personalizzata) sia consentito.
2. Percorso di rete: Assicurati che eventuali ACL di rete intermedie o firewall aziendali non stiano bloccando il traffico.
3. Remoto (Nodo gestito): Verifica che il firewall dell'host remoto (firewalld, ufw, ecc.) abbia la porta SSH (solitamente 22) aperta e configurata per la corretta interfaccia di rete.

5.2 Errori dell'interprete Python

Ansible richiede un interprete Python sul nodo gestito per eseguire i moduli. Sebbene non sia strettamente un errore SSH, la fase di connessione iniziale di Ansible comporta la raccolta dei fatti, che è un'esecuzione di script Python. Se la macchina di destinazione è un'installazione minima senza Python 3, la connessione può fallire durante la fase di configurazione.

Se il tuo target utilizza Python 3 ma il percorso dell'interprete non è standard (ad esempio, python3.8 invece di python3), specifica il percorso corretto nel tuo inventario:

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

5.3 Contesto SELinux o AppArmor

In rari casi, moduli di sicurezza eccessivamente restrittivi come SELinux (su RHEL/CentOS/Fedora) o AppArmor (su Ubuntu/Debian) potrebbero impedire l'accesso corretto al profilo shell o alle autorizzazioni della directory dell'utente remoto durante la sessione SSH. Controlla i log di audit dell'host remoto (/var/log/audit/audit.log o equivalente) per i dinieghi AVC relativi ad SSH o all'accesso alla directory home dell'utente.

Riepilogo degli errori di connessione comuni e delle soluzioni

Messaggio di errore	Causa probabile	Correzione attuabile
Permission denied (publickey).	La chiave non è riconosciuta o le autorizzazioni della chiave non sono corrette.	chmod 600 sulla chiave privata; verifica la chiave pubblica sull'host remoto.
Host key verification failed.	La chiave host è cambiata o il file known_hosts è corrotto.	Usa ssh-keygen -R hostname per rimuovere la vecchia voce.
Connection timed out.	Blocco del firewall o host è spento/irraggiungibile.	Controlla la connettività manuale (ping, ssh); verifica le regole del firewall sull'host di destinazione.
La connessione si blocca/interrompe.	In attesa di input di password che non è stato fornito.	Esegui con -k o configura l'autenticazione basata su chiave.

Conclusione

La risoluzione dei problemi di connessione SSH in Ansible è principalmente un processo sistematico di debug della configurazione del client SSH sottostante. Iniziando con controlli di connettività manuali di base, aumentando la verbosità (-vvv) e verificando metodicamente l'autenticazione, le chiavi host e i percorsi di rete, è possibile isolare e risolvere rapidamente la maggior parte dei fallimenti di connettività, consentendo ai flussi di lavoro di automazione di procedere senza interruzioni.