Solução de Problemas Comuns de Conectividade de Agentes Jenkins e Soluções

Os agentes Jenkins, também chamados de nós, são onde a maior parte do trabalho de build realmente é executada. Quando um fica offline, o sintoma é óbvio: os jobs ficam na fila, os labels não podem ser satisfeitos e as equipes começam a reexecutar builds que nunca iriam iniciar. O trabalho útil é descobrir qual camada quebrou: acessibilidade de rede, SSH, remoting de entrada, Java, credenciais, disco ou o próprio controlador.

Entender por que um agente pode se tornar inacessível é o primeiro passo para uma solução de problemas eficaz. Esses problemas podem decorrer de configurações de rede incorretas, configuração incorreta do agente, restrições de firewall ou problemas com o próprio controlador Jenkins. Ao verificar sistematicamente essas áreas, você pode identificar rapidamente a causa raiz e implementar uma solução.

Causas Comuns de Desconexão do Agente Jenkins

Vários fatores podem levar um agente a ficar offline. Identificar o sintoma específico é fundamental para restringir as causas potenciais:

Agente inacessível: O controlador Jenkins não consegue estabelecer uma conexão com o agente.
Conexão recusada: A máquina do agente rejeita ativamente a tentativa de conexão do controlador.
Agente relata offline após conexão bem-sucedida: O agente estava conectado, mas perdeu a conexão.
Erros JSch (para agentes baseados em SSH): Erros específicos relacionados à biblioteca Java Secure Channel usada para conexões SSH.

Problemas de Rede e Firewall

A conectividade de rede é o culpado mais frequente por problemas de conexão do agente. Garantir que o controlador Jenkins possa alcançar a máquina do agente e vice-versa é fundamental.

Verificando a Acessibilidade da Rede

Antes de mergulhar nas configurações específicas do Jenkins, confirme a conectividade básica de rede:

Ping no agente: Da máquina do controlador Jenkins, tente pingar o endereço IP ou nome do host da máquina do agente.
```
ping <agent-hostname-or-ip>
```
Telnet para a porta do agente: Teste se a porta que o Jenkins usa para se conectar ao agente está aberta e ouvindo. Para agentes JNLP, esta é tipicamente a porta 50000. Para agentes SSH, é a porta SSH (padrão 22).
```
telnet <agent-hostname-or-ip> <agent-port>
```
Se a conexão expirar ou for recusada, provavelmente há um problema de rede ou firewall bloqueando a porta.

Configuração de Firewall

Firewalls no controlador Jenkins, na máquina do agente ou em dispositivos de rede intermediários podem bloquear as portas necessárias.

Firewall do Controlador Jenkins: Certifique-se de que o controlador possa iniciar conexões para a porta do agente.
Firewall da Máquina do Agente: Certifique-se de que o firewall da máquina do agente (por exemplo, ufw, firewalld, Firewall do Windows) permita conexões de entrada na porta do agente a partir do endereço IP do controlador Jenkins.
Firewalls de Rede: Se sua rede tiver firewalls internos, verifique se o tráfego é permitido entre o controlador e o agente.

Exemplo: Permitindo a Porta 50000 em um Agente (Linux com `ufw`)

# Permitir conexões de um IP específico (controlador Jenkins)
sudo ufw allow from <jenkins-controller-ip> to any port 50000

# Ou permitir de qualquer IP (menos seguro)
sudo ufw allow 50000

# Recarregar regras do firewall
sudo ufw reload

Exemplo: Permitindo a Porta 22 em um Agente (Linux com `firewalld`)

# Permitir serviço SSH permanentemente de um IP de origem específico
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<jenkins-controller-ip>" port protocol="tcp" port="22" accept'

# Recarregar regras do firewall
sudo firewall-cmd --reload

Dica: Sempre priorize permitir conexões de endereços IP específicos para melhor segurança.

Problemas de Configuração do Agente Jenkins

Configurações incorretas dentro do Jenkins ou no próprio agente são fontes comuns de problemas de conectividade.

Configuração do Agente JNLP

Agentes Java Network Launch Protocol (JNLP) se comunicam com o controlador Jenkins usando uma porta dedicada. A configuração principal envolve o método de inicialização do agente e as portas disponíveis do controlador.

Agente Offline na Interface do Jenkins

Se um agente aparecer offline na interface do Jenkins, significa que o controlador não conseguiu estabelecer ou manter uma conexão.

