Solución de Problemas Comunes de Conectividad de Agentes Jenkins y Soluciones

Los agentes Jenkins, también llamados nodos, son donde se ejecuta la mayor parte del trabajo de compilación. Cuando uno se desconecta, el síntoma es obvio: los trabajos se quedan en la cola, las etiquetas no se pueden satisfacer y los equipos comienzan a reejecutar compilaciones que nunca iban a comenzar. El trabajo útil es averiguar qué capa falló: accesibilidad de red, SSH, remoting entrante, Java, credenciales, disco o el propio controlador.

Entender por qué un agente puede volverse inalcanzable es el primer paso para una solución de problemas efectiva. Estos problemas pueden deberse a configuraciones de red incorrectas, configuración incorrecta del agente, restricciones de firewall o problemas con el propio controlador Jenkins. Al verificar sistemáticamente estas áreas, puedes identificar rápidamente la causa raíz e implementar una solución.

Causas Comunes de Desconexión de Agentes Jenkins

Varios factores pueden llevar a que un agente se desconecte. Identificar el síntoma específico es clave para reducir las causas potenciales:

Agente inalcanzable: El controlador Jenkins no puede establecer una conexión con el agente.
Conexión rechazada: La máquina agente rechaza activamente el intento de conexión del controlador.
El agente informa desconexión después de una conexión exitosa: El agente estaba conectado pero ha perdido su conexión.
Errores JSch (para agentes basados en SSH): Errores específicos relacionados con la biblioteca Java Secure Channel utilizada para conexiones SSH.

Problemas de Red y Firewall

La conectividad de red es el culpable más frecuente de los problemas de conexión de agentes. Asegurarse de que el controlador Jenkins pueda alcanzar la máquina agente y viceversa es primordial.

Verificación de Accesibilidad de Red

Antes de profundizar en configuraciones específicas de Jenkins, confirma la conectividad básica de red:

Hacer ping al agente: Desde la máquina del controlador Jenkins, intenta hacer ping a la dirección IP o nombre de host de la máquina agente.
```
ping <nombre-host-o-ip-del-agente>
```
Telnet al puerto del agente: Prueba si el puerto que Jenkins usa para conectarse al agente está abierto y escuchando. Para agentes JNLP, este es típicamente el puerto 50000. Para agentes SSH, es el puerto SSH (por defecto 22).
```
telnet <nombre-host-o-ip-del-agente> <puerto-del-agente>
```
Si la conexión se agota o es rechazada, probablemente hay un problema de red o firewall bloqueando el puerto.

Configuración del Firewall

Los firewalls en el controlador Jenkins, la máquina agente o los dispositivos de red intermedios pueden bloquear los puertos necesarios.

Firewall del Controlador Jenkins: Asegúrate de que el controlador pueda iniciar conexiones al puerto del agente.
Firewall de la Máquina Agente: Asegúrate de que el firewall de la máquina agente (por ejemplo, ufw, firewalld, Firewall de Windows) permita conexiones entrantes en el puerto del agente desde la dirección IP del controlador Jenkins.
Firewalls de Red: Si tu red tiene firewalls internos, verifica que el tráfico esté permitido entre el controlador y el agente.

Ejemplo: Permitir el Puerto 50000 en un Agente (Linux con `ufw`)

# Permitir conexiones desde una IP específica (controlador Jenkins)
sudo ufw allow from <ip-controlador-jenkins> to any port 50000

# O permitir desde cualquier IP (menos seguro)
sudo ufw allow 50000

# Recargar reglas del firewall
sudo ufw reload

Ejemplo: Permitir el Puerto 22 en un Agente (Linux con `firewalld`)

# Permitir el servicio SSH permanentemente desde una IP de origen específica
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<ip-controlador-jenkins>" port protocol="tcp" port="22" accept'

# Recargar reglas del firewall
sudo firewall-cmd --reload

Consejo: Siempre prioriza permitir conexiones desde direcciones IP específicas para una mejor seguridad.

Problemas de Configuración del Agente Jenkins

Las configuraciones incorrectas dentro de Jenkins o en el propio agente son fuentes comunes de problemas de conectividad.

Configuración del Agente JNLP

Los agentes de Java Network Launch Protocol (JNLP) se comunican con el controlador Jenkins utilizando un puerto dedicado. La configuración principal involucra el método de lanzamiento del agente y los puertos disponibles del controlador.

Agente Desconectado en la Interfaz de Usuario de Jenkins

Si un agente aparece desconectado en la interfaz de usuario de Jenkins, significa que el controlador no pudo establecer o mantener una conexión.

