Troubleshooting no Kubernetes: comandos, erros e como corrigir

TLDR:
O troubleshooting no Kubernetes funciona de baixo para cima: verifique o status do pod, inspecione os eventos, veja os logs e, se necessário, faça debugging interativo. A maioria dos problemas se resume a um punhado de erros recorrentes (ImagePullBackOff, CrashLoopBackOff, Pending, OOMKilled), todos rastreáveis com kubectl describe/logs. Evite problemas recorrentes definindo requests e limits de recursos adequados, ajustando as probes, monitorando continuamente e fazendo right-sizing dos workloads ao longo do tempo.

Códigos de erro comuns no Kubernetes e como corrigi-los

ImagePullBackOff

Problema: o ImagePullBackOff ocorre quando o Kubernetes não consegue baixar a imagem de container necessária para iniciar um pod. Após a falha inicial ao baixar a imagem, o Kubernetes tenta novamente com intervalos progressivamente maiores. Até que a imagem fique disponível, o pod permanece sem entrar em execução.

Diagnóstico: falhas ao baixar imagens são comumente causadas por nomes de imagem inválidos, tags incorretas, credenciais de registry ausentes, tokens de autenticação expirados, indisponibilidade do registry ou problemas de conectividade de rede. O ponto de partida mais útil é a seção Events da descrição do pod.

Execute kubectl describe pod <pod-name> e procure por mensagens como ErrImagePull, pull access denied, unauthorized ou manifest unknown. Essas mensagens geralmente indicam se a falha está relacionada a autenticação, disponibilidade da imagem ou conectividade.

Fluxo de resolução:

1. Execute kubectl describe pod <pod-name> e revise a seção Events.
2. Verifique se o nome e a tag da imagem estão corretos e existem no registry.
3. Confirme que o container registry está acessível a partir dos nodes do cluster.
4. Valide os image pull secrets configurados no pod ou na service account.
5. Verifique as credenciais do registry, as permissões e o status de expiração dos tokens.
6. Verifique a resolução de DNS e a conectividade de rede de saída dos worker nodes.
7. Revise as configurações de proxy, firewall ou network policies que possam bloquear o acesso ao registry.

Exemplo

kubectl describe pod my-pod
kubectl get secrets
kubectl describe secret registry-secret

CrashLoopBackOff

Problema: o CrashLoopBackOff indica que um container inicia, encerra e é reiniciado repetidamente pelo Kubernetes. Após várias falhas consecutivas, o Kubernetes introduz intervalos crescentes entre as tentativas de reinicialização para evitar ciclos constantes de restart.

Diagnóstico: essa condição costuma ser causada por falhas na inicialização da aplicação, valores de configuração inválidos, variáveis de ambiente ausentes, falha na inicialização de dependências, problemas de conectividade com banco de dados ou comandos de container incorretos.

Os logs do container geralmente são a forma mais rápida de identificar a causa-raiz. Revise os logs usando kubectl logs <pod-name>. Se o container reiniciar rápido demais, use a flag --previous para recuperar os logs da última instância que falhou. A descrição do pod também pode revelar motivos de encerramento, códigos de saída, contagens de reinicialização e falhas de probes.

Fluxo de resolução:

1. Revise os logs da aplicação usando kubectl logs <pod-name>.
2. Se necessário, recupere os logs da instância anterior do container usando --previous.
3. Inspecione os eventos do pod e os detalhes de encerramento com kubectl describe pod <pod-name>.
4. Verifique as variáveis de ambiente, arquivos de configuração, secrets e comandos de inicialização.
5. Verifique as conexões com bancos de dados, dependências externas e endpoints de services.
6. Revise os limites de CPU e memória em busca de sinais de esgotamento de recursos.
7. Valide as configurações das probes de readiness, startup e liveness e ajuste os limites de tempo, se necessário.

Exemplo

kubectl logs my-pod
kubectl logs my-pod --previous
kubectl describe pod my-pod

Pending

Problema: um pod entra no estado Pending quando o Kubernetes aceita a definição do pod, mas não consegue atribuí-lo a um node adequado. O workload permanece sem agendamento e não inicia até que todos os requisitos de agendamento sejam atendidos.