Verifique o Método de Inicialização do Agente: Certifique-se de que o agente está configurado para iniciar corretamente. Métodos comuns incluem:
- Iniciar agente conectando-o ao mestre: Isso requer iniciação manual do lado do agente.
- Iniciar agente via SSH: Configurado através de credenciais SSH e configurações de host.
- Iniciar agente usando propriedades de nó integradas: Para cenários específicos.
Verifique a Disponibilidade da Porta JNLP: O controlador Jenkins precisa ouvir na porta JNLP configurada (padrão 50000). Navegue até Gerenciar Jenkins -> Sistema -> Avançado -> Arquivo -> Porta TCP para agentes JNLP e certifique-se de que está definida e acessível.

"Conexão recusada" ao iniciar o Agente JNLP

Isso geralmente significa que a porta JNLP (padrão 50000) no controlador Jenkins não está aberta ou acessível a partir da máquina do agente. Verifique as regras de firewall no controlador e certifique-se de que a porta está configurada corretamente.

Dica: Reiniciar o controlador Jenkins às vezes pode resolver problemas transitórios de porta JNLP.

Configuração do Agente SSH

Ao usar SSH para se conectar a agentes, vários fatores podem causar problemas:

Credenciais SSH Incorretas: Verifique o nome de usuário, senha ou chave privada configurados no Jenkins para a conexão SSH. Certifique-se de que a chave privada está formatada corretamente (por exemplo, formato PEM) e tem as permissões corretas.
Servidor SSH Não Executando no Agente: Certifique-se de que o daemon SSH (sshd) está em execução na máquina do agente.
```
# Na máquina do agente
sudo systemctl status sshd
# ou
sudo service ssh status
```
Se não estiver em execução, inicie-o:
```
sudo systemctl start sshd
sudo systemctl enable sshd
```
Incompatibilidade de Porta SSH: Certifique-se de que a porta configurada no Jenkins para SSH corresponde à porta em que o servidor SSH está ouvindo (padrão 22).
Resolução de Nome do Agente/IP: O controlador Jenkins deve ser capaz de resolver o nome do host ou endereço IP do agente.
Permissões da Chave SSH: Na máquina do agente, o arquivo ~/.ssh/authorized_keys para o usuário com o qual o Jenkins se conecta deve ter as permissões corretas (geralmente 600).

Exemplo: Testando a Conexão SSH Manualmente

Da máquina do controlador Jenkins, tente fazer SSH no agente usando as mesmas credenciais e porta configuradas no Jenkins:

ssh -p <ssh-port> <jenkins-user>@<agent-hostname-or-ip>

Se este comando SSH manual falhar, o problema está fora da configuração SSH do Jenkins, provavelmente em configurações de rede, firewall ou servidor SSH no agente.

Permissões do Diretório de Trabalho do Agente

O Jenkins requer permissões específicas para operar no sistema de arquivos do agente. O usuário que o Jenkins usa para se conectar ao agente (ou o usuário que executa o processo do agente) precisa de permissões de gravação no diretório de trabalho configurado do agente.

Verifique proprietário e permissões: No agente, verifique a propriedade e as permissões do diretório home do Jenkins e seus subdiretórios.
```
ls -ld /path/to/jenkins/agent/home
ls -l /path/to/jenkins/agent/home
```
Conceda permissões (se necessário): Certifique-se de que o usuário com o qual o Jenkins se conecta tenha acesso de leitura e gravação. Use chown e chmod com cuidado.

Problemas do Controlador Jenkins

Às vezes, o problema pode não estar no agente, mas no próprio controlador Jenkins.

Sobrecarga do Controlador

Se o controlador Jenkins estiver sob carga pesada (muitos jobs em execução, alto uso de CPU/memória), ele pode ter dificuldade para gerenciar conexões de agentes. Monitore a utilização de recursos do controlador.

Conflitos de Porta JNLP

Se a porta JNLP (padrão 50000) já estiver em uso por outro processo no controlador Jenkins, os agentes falharão ao conectar.

Verifique o uso da porta: Na máquina do controlador, use netstat ou ss para ver qual processo está usando a porta.
```
sudo netstat -tulnp | grep 50000
# ou
sudo ss -tulnp | grep 50000
```
Se outro processo estiver usando-a, você precisará reconfigurar o Jenkins ou o outro aplicativo para usar portas diferentes.

Solução de Problemas Avançada e Logs

Quando as verificações padrão não revelam o problema, uma investigação mais aprofundada é necessária.

Logs do Controlador Jenkins

Revise os logs do controlador Jenkins em busca de erros relacionados a conexões de agentes. Esses logs podem fornecer mensagens de erro específicas.