Verificar el Método de Lanzamiento del Agente: Asegúrate de que el agente esté configurado para lanzarse correctamente. Los métodos comunes incluyen:
- Lanzar agente conectándolo al maestro: Esto requiere iniciación manual desde el lado del agente.
- Lanzar agente vía SSH: Configurado a través de credenciales SSH y configuraciones de host.
- Lanzar agente usando propiedades de nodo incorporadas: Para escenarios específicos.
Verificar la Disponibilidad del Puerto JNLP: El controlador Jenkins necesita escuchar en el puerto JNLP configurado (por defecto 50000). Navega a Administrar Jenkins -> Sistema -> Avanzado -> Archivo -> Puerto TCP para agentes JNLP y asegúrate de que esté configurado y accesible.

"Conexión rechazada" al lanzar el Agente JNLP

Esto a menudo significa que el puerto JNLP (por defecto 50000) en el controlador Jenkins no está abierto o accesible desde la máquina agente. Verifica las reglas del firewall en el controlador y asegúrate de que el puerto esté configurado correctamente.

Consejo: Reiniciar el controlador Jenkins a veces puede resolver problemas transitorios del puerto JNLP.

Configuración del Agente SSH

Al usar SSH para conectarse a los agentes, varios factores pueden causar problemas:

Credenciales SSH Incorrectas: Verifica el nombre de usuario, la contraseña o la clave privada configurados en Jenkins para la conexión SSH. Asegúrate de que la clave privada tenga el formato correcto (por ejemplo, formato PEM) y tenga los permisos correctos.
Servidor SSH No Ejecutándose en el Agente: Asegúrate de que el demonio SSH (sshd) se esté ejecutando en la máquina agente.
```
# En la máquina agente
sudo systemctl status sshd
# o
sudo service ssh status
```
Si no se está ejecutando, inícialo:
```
sudo systemctl start sshd
sudo systemctl enable sshd
```
Discrepancia en el Puerto SSH: Asegúrate de que el puerto configurado en Jenkins para SSH coincida con el puerto en el que el servidor SSH está escuchando (por defecto 22).
Resolución del Nombre de Host/Dirección IP del Agente: El controlador Jenkins debe poder resolver el nombre de host o la dirección IP del agente.
Permisos de la Clave SSH: En la máquina agente, el archivo ~/.ssh/authorized_keys para el usuario con el que Jenkins se conecta debe tener los permisos correctos (generalmente 600).

Ejemplo: Probar la Conexión SSH Manualmente

Desde la máquina del controlador Jenkins, intenta SSH al agente usando las mismas credenciales y puerto configurados en Jenkins:

ssh -p <puerto-ssh> <usuario-jenkins>@<nombre-host-o-ip-del-agente>

Si este comando SSH manual falla, el problema está fuera de la configuración SSH de Jenkins, probablemente en la red, el firewall o la configuración del servidor SSH en el agente.

Permisos del Directorio de Trabajo del Agente

Jenkins requiere permisos específicos para operar en el sistema de archivos del agente. El usuario que Jenkins usa para conectarse al agente (o el usuario que ejecuta el proceso del agente) necesita permisos de escritura en el directorio de trabajo configurado del agente.

Verificar propietario y permisos: En el agente, verifica la propiedad y los permisos del directorio de inicio de Jenkins y sus subdirectorios.
```
ls -ld /ruta/al/hogar/agente/jenkins
ls -l /ruta/al/hogar/agente/jenkins
```
Conceder permisos (si es necesario): Asegúrate de que el usuario con el que Jenkins se conecta tenga acceso de lectura y escritura. Usa chown y chmod con precaución.

Problemas del Controlador Jenkins

A veces, el problema puede no estar en el agente sino en el propio controlador Jenkins.

Sobrecarga del Controlador

Si el controlador Jenkins está bajo una carga pesada (muchos trabajos ejecutándose, alto uso de CPU/memoria), podría tener dificultades para gestionar las conexiones de los agentes. Monitorea la utilización de recursos del controlador.

Conflictos de Puerto JNLP

Si el puerto JNLP (por defecto 50000) ya está siendo utilizado por otro proceso en el controlador Jenkins, los agentes no podrán conectarse.

Verificar el uso del puerto: En la máquina del controlador, usa netstat o ss para ver qué proceso está usando el puerto.
```
sudo netstat -tulnp | grep 50000
# o
sudo ss -tulnp | grep 50000
```
Si otro proceso lo está usando, necesitarás reconfigurar Jenkins o la otra aplicación para que usen puertos diferentes.

Solución de Problemas Avanzada y Registros

Cuando las comprobaciones estándar no revelan el problema, se necesita una investigación más profunda.

Registros del Controlador Jenkins

Revisa los registros del controlador Jenkins en busca de errores relacionados con las conexiones de los agentes. Estos registros pueden proporcionar mensajes de error específicos.