Diagnóstico: pods em Pending são causados, na maioria das vezes, por recursos insuficientes no cluster, regras de agendamento restritivas, falhas no provisionamento de armazenamento ou restrições de posicionamento em nodes. Mensagens comuns de agendamento incluem CPU insuficiente, memória insuficiente, node selectors sem correspondência, conflitos de taints ou PersistentVolumeClaims não vinculados.

Os eventos de agendamento exibidos por kubectl describe pod <pod-name> normalmente identificam o motivo exato pelo qual o scheduler não conseguiu alocar o workload.

Fluxo de resolução:

1. Execute kubectl describe pod <pod-name> e revise os eventos do scheduler.
2. Verifique a disponibilidade dos nodes usando kubectl get nodes.
3. Confirme que existem recursos suficientes de CPU e memória no cluster.
4. Revise os node selectors, as regras de node affinity, os taints e as tolerations.
5. Valide que os labels de node necessários estão presentes.
6. Verifique os PersistentVolumeClaims (PVC) e o status do provisionamento de armazenamento.
7. Se o autoscaling estiver habilitado, confirme que o cluster autoscaler está funcionando corretamente.

Exemplo

kubectl describe pod my-pod
kubectl get nodes
kubectl get pvc

OOMKilled

Problema: o OOMKilled ocorre quando um container excede seu limite de memória configurado e é encerrado pelo out-of-memory (OOM) killer do Linux. O Kubernetes aplica os limites de memória de forma rigorosa, fazendo com que o container pare imediatamente quando o limite é excedido.

Diagnóstico: o esgotamento de memória pode resultar de vazamentos de memória, caching excessivo, comportamento ineficiente da aplicação, picos de tráfego, grandes volumes de dados ou limites de memória definidos abaixo do necessário para o workload.

A descrição do pod geralmente mostra OOMKilled como o motivo do encerramento. Ferramentas de monitoramento de recursos como Prometheus, Grafana ou Metrics Server podem ajudar a determinar se o workload sofre pressão de memória sustentada ou picos repentinos de uso.

Fluxo de resolução:

1. Confirme o motivo do encerramento usando kubectl describe pod <pod-name>.
2. Revise as métricas de consumo de memória antes da falha.
3. Identifique picos de memória, vazamentos ou utilização alta sustentada.
4. Compare o uso real de memória com os requests e limits configurados.
5. Aumente os limites de memória se estiverem claramente subdimensionados.
6. Investigue causas no nível da aplicação, como caching, concorrência ou vazamentos de memória.
7. Otimize o uso de memória da aplicação e ajuste as configurações de recursos com base no comportamento observado do workload.

Exemplo

kubectl describe pod my-pod
kubectl top pod my-pod
kubectl top nodes

5 formas de evitar problemas no Kubernetes antes que aconteçam

Equipes experientes em Kubernetes planejam seus clusters de forma a minimizar falhas comuns. Isso aumenta a resiliência e também facilita o troubleshooting quando os problemas realmente surgem.

1. Defina requests e limits de recursos

Os requests e limits de recursos ajudam o Kubernetes a alocar CPU e memória de forma previsível em todo o cluster. Os requests definem os recursos mínimos necessários para o agendamento, enquanto os limits definem o máximo de recursos que um container pode consumir. Uma configuração adequada evita que os workloads disputem agressivamente recursos compartilhados.

Sem requests, o scheduler não consegue tomar decisões precisas de alocação, o que pode levar a nodes sobrecarregados e workloads instáveis. Sem limits, um único container pode consumir memória ou CPU em excesso, afetando outras aplicações em execução no mesmo node.

Limits configurados com cuidado ajudam a reduzir o risco de eventos de OOMKilled, throttling de CPU e esgotamento de recursos dos nodes. No entanto, limits definidos muito baixos também podem criar instabilidade ao restringir as aplicações durante períodos de pico de carga.

Usar políticas de LimitRange e ResourceQuota no nível do namespace ajuda a garantir práticas consistentes de gerenciamento de recursos entre equipes e ambientes. Esses controles reduzem a probabilidade de workloads mal configurados afetarem a estabilidade do cluster.

2. Use probes de readiness e liveness com cuidado

As probes de readiness e liveness ajudam o Kubernetes a determinar se os containers estão saudáveis e prontos para receber tráfego. Uma configuração adequada de probes melhora a confiabilidade das aplicações, impedindo que pods não saudáveis atendam requisições e reiniciando automaticamente containers com falha.