Localização: Geralmente encontrados em $JENKINS_HOME/jenkins.log ou acessíveis via Gerenciar Jenkins -> Log do Sistema.
Procure por: Mensagens mencionando o nome do host do agente, endereço IP, tentativas de conexão, exceções JSch ou erros de Conexão recusada.

Logs do Agente

Se o agente estiver em execução, mas relatando offline, verifique seus logs em busca de erros.

Agentes JNLP: O próprio processo do agente pode gerar logs em seu console ou em um arquivo de log designado.
Agentes SSH: Os logs podem estar em $JENKINS_HOME/agent.log na máquina do agente, ou relacionados ao sshd se a conexão falhar no nível SSH.

Ativar Log de Depuração

Para problemas muito persistentes, ativar temporariamente o log de depuração para componentes relevantes do Jenkins pode fornecer informações mais granulares.

Comunicação JNLP/Agente: Você pode precisar ajustar propriedades do sistema Java ou usar a configuração de log do Jenkins (Gerenciar Jenkins -> Log do Sistema -> Gravadores de Log) para aumentar a verbosidade para hudson.slaves ou pacotes relacionados.

Hábitos Práticos que Previnem Interrupções Repetidas

Solucionar problemas de conectividade de agentes Jenkins requer uma abordagem sistemática, começando com verificações básicas de rede e progredindo para configurações específicas do Jenkins.

Verifique a Rede: Sempre comece com ping e telnet/nc para garantir a acessibilidade básica da rede e o acesso à porta.
Verifique Firewalls: Certifique-se de que os firewalls no controlador e no agente, bem como quaisquer firewalls de rede, permitam tráfego nas portas necessárias.
Valide Credenciais: Verifique novamente chaves SSH, nomes de usuário e senhas.
Confirme o Serviço do Agente: Para agentes SSH, certifique-se de que o sshd esteja em execução e acessível.
Monitore os Logs do Jenkins: Os logs do controlador são sua principal fonte para entender falhas de conexão.
Use IPs Específicos: Sempre que possível, configure firewalls e Jenkins para usar endereços IP específicos em vez de intervalos amplos ou 0.0.0.0.

Seguindo estas etapas, você pode diagnosticar e resolver efetivamente a maioria dos problemas comuns de conectividade de agentes Jenkins, mantendo seus pipelines de CI/CD funcionando sem problemas.

Lendo a Mensagem Offline Sem Adivinhar

A palavra "offline" é muito ampla para solucionar problemas por si só. Antes de alterar as configurações do Jenkins, abra a página do agente e leia o motivo exato que o Jenkins fornece. Há uma grande diferença entre "conexão recusada", "permissão negada", "verificação de chave do host falhou", "agente JNLP rejeitado" e "canal foi fechado". Todos terminam com um nó offline, mas apontam para camadas diferentes.

Geralmente, anoto o sintoma em linguagem simples: "controlador não consegue alcançar a porta TCP 22", "login SSH funciona, mas o Java não consegue iniciar", "agente de entrada inicia, mas não consegue chamar de volta o controlador" ou "agente conecta e depois cai durante os builds". Essa frase mantém a investigação focada.

Se o agente nunca se conectou, suspeite de configuração, DNS, firewall, credenciais ou comando de inicialização. Se ele se conectou por meses e começou a falhar hoje, verifique as mudanças recentes: chaves SSH rotacionadas, uma atualização do Jenkins, uma atualização de plugin, uma nova regra de firewall, um certificado expirado, uma reconstrução de imagem do agente ou uma mudança de rede em nuvem. A linha do tempo é muitas vezes mais útil do que o texto do erro.

Agentes SSH: Separe Problemas de Login de Problemas de Inicialização

Para agentes baseados em SSH, teste o mesmo caminho que o Jenkins usa. Do host do controlador, conecte-se como o usuário configurado no Jenkins:

ssh -vvv jenkins-agent-user@agent-hostname

A saída detalhada informa se a falha ocorre antes da autenticação, durante a autenticação ou após o login. Se o SSH nunca alcançar o servidor, o Jenkins não pode corrigir isso. Verifique roteamento, grupos de segurança, ACLs de rede, firewalls de host e o daemon SSH. Se o SSH alcançar o servidor, mas rejeitar a chave, verifique a credencial no Jenkins, o authorized_keys do usuário, as permissões de arquivo e se a conta está bloqueada.

