Solução de Problemas de Falhas de Conexão SSH em Playbooks Ansible

O Ansible depende exclusivamente do protocolo Secure Shell (SSH) para se comunicar com os nós gerenciados. Quando um playbook Ansible falha com um erro de conectividade, quase sempre aponta para um problema subjacente na configuração padrão do SSH entre a máquina de controle e o host de destino. Entender como diagnosticar sistematicamente essas falhas é crucial para manter uma automação confiável.

Este guia fornece uma metodologia passo a passo para diagnosticar e resolver as falhas de conexão SSH mais comuns encontradas ao executar playbooks Ansible, garantindo que o gerenciamento de sua configuração funcione sem problemas.

Fase 1: Ativação da Verbose e Verificações Iniciais

A ferramenta mais importante na solução de problemas do Ansible é aumentar a verbosidade da saída. Os erros de SSH são frequentemente mascarados, mas a verbosidade máxima revela os parâmetros exatos que o Ansible está usando e a mensagem de erro específica retornada pelo cliente OpenSSH subjacente.

Usar Flags de Verbosidade

Execute seu comando de teste ou playbook com três ou quatro flags de verbosidade (-v, -vv, -vvv, -vvvv). A maioria dos problemas de conexão é resolvida revisando a saída de -vvv.

# Testar conectividade a um host chamado 'webserver' definido no seu inventário
ansible webserver -m ansible.builtin.ping -vvv

# Executar um playbook com depuração máxima
ansible-playbook site.yml -i inventory.ini -vvvv

Verificar Inventário e Status do Host

Certifique-se de que o host que você está visando esteja corretamente definido e acessível.

O Nome do Host Está Correto? Verifique a grafia no seu arquivo de inventário (/etc/ansible/hosts ou inventário personalizado).
O Destino Está Ativo? Certifique-se de que o nó gerenciado esteja ligado e acessível na rede.
As Variáveis de Inventário Estão Corretas? Confirme se variáveis essenciais como ansible_host (endereço IP ou nome do host) e ansible_user (nome de usuário remoto) estão definidas corretamente para o grupo ou host de destino.

# Exemplo de Trecho de Inventário
[webservers]
web1 ansible_host=192.168.1.100 ansible_user=deploy_user ansible_port=22

Fase 2: Verificação de Conectividade Manual Básica

Se o Ansible não conseguir conectar, o primeiro passo deve ser sempre confirmar que o SSH padrão funciona manualmente, usando exatamente o mesmo usuário, chave e porta que o Ansible está configurado para usar.

Teste Manual de SSH

Se você estiver usando um usuário específico (ansible_user) e uma chave privada específica (ansible_ssh_private_key_file), replique essa conexão manualmente.

# Teste SSH padrão (se estiver usando a porta e chave padrão)
ssh <ansible_user>@<ansible_host>

# Testar usando uma chave privada e porta não padrão
ssh -i /path/to/private/key -p 2222 [email protected]

Se o teste manual de SSH falhar, o problema é ambiental, não do Ansible. Corrija o problema central do SSH antes de prosseguir com o Ansible.

Fase 3: Diagnóstico de Falhas de Autenticação

Falhas de autenticação são a causa mais comum de problemas de conexão do Ansible. Elas geralmente se manifestam como erros de Authentication failed (Autenticação falhou) ou Permission denied (Permissão negada).

3.1 Permissões e Localização da Chave

Se o Ansible estiver usando chaves SSH, certifique-se de que o arquivo de chave privada tenha as permissões restritas e corretas na máquina de controle. O SSH frequentemente rejeitará chaves que são muito permissivas.

# Definir permissões corretas no arquivo de chave privada
chmod 600 /path/to/private/key

Além disso, se você usar um SSH Agent, certifique-se de que sua chave esteja adicionada:

# Iniciar o agent se necessário
eval "$(ssh-agent -s)"
# Adicionar sua chave ao agent
ssh-add /path/to/private/key

3.2 Falhas de Prompt de Senha (Timeout/Senha Ausente)

Se sua configuração exigir uma senha (não recomendado para produção, mas comum em laboratórios), ela precisa ser fornecida ao Ansible. Se a conexão travar ou expirar, o Ansible provavelmente está esperando por uma senha que nunca foi fornecida.

Use o flag --ask-pass ou -k para solicitar a senha de conexão SSH:

ansible webserver -m ansible.builtin.ping -k

3.3 Chaves Autorizadas Remotas

Verifique se a chave pública correspondente à sua chave privada está instalada corretamente no arquivo ~/.ssh/authorized_keys no nó gerenciado e se as permissões de arquivo e diretório no lado remoto estão corretas (700 para .ssh e 600 para authorized_keys).