As probes de readiness controlam se um pod é adicionado à lista de endpoints de um service. Se a probe de readiness falhar, o tráfego deixa de ser roteado para o pod até que ele se recupere. Isso ajuda a evitar que os usuários acessem aplicações parcialmente inicializadas ou degradadas.

As probes de liveness detectam deadlocks da aplicação ou processos que não respondem. Quando uma probe de liveness falha repetidamente, o Kubernetes reinicia o container automaticamente. Esse mecanismo melhora o comportamento de autorrecuperação, mas também pode criar instabilidade se for configurado incorretamente.

Tempos de probe agressivos são uma fonte comum de reinicializações desnecessárias e de condições de CrashLoopBackOff. Aplicações que exigem longos tempos de inicialização podem falhar nos health checks antes de concluir a inicialização. As startup probes costumam ser úteis para workloads com processos de boot lentos.

3. Monitore eventos, logs e métricas

O monitoramento contínuo é essencial para detectar problemas no Kubernetes antes que eles se transformem em indisponibilidades. Logs, métricas e eventos do cluster fornecem visibilidade sobre o comportamento dos workloads, o uso de recursos, a saúde da infraestrutura e as falhas operacionais.

Plataformas de métricas como Prometheus e Grafana ajudam a acompanhar o uso de CPU, o consumo de memória, as reinicializações de pods, a latência de rede e o desempenho de armazenamento. Monitorar tendências ao longo do tempo permite que os engenheiros identifiquem comportamentos anormais antes que os serviços fiquem instáveis.

Sistemas de logging centralizado melhoram o troubleshooting ao agregar logs de containers, logs de nodes e eventos de sistema em uma plataforma pesquisável. Ferramentas como Elasticsearch, Fluent Bit, Loki e Splunk são comumente usadas para coleta e análise de logs do Kubernetes.

Os eventos do Kubernetes fornecem contexto operacional adicional ao registrar falhas de agendamento, erros ao baixar imagens, evicções de pods e problemas de configuração. Como os eventos são temporários, coletá-los e armazená-los externamente melhora a capacidade de troubleshooting no longo prazo.

4. Use namespaces e labels de forma consistente

Os namespaces ajudam a organizar workloads e isolar recursos dentro de um cluster Kubernetes. O uso consistente de namespaces melhora a clareza operacional, o controle de acesso, o gerenciamento de recursos e a eficiência do troubleshooting.

Separar ambientes como desenvolvimento, staging e produção em namespaces diferentes reduz o risco de interferência acidental entre workloads. Políticas no nível do namespace também podem impor limites de segurança e cotas de recursos.

Os labels fornecem metadados usados para seleção, agrupamento, monitoramento e automação de workloads. Services, deployments, network policies e sistemas de monitoramento do Kubernetes dependem fortemente de labels para identificar workloads.

Esquemas de labels inconsistentes ou mal projetados costumam causar falhas de roteamento de services, confusão nos deployments e complexidade operacional. Labels padronizados facilitam a busca, o monitoramento e o gerenciamento de workloads em clusters grandes.

5. Faça right-sizing contínuo dos workloads com base no uso real

Os requisitos de recursos dos workloads mudam ao longo do tempo à medida que as aplicações evoluem, os padrões de tráfego se alteram e o uso da infraestrutura cresce. O right-sizing contínuo dos workloads ajuda a manter o desempenho enquanto reduz o desperdício de recursos do cluster.

Workloads superdimensionados desperdiçam CPU e memória, aumentando os custos de infraestrutura e reduzindo a eficiência do cluster. Workloads subdimensionados criam instabilidade, falhas de agendamento, throttling de CPU e crashes relacionados à memória.

Monitorar o comportamento real dos workloads fornece os dados necessários para otimizar requests e limits de recursos. Os engenheiros devem analisar padrões de uso de longo prazo em vez de depender apenas de picos de curto prazo ou de estimativas do deployment inicial.

Ferramentas como o Vertical Pod Autoscaler (VPA) podem recomendar ou ajustar automaticamente as configurações de recursos com base no consumo observado. O Horizontal Pod Autoscaler (HPA) complementa essa abordagem ao escalar a quantidade de réplicas em resposta a mudanças de carga.