Ubicación: Generalmente se encuentra en $JENKINS_HOME/jenkins.log o accesible a través de Administrar Jenkins -> Registro del Sistema.
Buscar: Mensajes que mencionen el nombre de host del agente, la dirección IP, los intentos de conexión, las excepciones JSch o errores de Conexión rechazada.

Registros del Agente

Si el agente se está ejecutando pero informa que está desconectado, verifica sus registros en busca de errores.

Agentes JNLP: El propio proceso del agente podría generar registros en su consola o en un archivo de registro designado.
Agentes SSH: Los registros pueden estar en $JENKINS_HOME/agent.log en la máquina agente, o relacionados con sshd si la conexión falla a nivel SSH.

Habilitar Registro de Depuración

Para problemas muy persistentes, habilitar temporalmente el registro de depuración para componentes relevantes de Jenkins puede proporcionar información más detallada.

Comunicación JNLP/Agente: Es posible que necesites ajustar las propiedades del sistema Java o usar la configuración de registro de Jenkins (Administrar Jenkins -> Registro del Sistema -> Grabadores de Registro) para aumentar la verbosidad de hudson.slaves o paquetes relacionados.

Hábitos Prácticos que Previenen Cortes Repetidos

La solución de problemas de conectividad de agentes Jenkins requiere un enfoque sistemático, comenzando con comprobaciones básicas de red y progresando a configuraciones específicas de Jenkins.

Verificar Red: Siempre comienza con ping y telnet/nc para asegurar la accesibilidad básica de red y el acceso al puerto.
Verificar Firewalls: Asegúrate de que los firewalls tanto en el controlador como en el agente, así como cualquier firewall de red, permitan el tráfico en los puertos requeridos.
Validar Credenciales: Vuelve a verificar las claves SSH, nombres de usuario y contraseñas.
Confirmar Servicio del Agente: Para agentes SSH, asegúrate de que sshd se esté ejecutando y sea accesible.
Monitorear Registros de Jenkins: Los registros del controlador son tu fuente principal para entender las fallas de conexión.
Usar IPs Específicas: Cuando sea posible, configura firewalls y Jenkins para usar direcciones IP específicas en lugar de rangos amplios o 0.0.0.0.

Siguiendo estos pasos, puedes diagnosticar y resolver efectivamente la mayoría de los problemas comunes de conectividad de agentes Jenkins, manteniendo tus pipelines de CI/CD funcionando sin problemas.

Leyendo el Mensaje de Desconexión Sin Adivinar

La palabra "offline" es demasiado amplia para solucionar problemas por sí sola. Antes de cambiar la configuración de Jenkins, abre la página del agente y lee la razón exacta que Jenkins da. Hay una gran diferencia entre "conexión rechazada", "permiso denegado", "verificación de clave de host fallida", "agente JNLP rechazado" y "canal fue cerrado". Todos terminan con un nodo desconectado, pero apuntan a diferentes capas.

Normalmente escribo el síntoma en lenguaje sencillo: "el controlador no puede alcanzar el puerto TCP 22", "el inicio de sesión SSH funciona pero Java no puede iniciar", "el agente entrante se inicia pero no puede llamar de vuelta al controlador", o "el agente se conecta y luego se cae durante las compilaciones". Esa frase mantiene la investigación enfocada.

Si el agente nunca se ha conectado, sospecha de configuración, DNS, firewall, credenciales o comando de lanzamiento. Si se conectó durante meses y comenzó a fallar hoy, verifica los cambios recientes: claves SSH rotadas, una actualización de Jenkins, una actualización de plugin, una nueva regla de firewall, un certificado caducado, una reconstrucción de imagen del agente o un cambio en la red de la nube. La línea de tiempo a menudo es más útil que el texto del error.

Agentes SSH: Separa los Problemas de Inicio de Sesión de los Problemas de Lanzamiento

Para agentes basados en SSH, prueba la misma ruta que usa Jenkins. Desde el host del controlador, conéctate como el usuario configurado en Jenkins:

ssh -vvv usuario-agente-jenkins@nombre-host-agente

La salida detallada te dice si la falla ocurre antes de la autenticación, durante la autenticación o después del inicio de sesión. Si SSH nunca llega al servidor, Jenkins no puede arreglar eso. Verifica el enrutamiento, los grupos de seguridad, las ACL de red, los firewalls del host y el demonio SSH. Si SSH llega al servidor pero rechaza la clave, verifica la credencial en Jenkins, el authorized_keys del usuario, los permisos de archivo y si la cuenta está bloqueada.

Si el inicio de sesión SSH funciona manualmente pero Jenkins aún falla, mira el directorio raíz remoto y el inicio de Java. Jenkins necesita un directorio escribible para los archivos de remoting, y el usuario del agente necesita permiso para crear archivos allí. Un error común es apuntar la raíz remota a una ruta propiedad de root o limpiada por otro proceso.

