Centro de Conocimiento DevOps
Centro de Conocimiento DevOps

Resolución de problemas de conexión SSH en Playbooks de Ansible

Esta guía experta proporciona un enfoque sistemático para solucionar problemas comunes de conexión SSH al ejecutar playbooks de Ansible. Aprenda a aprovechar la verbosidad máxima (`-vvv`) para el diagnóstico, resolver errores de autenticación relacionados con claves privadas y permisos, solucionar problemas de `Host key verification failed` (verificación de clave de host fallida) y diagnosticar bloqueos de red. Pasos prácticos y ejemplos de línea de comandos aseguran que pueda aislar y resolver rápidamente la causa raíz de los tiempos de espera de conexión y los mensajes de permiso denegado, restaurando la automatización confiable.

50 vistas

Solución de Problemas de Fallos de Conexión SSH en Playbooks de Ansible

Ansible se basa exclusivamente en el protocolo Secure Shell (SSH) para comunicarse con los nodos gestionados. Cuando un playbook de Ansible falla con un error de conectividad, casi siempre apunta a un problema subyacente en la configuración SSH estándar entre la máquina de control y el host de destino. Comprender cómo diagnosticar sistemáticamente estos fallos es crucial para mantener una automatización fiable.

Esta guía proporciona una metodología paso a paso para diagnosticar y resolver los fallos de conexión SSH más comunes encontrados al ejecutar playbooks de Ansible, asegurando que su gestión de configuración se ejecute sin problemas.

Fase 1: Habilitación de la Verbosidad y Comprobaciones Iniciales

La herramienta más importante para la solución de problemas de Ansible es aumentar la verbosidad de la salida. Los errores de SSH a menudo están enmascarados, pero la verbosidad máxima revela los parámetros exactos que Ansible está utilizando y el mensaje de error específico devuelto por el cliente OpenSSH subyacente.

Usar Banderas de Verbosidad

Ejecute su comando de prueba o playbook con tres o cuatro banderas de verbosidad (-v, -vv, -vvv, -vvvv). La mayoría de los problemas de conexión se resuelven revisando la salida de -vvv.

# Probar la conectividad a un host llamado 'webserver' definido en su inventario
ansible webserver -m ansible.builtin.ping -vvv

# Ejecutar un playbook con depuración máxima
ansible-playbook site.yml -i inventory.ini -vvvv

Verificar el Inventario y el Estado del Host

Asegúrese de que el host al que se dirige esté correctamente definido y sea accesible.

  1. ¿Es Correcto el Nombre del Host? Vuelva a verificar la ortografía en su archivo de inventario (/etc/ansible/hosts o inventario personalizado).
  2. ¿Está Activo el Destino? Asegúrese de que el nodo gestionado esté encendido y accesible en la red.
  3. ¿Son Correctas las Variables del Inventario? Confirme que las variables esenciales como ansible_host (dirección IP o nombre de host) y ansible_user (nombre de usuario remoto) estén configuradas correctamente para el grupo o host de destino.
# Fragmento de Inventario de Ejemplo
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

Fase 2: Verificación de la Conectividad Manual Básica

Si Ansible no puede conectarse, el primer paso debe ser siempre confirmar que el SSH estándar funciona manualmente, utilizando exactamente el mismo usuario, clave y puerto que Ansible tiene configurados.

Prueba Manual de SSH

Si está utilizando un usuario específico (ansible_user) y una clave privada específica (ansible_ssh_private_key_file), replique esa conexión manualmente.

# Prueba SSH estándar (si usa el puerto y la clave predeterminados)
ssh <ansible_user>@<ansible_host>

# Probar utilizando una clave privada y un puerto no predeterminados
ssh -i /path/to/private/key -p 2222 [email protected]

Si la prueba manual de SSH falla, el problema es ambiental, no de Ansible. Solucione el problema central de SSH antes de continuar con Ansible.

Fase 3: Diagnóstico de Fallos de Autenticación

Los fallos de autenticación son la causa más común de problemas de conexión de Ansible. Estos suelen manifestarse como errores de Authentication failed o Permission denied.

3.1 Permisos y Ubicación de la Clave

Si Ansible está utilizando claves SSH, asegúrese de que el archivo de clave privada tenga los permisos correctos y restringidos en la máquina de control. SSH a menudo rechazará las claves que son demasiado permisivas.

# Establecer permisos correctos en el archivo de clave privada
chmod 600 /path/to/private/key

Además, si utiliza un Agente SSH, asegúrese de que su clave esté añadida:

# Iniciar el agente si es necesario
eval "$(ssh-agent -s)"
# Añadir su clave al agente
ssh-add /path/to/private/key

3.2 Fallos en la Solicitud de Contraseña (Tiempo de Espera/Contraseña Faltante)

Si su configuración requiere una contraseña (no recomendada para producción, pero común en laboratorios), Ansible debe proporcionársela. Si la conexión se cuelga o agota el tiempo de espera, es probable que Ansible esté esperando una contraseña que nunca se proporcionó.

