Dominando kubectl logs e describe para Depuração Eficiente de Pods
Depurar aplicações em um ambiente distribuído como o Kubernetes pode ser desafiador. Quando um pod falha ao iniciar, entra em um loop de reinicialização ou exibe comportamento inesperado, as duas ferramentas mais críticas no conjunto de ferramentas de um operador Kubernetes são kubectl describe e kubectl logs.
Esses comandos fornecem visões diferentes, porém complementares, sobre o estado e o histórico de um Pod Kubernetes. kubectl describe fornece os metadados, status, variáveis de ambiente do Pod e, crucialmente, um histórico de eventos do sistema. kubectl logs fornece os fluxos de saída padrão (stdout) e erro padrão (stderr) gerados pela própria aplicação conteinerizada.
Dominar as flags e técnicas associadas a esses comandos é essencial para diagnosticar e resolver problemas rapidamente, melhorando significativamente a eficiência geral da solução de problemas do seu cluster.
O Fluxo de Trabalho de Depuração de Pods em Três Etapas
Antes de mergulhar nos comandos, é útil entender o fluxo de trabalho típico de depuração:
- Verificar Status: Use
kubectl get podspara identificar o estado de falha (Pending,CrashLoopBackOff,ImagePullBackOff, etc.). - Obter Contexto e Eventos: Use
kubectl describe podpara entender por que a transição de estado ocorreu (por exemplo, o agendador falhou, a sonda de vivacidade falhou, o volume não montou). - Inspecionar Saída da Aplicação: Use
kubectl logspara examinar o comportamento da aplicação em tempo de execução (por exemplo, erros de configuração, falhas de conexão com o banco de dados, rastreamentos de pilha).
1. kubectl describe: A Ferramenta de Triagem do Sistema
kubectl describe é o primeiro comando que você deve executar quando um Pod está se comportando mal. Ele não mostra a saída da aplicação, mas fornece os metadados críticos e o histórico que o próprio Kubernetes registrou sobre o Pod.
Uso Básico
O uso fundamental requer apenas o nome do Pod:
kubectl describe pod my-failing-app-xyz789
Seções Chave na Saída
Ao revisar a saída de describe, concentre-se nestas seções críticas:
A. Status e Estado
Observe o campo Status no topo e, em seguida, revise os estados individuais dos contêineres dentro do Pod. Isso informa se o contêiner está Running (em execução), Waiting (esperando) ou Terminated (terminado), e fornece o motivo para esse estado.
| Campo | Status/Razão Comum | Significado |
|---|---|---|
Status |
Pending |
O Pod está aguardando para ser agendado ou tem recursos ausentes. |
Reason |
ContainerCreating |
O runtime do contêiner está puxando a imagem ou executando a configuração. |
State |
Waiting / Reason: CrashLoopBackOff |
O contêiner iniciou e saiu repetidamente. |
State |
Terminated / Exit Code |
O contêiner concluiu a execução. Códigos de saída diferentes de zero geralmente indicam erros. |
B. Configuração do Contêiner
Esta seção verifica se suas variáveis de ambiente, requisições/limites de recursos, montagens de volume e sondas de vivacidade/prontidão estão definidas corretamente, correspondendo ao manifesto que você aplicou.
C. A Seção Events (Crucial)
A seção Events, localizada na parte inferior da saída, é sem dúvida a parte mais valiosa. Ela fornece um registro cronológico do que o painel de controle do Kubernetes fez para e pelo Pod, incluindo avisos e erros.
Erros Comuns revelados pelos Events:
- Problemas de Agendamento:
Warning FailedScheduling: Indica que o agendador não conseguiu encontrar um nó adequado (por exemplo, devido a restrições de recursos, taints de nó ou regras de afinidade). - Falhas de Pull de Imagem:
Warning Failed: ImagePullBackOff: Indica que o nome da imagem está incorreto, a tag não existe ou o Kubernetes não possui credenciais para puxar de um registro privado. - Erros de Volume:
Warning FailedAttachVolume: Indica problemas na conexão de armazenamento externo.
Dica: Se a seção
Eventsestiver limpa, o problema geralmente está relacionado à aplicação (falha em tempo de execução, inicialização falha, erro de configuração), direcionando você a usarkubectl logsem seguida.
2. kubectl logs: Inspecionando a Saída da Aplicação
Se describe mostrar que o Pod foi agendado com sucesso e os contêineres tentaram executar, o próximo passo é verificar os fluxos de saída padrão usando kubectl logs.
Recuperação Básica de Logs e Transmissão em Tempo Real
Para visualizar os logs atuais do contêiner principal em um Pod:
# Recuperar todos os logs até o momento atual
kubectl logs my-failing-app-xyz789
# Transmitir logs em tempo real (útil para monitorar a inicialização)
kubectl logs -f my-failing-app-xyz789
Lidando com Pods Multi-Contêineres
Para pods que utilizam o padrão Sidecar ou outros designs multi-contêiner, você deve especificar os logs de qual contêiner deseja visualizar usando a flag -c ou --container.
# Visualizar logs do contêiner 'sidecar-proxy' dentro do Pod
kubectl logs my-multi-container-pod -c sidecar-proxy
# Transmitir logs para o contêiner principal da aplicação
kubectl logs -f my-multi-container-pod -c main-app
Depurando Contêineres em Reinicialização (--previous)
Um dos cenários de depuração mais comuns é o estado CrashLoopBackOff. Quando um contêiner reinicia, kubectl logs mostra apenas a saída da tentativa atual (falha), que muitas vezes contém apenas a mensagem de inicialização antes da falha.
Para visualizar os logs da instância anterior, terminada – que contém o erro real que causou a saída – use a flag --previous (-p):
# Visualizar logs da instância anterior do contêiner que falhou
kubectl logs my-crashloop-pod --previous
# Combinar com a especificação do contêiner, se necessário
kubectl logs my-crashloop-pod -c worker --previous
Limitando a Saída
Para logs de alto volume, recuperar todo o histórico pode ser lento ou avassalador. Use --tail para limitar a saída às últimas N linhas.
# Mostrar apenas as últimas 50 linhas dos logs do contêiner
kubectl logs my-high-traffic-app --tail=50
3. Combinando Técnicas para Diagnóstico Avançado
A depuração eficaz geralmente envolve alternar rapidamente entre os comandos describe e logs específicos.
Estudo de Caso: Diagnosticando Falha da Sonda de Vivacidade
Imagine que um Pod esteja preso em Running (em execução), mas ocasionalmente reinicia, causando interrupção.
Passo 1: Verifique describe para a visão do sistema.
kubectl describe pod web-server-dpl-abc
A saída mostra na seção Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning Unhealthy 2s kubelet, node-a01 Liveness probe failed: HTTP GET http://10.42.0.5:8080/health failed: 503 Service Unavailable
Conclusão do Passo 1: O contêiner está em execução, mas a sonda de vivacidade está falhando com um erro 503, fazendo com que o Kubernetes reinicie o contêiner.
Passo 2: Verifique logs para o contexto da aplicação.
Agora, investigue por que a aplicação está retornando um status 503, que é uma falha em nível de aplicação.
kubectl logs web-server-dpl-abc --tail=200
A saída do log revela:
2023-10-26 14:01:15 ERROR Database connection failure: Timeout connecting to DB instance 192.168.1.10
Conclusão Final: O Pod está reiniciando devido a uma falha na sonda de vivacidade, e a sonda está falhando porque a aplicação não consegue se conectar ao banco de dados. O problema é de rede externa ou configuração do banco de dados, não o contêiner em si.
Melhores Práticas e Avisos
| Prática | Comando | Justificativa |
|---|---|---|
| Sempre verificar logs anteriores | kubectl logs --previous |
Necessário para diagnosticar CrashLoopBackOff. O erro crítico está quase sempre na execução anterior. |
| Especificar contêineres | kubectl logs -c <name> |
Evita ambiguidade em Pods multi-contêiner e impede a busca de logs de sidecars não intencionais. |
| Usar labels para operações em massa | kubectl logs -l app=frontend -f |
Permite o streaming de logs de vários Pods que correspondem a um seletor simultaneamente (útil para atualizações contínuas). |
| Aviso: Rotação de Log | N/A | Os nós Kubernetes realizam rotação de logs. Logs mais antigos do que a política de retenção configurada do nó (muitas vezes alguns dias ou baseada no tamanho) serão eliminados e ficarão indisponíveis via kubectl logs. Use uma solução externa de log centralizado (por exemplo, Fluentd, Loki, Elastic Stack) para retenção de longo prazo. |
Conclusão
kubectl describe e kubectl logs são os comandos centrais indispensáveis para a depuração no Kubernetes. Ao tratar describe como o relatório de status do sistema (focando em configuração, eventos e erros de agendamento) e logs como o fluxo de execução da aplicação (focando em erros de código e comportamento em tempo de execução), você pode sistematicamente reduzir a causa de quase qualquer falha de Pod, diminuindo significativamente o Tempo Médio para Resolução (MTTR) dentro do seu cluster.