Deploy falhando? Como inspecionar logs do Kubelet no nó

O que é o Kubelet e por que ele falha durante um deploy

Quando um deploy falha no Kubernetes, a frustração costuma ser imediata. Mensagens genéricas como CrashLoopBackOff ou ContainerCreating aparecem no terminal, mas muitas vezes não revelam a raiz do problema. É exatamente nesse cenário que entra o Kubelet, o agente invisível que roda em cada máquina do seu cluster (os nós) e transforma especificações teóricas em containers reais rodando na prática.

Na rotina de engenharia, o Kubelet funciona como o gerente local de uma grande obra: ele recebe as plantas enviadas pelo servidor central e coordena os operários — que, no nosso caso, são ferramentas como o Containerd ou o Docker. Se faltar material, se a fundação falhar ou se houver um erro de permissão, é o Kubelet quem anota a ocorrência no diário de bordo do sistema. Entender como ler esse diário de bordo direto na máquina é a chave para destravar qualquer infraestrutura travada.

Muitas vezes, as falhas de inicialização estão intimamente ligadas a problemas de recursos esgotados no host, como discutimos ao analisar por que pods sofrem OOM Killed no Kubernetes e como ajustar limites. Quando o sistema operacional precisa cortar processos à força para se salvar, o Kubelet registra o desespero do kernel em seus registros internos. Vamos ver como acessar essas informações preciosas usando comandos simples e diretos.

Como acessar o nó e isolar o serviço do Kubelet

Para inspecionar o Kubelet, o primeiro passo é abrir uma conexão segura via SSH diretamente na máquina virtual ou física que está apresentando o problema. Diferente dos comandos kubectl tradicionais que conversam com a API central, aqui estamos pisando no chão da fábrica, olhando diretamente para o sistema operacional que sustenta os containers.

A grande maioria das distribuições modernas do Linux gerencia serviços através do Systemd, o sistema de inicialização padrão. Isso significa que os registros do Kubelet são capturados e armazenados centralmente por uma ferramenta chamada Journald. Para examinar o comportamento recente do nosso agente, utilizamos o utilitário de consulta padrão do sistema.

Execute o comando abaixo no terminal do nó para visualizar as entradas mais recentes geradas exclusivamente pelo serviço do Kubelet:

sudo journalctl -u kubelet -e --no-pager

Esse comando filtra o caos gerado pelo sistema operacional inteiro e foca apenas nas últimas linhas do Kubelet, permitindo que você identifique rapidamente se houve rejeição de certificados, falhas de comunicação com a API ou erros de timeout ao tentar baixar uma imagem.

Identificando erros de imagem e falhas de disco no nó

Um dos motivos mais comuns para um pod recusar-se a iniciar é a impossibilidade de baixar a imagem do container do registro remoto, seja por credenciais inválidas, falhas temporárias de rede ou falta de espaço em disco no nó. Quando isso acontece, o Kubelet tenta repetidamente baixar o pacote, gerando um histórico rico de mensagens de erro.

Ao inspecionar os logs, procure por termos como ImagePullBackOff, ErrImagePull ou falhas relacionadas ao sistema de arquivos subjacente. Em alguns casos, problemas severos de E/S na máquina podem corromper o armazenamento local, situação parecida com a que investigamos quando um SSD NVMe lento no Linux exige diagnóstico via terminal antes que o Kubernetes comece a rejeitar novas cargas de trabalho.

Para monitorar os eventos em tempo real enquanto você tenta recriar o pod problemático em outra janela, utilize o parâmetro de acompanhamento contínuo do journalctl:

sudo journalctl -u kubelet -f -n 100

Essa visualização contínua permite que você dispare o comando de deploy e assista, segundo a segundo, a forma como o Kubelet interage com o tempo de execução do container para puxar camadas, montar volumes e iniciar os processos internos.

Inspecionando o tempo de execução e resolvendo o travamento

Além dos registros textuais do Kubelet, muitas vezes precisamos olhar diretamente para o motor que executa os containers — geralmente o Containerd. O Kubelet delega a criação real dos processos a esse motor, e um erro de comunicação entre eles pode congelar completamente o ciclo de vida da aplicação.

Quando o nó apresenta travamentos generalizados e o Kubelet parece congelado, vale a pena verificar se o kernel não finalizou processos críticos devido ao consumo excessivo de memória, conforme detalhamos no guia sobre como auditar o OOM Killer com dmesg. Muitas vezes, o Kubelet sofre quedas abruptas porque a própria máquina ficou sem fôlego.

Para reiniciar o agente com segurança após aplicar correções de configuração ou certificados expirados, utilize o gerenciador de serviços do sistema:

sudo systemctl restart kubelet

Essa ação força o Kubelet a reler seus arquivos de configuração locais, reestabelecer a conexão segura com o plano de controle central e retomar a sincronização dos pods atribuídos àquele nó específico.

Considerações finais sobre o diagnóstico profundo em Kubernetes

Dominar a inspeção de logs do Kubelet diretamente no nó transforma um engenheiro de software ou DevOps de um mero espectador em um solucionador completo de problemas. Em vez de depender apenas de comandos de alto nível que muitas vezes omitem detalhes cruciais de infraestrutura, descer ao nível do sistema operacional revela exatamente onde o ecossistema de containers encontrou barreiras.

Manter esse hábito de troubleshooting estruturado garante que interrupções em produção deixem de ser um mistério assustador e se tornem incidentes com causa raiz identificada e resolvida em poucos minutos. A observabilidade começa sempre onde a abstração termina.