Utilice la bandera --ask-pass o -k para solicitar la contraseña de conexión SSH:

ansible webserver -m ansible.builtin.ping -k

3.3 Claves Autorizadas Remotas

Verifique que la clave pública correspondiente a su clave privada esté correctamente instalada en el archivo ~/.ssh/authorized_keys en el nodo gestionado, y que los permisos del archivo y del directorio en el lado remoto sean correctos (700 para .ssh y 600 para authorized_keys).

Fase 4: Resolución de Errores de Clave de Host

Ansible respeta el archivo known_hosts, que almacena la huella digital de los servidores remotos. Si la clave de host de un nodo gestionado cambia (por ejemplo, debido a una reconstrucción o reasignación de IP), los intentos de conexión SSH fallarán con una advertencia que parece un ataque Man-in-the-Middle.

El Error Host key verification failed

Cuando ocurre este error, debe actualizar o eliminar la entrada de clave en conflicto.

  1. Identifique el número de línea en ~/.ssh/known_hosts mencionado en la salida de error.
  2. Elimine la entrada utilizando ssh-keygen.
# Reemplace <hostname_or_ip> con el host que falla
ssh-keygen -R <hostname_or_ip>

⚠️ Advertencia de Seguridad: Desactivar la Verificación de Host

Para pruebas temporales o en entornos de laboratorio altamente controlados donde se espera inestabilidad del host, puede configurar Ansible para que ignore la verificación de la clave del host. Esto está fuertemente desaconsejado para entornos de producción, ya que lo expone a ataques MITM.

En su ansible.cfg (o variable de entorno temporal):
ini [defaults] host_key_checking = False

Fase 5: Problemas de Red, Firewall y Entorno Remoto

A veces, SSH se conecta, pero la conexión se detiene o falla debido a la configuración de red o a restricciones en la máquina de destino.

5.1 Bloqueo por Firewall

Si la conexión agota el tiempo de espera sin una solicitud, es probable que un firewall esté bloqueando el intento de conexión. Verifique el firewall en tres puntos:

  1. Local (Máquina de Control): Asegúrese de que el tráfico saliente en el puerto 22 (o puerto personalizado) esté permitido.
  2. Ruta de Red: Asegúrese de que no haya ACLs de red intermedias o firewalls corporativos bloqueando el tráfico.
  3. Remoto (Nodo Gestionado): Verifique que el firewall del host remoto (firewalld, ufw, etc.) tenga SSH (generalmente puerto 22) abierto y configurado para la interfaz de red correcta.

5.2 Errores del Intérprete de Python

Ansible requiere un intérprete de Python en el nodo gestionado para ejecutar módulos. Aunque no es estrictamente un fallo de SSH, la fase inicial de conexión de Ansible implica la recopilación de hechos, que es una ejecución de script de Python. Si la máquina de destino es una instalación mínima sin Python 3, la conexión puede fallar durante la fase de configuración.

Si su destino utiliza Python 3 pero la ruta del intérprete no es estándar (por ejemplo, python3.8 en lugar de python3), especifique la ruta correcta en su inventario:

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

5.3 Contexto de SELinux o AppArmor

En casos raros, módulos de seguridad excesivamente estrictos como SELinux (en RHEL/CentOS/Fedora) o AppArmor (en Ubuntu/Debian) podrían impedir que el perfil de shell o los permisos de directorio del usuario remoto sean accedidos correctamente durante la sesión SSH. Verifique los registros de auditoría del host remoto (/var/log/audit/audit.log o equivalente) en busca de denegaciones de AVC relacionadas con SSH o el acceso al directorio personal del usuario.

Resumen de Errores Comunes de Conexión y Soluciones

Mensaje de Error Causa Probable Solución Aplicable
Permission denied (publickey). Clave no reconocida o permisos de clave incorrectos. chmod 600 en la clave privada; verifique la clave pública en el host remoto.
Host key verification failed. La clave de host cambió o el archivo known_hosts está corrupto. Use ssh-keygen -R hostname para eliminar la entrada antigua.
Connection timed out. Bloqueo de firewall o host caído/inaccesible. Verifique la conectividad manual (ping, ssh); verifique las reglas del firewall en el host de destino.
Connection hangs/stalls. Esperando la entrada de contraseña que no se proporcionó. Ejecute con -k o configure la autenticación basada en clave.

Conclusión

La solución de problemas de conexión SSH en Ansible es principalmente un proceso sistemático de depuración de la configuración del cliente SSH subyacente. Al comenzar con comprobaciones básicas de conectividad manual, aumentar la verbosidad (-vvv) y verificar metódicamente la autenticación, las claves de host y las rutas de red, puede aislar y resolver rápidamente la mayoría de los fallos de conectividad, permitiendo que sus flujos de trabajo de automatización continúen sin interrupción.