Ejecuta estas comprobaciones en el agente:

whoami
pwd
java -version
test -w /ruta/al/agente-jenkins && echo escribible
df -h /ruta/al/agente-jenkins

La versión de Java importa porque los controladores Jenkins modernos requieren versiones de Java compatibles en los agentes. El requisito exacto depende de tu versión de Jenkins, así que consulta la documentación de Jenkins para tu versión en lugar de asumir que una imagen de agente antigua sigue siendo válida.

Agentes Entrantes: La Ruta de Devolución de Llamada es la Trampa Habitual

Los agentes entrantes se usan a menudo cuando el controlador no puede iniciar SSH al agente, como agentes detrás de NAT o en redes restringidas. El proceso del agente se inicia fuera de Jenkins y se conecta de vuelta al controlador. Eso significa que la ruta de red está invertida: el agente debe resolver y alcanzar la URL de Jenkins.

En el host del agente, prueba la URL de Jenkins exactamente como está configurada:

curl -I https://jenkins.ejemplo.com/

Si Jenkins está detrás de un proxy inverso, confirma que la URL pública en Administrar Jenkins > Sistema sea correcta. Una URL de Jenkins incorrecta puede hacer que los comandos generados del agente apunten a un nombre de host interno que el agente no puede resolver. Si el modo WebSocket está habilitado para agentes entrantes, asegúrate de que el proxy admita los encabezados de actualización de WebSocket. Si usas el puerto TCP del agente entrante, confirma que el puerto fijo esté configurado y sea accesible desde la red del agente.

Los problemas de TLS pueden parecer problemas de Jenkins. Si el agente se ejecuta en una imagen de contenedor mínima, es posible que no tenga tu certificado CA interno. curl generalmente expondrá eso rápidamente. Instala el certificado CA en la imagen del agente en lugar de deshabilitar la verificación del certificado.

Agentes que se Desconectan Durante las Compilaciones

Un agente que se conecta exitosamente y luego se cae durante una compilación generalmente no es un problema básico de conectividad. Mira la presión de recursos y el ciclo de vida del proceso.

Verifica si el sistema operativo mató el proceso del agente:

dmesg -T | grep -i -E 'killed process|out of memory'
journalctl -u jenkins-agent --since '2 hours ago'

También verifica el espacio en disco. El remoting de Jenkins, el checkout, los informes de prueba y los artefactos archivados necesitan espacio. Un volumen del espacio de trabajo lleno puede hacer que un agente parezca poco confiable porque el proceso de remoting no puede escribir archivos temporales o registros.

Si las desconexiones ocurren durante una salida de consola grande, archivado de artefactos o publicación de informes de prueba, mira la estabilidad de la red y la carga del controlador. El canal del agente es una conexión en vivo. Las pausas largas de recolección de basura en el controlador, los proxies sobrecargados, los tiempos de espera de conexión inactiva y la pérdida de paquetes pueden cerrarlo. Para agentes que cruzan balanceadores de carga o proxies corporativos, verifica la configuración de tiempo de espera de inactividad y el comportamiento de keepalive.

Problemas de DNS y Clave de Host

Los cambios de DNS son fáciles de pasar por alto. Jenkins puede conectarse a build-agent-01, mientras que tu prueba manual usa una dirección IP. Prueba el nombre de host desde el controlador:

getent hosts build-agent-01
nc -vz build-agent-01 22

Si el nombre de host se resuelve a la dirección incorrecta, arregla el DNS o la configuración del agente. Evita parches de /etc/hosts a largo plazo a menos que tengas un proceso de propiedad claro, porque se convierten en infraestructura invisible.

Para agentes SSH, la verificación de la clave de host protege a Jenkins de conectarse a una máquina inesperada. Si un agente fue reconstruido, su clave de host puede haber cambiado. No deshabilites la verificación a ciegas. Confirma la reconstrucción, elimina la clave antigua del known_hosts del usuario del controlador y acepta la nueva clave a través de la estrategia de Jenkins configurada.

Una Lista de Verificación de Recuperación para Agentes de Producción

Cuando varios agentes se desconectan a la vez, evita arreglarlos uno por uno antes de encontrar la causa compartida. Pregunta:

¿El controlador Jenkins se reinició o actualizó?
¿Se rotó una credencial compartida?
¿Cambió una imagen base del agente?
¿Se implementó un cambio en el firewall, proxy, VPN o DNS?
¿Están todos los agentes fallidos en la misma subred, cuenta de nube, espacio de nombres de Kubernetes o zona de disponibilidad?

Si solo falla un agente, inspecciona ese host. Si falla un grupo completo junto, inspecciona la dependencia común. Esto ahorra mucho tiempo en flotas de Jenkins más grandes.