Se o login SSH funcionar manualmente, mas o Jenkins ainda falhar, observe o diretório raiz remoto e a inicialização do Java. O Jenkins precisa de um diretório gravável para os arquivos de remoting, e o usuário do agente precisa de permissão para criar arquivos lá. Um erro comum é apontar a raiz remota para um caminho de propriedade do root ou limpo por outro processo.

Execute estas verificações no agente:

whoami
pwd
java -version
test -w /path/to/jenkins-agent && echo writable
df -h /path/to/jenkins-agent

A versão do Java é importante porque os controladores Jenkins modernos exigem versões compatíveis do Java nos agentes. O requisito exato depende da sua versão do Jenkins, então verifique a documentação do Jenkins para sua versão em vez de assumir que uma imagem de agente antiga ainda é válida.

Agentes de Entrada: O Caminho de Retorno é a Armadilha Comum

Agentes de entrada são frequentemente usados quando o controlador não pode iniciar SSH para o agente, como agentes atrás de NAT ou em redes restritas. O processo do agente inicia fora do Jenkins e se conecta de volta ao controlador. Isso significa que o caminho de rede é invertido: o agente deve resolver e alcançar a URL do Jenkins.

No host do agente, teste a URL do Jenkins exatamente como configurada:

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

Se o Jenkins estiver atrás de um proxy reverso, confirme se a URL pública em Gerenciar Jenkins > Sistema está correta. Uma URL do Jenkins errada pode fazer com que comandos de agente gerados apontem para um nome de host interno que o agente não pode resolver. Se o modo WebSocket estiver ativado para agentes de entrada, certifique-se de que o proxy suporte cabeçalhos de atualização WebSocket. Se você usar a porta TCP do agente de entrada, confirme se a porta fixa está configurada e acessível a partir da rede do agente.

Problemas de TLS podem parecer problemas do Jenkins. Se o agente for executado em uma imagem de contêiner mínima, pode não ter seu certificado de CA interno. curl geralmente expõe isso rapidamente. Instale o certificado CA na imagem do agente em vez de desabilitar a verificação de certificado.

Agentes que Desconectam Durante Builds

Um agente que conecta com sucesso e depois cai durante um build geralmente não é um problema básico de conectividade. Observe a pressão de recursos e o ciclo de vida do processo.

Verifique se o sistema operacional matou o processo do agente:

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

Verifique também o espaço em disco. O remoting do Jenkins, checkout, relatórios de teste e artefatos arquivados precisam de espaço. Um volume de workspace cheio pode fazer um agente parecer não confiável porque o processo de remoting não pode gravar arquivos temporários ou logs.

Se as desconexões acontecerem durante grandes saídas de console, arquivamento de artefatos ou publicação de relatórios de teste, observe a estabilidade da rede e a carga do controlador. O canal do agente é uma conexão ativa. Longas pausas de coleta de lixo no controlador, proxies sobrecarregados, timeouts de conexão ociosa e perda de pacotes podem fechá-lo. Para agentes que cruzam balanceadores de carga ou proxies corporativos, verifique as configurações de timeout ocioso e o comportamento de keepalive.

Problemas de DNS e Chave do Host

Mudanças de DNS são fáceis de perder. O Jenkins pode se conectar a build-agent-01, enquanto seu teste manual usa um endereço IP. Teste o nome do host a partir do controlador:

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

Se o nome do host resolver para o endereço errado, corrija o DNS ou a configuração do agente. Evite patches de /etc/hosts de longo prazo, a menos que você tenha um processo de propriedade claro, porque eles se tornam infraestrutura invisível.

Para agentes SSH, a verificação da chave do host protege o Jenkins de se conectar a uma máquina inesperada. Se um agente foi reconstruído, sua chave do host pode ter mudado. Não desabilite a verificação cegamente. Confirme a reconstrução, remova a chave antiga do known_hosts do usuário do controlador e aceite a nova chave através da estratégia configurada do Jenkins.

Uma Lista de Verificação de Recuperação para Agentes de Produção

Quando vários agentes ficam offline ao mesmo tempo, evite corrigi-los um por um antes de encontrar a causa compartilhada. Pergunte:

O controlador Jenkins foi reiniciado ou atualizado?
Uma credencial compartilhada foi rotacionada?
Uma imagem de agente base mudou?
Uma mudança de firewall, proxy, VPN ou DNS foi implementada?
Todos os agentes com falha estão na mesma sub-rede, conta de nuvem, namespace Kubernetes ou zona de disponibilidade?

Se apenas um agente falhar, inspecione esse host. Se um grupo inteiro falhar junto, inspecione a dependência comum. Isso economiza muito tempo em frotas maiores do Jenkins.