Como o PerfectScale ajuda você a prevenir e resolver problemas no Kubernetes

A maior parte do troubleshooting no Kubernetes é reativa: você espera um pod falhar e depois vasculha eventos, logs e métricas para encontrar a causa. O PerfectScale inverte esse modelo ao fazer right-sizing autônomo dos workloads, prevenindo downtime e otimizando o uso de recursos para manter 99,99% de disponibilidade. Em vez de perseguir manualmente eventos de OOMKilled, CrashLoopBackOff e throttling, suas equipes de DevOps, SRE e engenharia de plataforma contam com remediação contínua e orientada por dados em todas as camadas da stack K8s.

Principais recursos do PerfectScale:

• Remediação automática de problemas: identifique e corrija instantaneamente riscos de resiliência para maximizar o uptime e eliminar a latência, tratando problemas como OOM, throttling de CPU e evicções de pods antes que se transformem em indisponibilidades em cascata.
• Prevenção de erros de configuração: detecte as configurações incorretas por trás das falhas mais comuns, incluindo requests de CPU ausentes, requests de memória ausentes e limits de memória não definidos, para que os workloads iniciem e rodem de forma confiável.
• Detecção de subprovisionamento: revele CPU e memória subprovisionadas (tanto requests quanto limits) e suspeitas de vazamento de memória — as causas-raiz que mantêm pods presos em loops de restart mesmo quando os nodes parecem saudáveis.
• Fortalecimento da infraestrutura: obtenha visibilidade holística dos nodes para evitar o over-commitment, validar node affinities e taints e escolher os tipos de node ideais para seus workloads.
• Priorização orientada por impacto: alinhe os alertas aos seus SLAs e SLOs, receba notificações instantâneas via Slack, MS Teams ou Datadog e transforme problemas em tickets com um clique.
• Otimização de autoscaling: faça o ajuste fino das configurações de autoscaling horizontal e vertical para que os gatilhos de escalonamento disparem com precisão, evitando os cenários de "HPA no máximo de réplicas" e de esgotamento de recursos que geram instabilidade.

FAQ

Qual é o primeiro comando a executar quando um pod está com problemas? kubectl get pods para localizar o pod com falha e, em seguida, kubectl describe pod <pod-name> para ver detalhes sobre seu estado e eventos recentes.

O que causa o CrashLoopBackOff? O container inicia, encerra e reinicia repetidamente — geralmente por falha na inicialização, configuração incorreta, variáveis de ambiente ausentes ou erro de conexão com banco de dados/dependência. Verifique primeiro kubectl logs <pod-name> --previous.

O que causa o ImagePullBackOff? O Kubernetes não consegue baixar a imagem do container — muitas vezes por nome/tag de imagem inválido, credenciais de registry ausentes ou expiradas, ou um problema de rede ao acessar o registry.

Por que meu pod está preso em Pending? O scheduler não consegue alocá-lo — normalmente por CPU/memória insuficientes no cluster, node selectors ou taints sem correspondência, ou um PersistentVolumeClaim não vinculado. kubectl describe pod <pod-name> mostra o motivo exato da falha de agendamento.

O que significa OOMKilled? O container excedeu seu limite de memória e foi encerrado pelo OOM killer do Linux. Compare o uso de memória com os requests/limits configurados e procure por vazamentos ou limits subdimensionados.

Como faço debug de problemas de rede ou DNS? Use kubectl get endpoints para confirmar que os pods estão vinculados a um service e kubectl exec -it <pod-name> -- nslookup <service-name> para testar a resolução de DNS de dentro de um pod.

Como posso prevenir esses problemas em vez de apenas reagir a eles? Defina requests/limits de recursos adequados, configure as probes de readiness/liveness com cuidado, monitore logs/eventos/métricas continuamente, use namespaces e labels de forma consistente e faça right-sizing dos workloads ao longo do tempo (por exemplo, com VPA/HPA ou uma ferramenta como o PerfectScale).

Pronto para parar de apagar incêndios no Kubernetes? Conheça a plataforma de desempenho e resiliência para Kubernetes do PerfectScale e veja como a otimização autônoma mantém seus clusters estáveis, resilientes e eficientes em custos.