Fase 4: Resolução de Erros de Chave de Host

O Ansible respeita o arquivo known_hosts, que armazena a impressão digital (fingerprint) dos servidores remotos. Se a chave do host de um nó gerenciado mudar (por exemplo, devido a uma reconstrução ou reatribuição de IP), as tentativas de conexão SSH falharão com um aviso que se assemelha a um ataque Man-in-the-Middle.

O Erro `Host key verification failed` (Falha na verificação da chave do host)

Quando este erro ocorrer, você deve atualizar ou remover a entrada da chave conflitante.

Identifique o número da linha em ~/.ssh/known_hosts mencionado na saída de erro.
Remova a entrada usando ssh-keygen.

# Substitua <hostname_or_ip> pelo host real que está falhando
ssh-keygen -R <hostname_or_ip>

⚠️ Aviso de Segurança: Desativando a Verificação de Host

Para testes temporários ou em ambientes de laboratório altamente controlados onde a instabilidade do host é esperada, você pode configurar o Ansible para ignorar a verificação da chave do host. Isso é fortemente desencorajado para ambientes de produção, pois o expõe a ataques MITM.

No seu ansible.cfg (ou variável de ambiente temporária):
ini [defaults] host_key_checking = False

Fase 5: Problemas de Rede, Firewall e Ambiente Remoto

Às vezes, o SSH conecta, mas a conexão paralisa ou falha devido à configuração de rede ou restrições na máquina de destino.

5.1 Bloqueio de Firewall

Se a conexão expirar (timeout) sem um prompt, é provável que um firewall esteja bloqueando a tentativa de conexão. Verifique o firewall em três pontos:

Local (Máquina de Controle): Certifique-se de que o tráfego de saída na porta 22 (ou porta personalizada) esteja permitido.
Caminho de Rede: Certifique-se de que nenhuma ACL de rede intermediária ou firewall corporativo esteja bloqueando o tráfego.
Remoto (Nó Gerenciado): Verifique se o firewall do host remoto (firewalld, ufw, etc.) tem o SSH (geralmente porta 22) aberto e configurado para a interface de rede correta.

5.2 Erros do Interpretador Python

O Ansible requer um interpretador Python no nó gerenciado para executar módulos. Embora não seja estritamente uma falha de SSH, a fase inicial de conexão do Ansible envolve a coleta de fatos (fact gathering), que é uma execução de script Python. Se a máquina de destino for uma instalação mínima sem Python 3, a conexão pode falhar durante a fase de configuração (setup).

Se o seu destino usa Python 3, mas o caminho do interpretador não é padrão (por exemplo, python3.8 em vez de python3), especifique o caminho correto no seu inventário:

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

5.3 Contexto SELinux ou AppArmor

Em casos raros, módulos de segurança excessivamente rigorosos como SELinux (em RHEL/CentOS/Fedora) ou AppArmor (em Ubuntu/Debian) podem impedir que o perfil de shell ou as permissões de diretório do usuário remoto sejam acessados corretamente durante a sessão SSH. Verifique os logs de auditoria do host remoto (/var/log/audit/audit.log ou equivalente) em busca de negações AVC relacionadas ao SSH ou ao acesso ao diretório inicial do usuário.

Resumo de Erros Comuns de Conexão e Soluções

Mensagem de Erro	Causa Provável	Solução Acionável
`Permission denied (publickey).` (Permissão negada (chave pública).)	Chave não reconhecida ou permissões de chave incorretas.	`chmod 600` na chave privada; verifique a chave pública no host remoto.
`Host key verification failed.` (Falha na verificação da chave do host.)	Chave do host alterada ou arquivo known_hosts corrompido.	Use `ssh-keygen -R hostname` para remover a entrada antiga.
`Connection timed out.` (Conexão expirou.)	Bloqueio de firewall ou host está inativo/inacessível.	Verifique a conectividade manual (`ping`, `ssh`); verifique as regras de firewall no host de destino.
Conexão trava/paralisa.	Aguardando entrada de senha que não foi fornecida.	Execute com `-k` ou configure a autenticação baseada em chave.

Conclusão

A solução de problemas de conexão SSH no Ansible é principalmente um processo sistemático de depuração da configuração subjacente do cliente SSH. Começando com verificações básicas de conectividade manual, aumentando a verbosidade (-vvv) e verificando metodicamente a autenticação, as chaves do host e os caminhos de rede, você pode isolar e resolver rapidamente a maioria das falhas de conectividade, permitindo que seus fluxos de trabalho de automação prossigam sem interrupção.