kubectl debug: o guia completo de troubleshooting de pods e nodes

kubectl debug vs. kubectl logs vs. kubectl describe

kubectl debug, kubectl logs e kubectl describe são todos comandos de troubleshooting, mas servem a propósitos diferentes. kubectl logs recupera a saída da aplicação, kubectl describe mostra detalhes e eventos dos recursos do Kubernetes, e kubectl debug fornece acesso interativo para investigação ao vivo.

kubectl logs

O comando kubectl logs exibe a saída de stdout e stderr dos containers. É comumente usado para identificar crashes da aplicação, falhas de inicialização ou erros em tempo de execução.

kubectl logs my-pod

Para pods com múltiplos containers, especifique o nome do container:

kubectl logs my-pod -c app-container

Esse comando é leve e seguro porque não modifica o pod nem cria novos containers.

kubectl describe

O comando kubectl describe fornece informações detalhadas sobre recursos do Kubernetes, incluindo labels, condições, volumes montados e eventos recentes.

kubectl describe pod my-pod

Esse comando é útil para diagnosticar problemas como:

• Falhas de agendamento
• Erros de pull de imagem
• Falhas de probes
• Restrições de recursos
• Eventos de CrashLoopBackOff

Diferentemente do kubectl logs, ele foca no estado do objeto do Kubernetes, e não na saída da aplicação.

kubectl debug

O comando kubectl debug permite o troubleshooting interativo anexando containers efêmeros ou criando pods temporários de debug.

kubectl debug my-pod -it --image=busybox

Essa abordagem é útil quando logs e descrições de recursos não são suficientes. Por exemplo, você pode:

• Inspecionar conectividade de rede
• Examinar o conteúdo do sistema de arquivos
• Executar ferramentas de inspeção de processos
• Depurar containers mínimos sem shell
• Investigar problemas em nível de node

Como cria ambientes temporários de depuração, o kubectl debug oferece acesso mais profundo do que os outros comandos, minimizando alterações em workloads de produção.

Exemplos práticos de kubectl debug

Depurar conectividade de rede

Use um container de debug para testar DNS, descoberta de serviços e acesso de saída à rede a partir do namespace de rede do pod.

kubectl debug my-pod -it --image=busybox --target=my-container

Dentro do container de debug, execute comandos como:

nslookup kubernetes.default
wget -qO- http://my-service.default.svc.cluster.local
ping 10.0.0.10

Isso é útil quando a imagem da aplicação não inclui ferramentas como nslookup, curl ou ping.

Depurar um pod em CrashLoopBackOff

Para um pod que fica reiniciando, crie uma cópia para inspeção. Isso evita alterar o workload original.

kubectl debug my-pod --copy-to=my-pod-debug -it --image=ubuntu

Você pode inspecionar variáveis de ambiente, arquivos montados, configuração e acesso de rede a partir do pod copiado:

env
ls -la /etc/config
cat /etc/config/app.conf

Isso ajuda a identificar arquivos ausentes, valores de ambiente incorretos ou dependências de runtime.

Depurar com compartilhamento de namespace de processos

Use o compartilhamento de namespace de processos quando precisar inspecionar processos de outro container do pod.

kubectl debug my-pod \
  --copy-to=my-pod-debug \
  --share-processes \
  -it \
  --image=ubuntu

Dentro do container de debug, verifique os processos em execução:

ps aux
top

Isso é útil para inspecionar processos travados, processos zumbis ou processos filhos inesperados.

Depurar usando uma imagem personalizada

Use uma imagem de debug personalizada quando as imagens padrão não incluírem as ferramentas de que você precisa.

kubectl debug my-pod -it \
  --image=my-registry.example.com/debug-tools:latest \
  --target=my-container

Uma imagem personalizada pode incluir ferramentas como curl, dig, tcpdump, strace ou clientes de banco de dados. Isso mantém as imagens de produção pequenas e, ao mesmo tempo, permite um troubleshooting mais profundo quando necessário.

Boas práticas ao usar o kubectl debug

Aqui estão algumas práticas úteis a considerar ao usar este comando.

1. Comece pela observabilidade antes de entrar no pod

Use kubectl logs, kubectl describe, eventos, métricas e traces antes de iniciar uma sessão interativa de debug. Essas ferramentas são mais rápidas, mais seguras e, muitas vezes, suficientes para identificar o problema.

kubectl logs my-pod
kubectl describe pod my-pod
kubectl get events --sort-by=.metadata.creationTimestamp

Isso ajuda a confirmar se o problema é causado pela aplicação, pelo agendamento, por probes, por limites de recursos, pela rede ou pela configuração do Kubernetes. Por exemplo, o kubectl describe pode mostrar falhas de pull de imagem, readiness probes com falha ou erros de montagem de volume antes que você gaste tempo inspecionando o container diretamente.

Use o kubectl debug quando os sinais disponíveis não explicarem o problema ou quando precisar inspecionar o estado de runtime de dentro do ambiente do pod.

2. Use containers efêmeros para inspeção, não para alterar a aplicação

Containers efêmeros são destinados a troubleshooting. Não os use para corrigir arquivos, reiniciar serviços, instalar dependências ou mudar o comportamento da aplicação em um workload em execução.

Use-os para inspecionar o estado, rodar comandos de diagnóstico e coletar evidências:

kubectl debug my-pod -it --image=busybox --target=my-container

Por exemplo, você pode verificar a resolução de DNS, inspecionar arquivos montados, testar a conectividade com serviços ou visualizar processos em execução. Essas ações ajudam a explicar o que está acontecendo sem alterar o workload.

Qualquer correção deve ser feita no código-fonte, na imagem de container, nos manifestos ou no pipeline de deploy. Isso mantém o comportamento de produção reproduzível e evita alterações manuais pontuais que desaparecem depois que o pod reinicia.

3. Prefira containers de debug a adicionar ferramentas nas imagens de produção

Evite instalar shells, gerenciadores de pacotes e ferramentas de rede em imagens de produção apenas para troubleshooting. Essas ferramentas aumentam o tamanho da imagem e podem ampliar a superfície de ataque do container.

Em vez disso, mantenha as imagens da aplicação pequenas e use uma imagem de debug separada quando necessário:

kubectl debug my-pod -it --image=nicolaka/netshoot --target=my-container

Isso é especialmente útil para imagens mínimas, como containers distroless ou baseados em scratch, que muitas vezes não incluem shell. Um container de debug pode fornecer ferramentas como curl, dig, tcpdump, ss e ip sem alterar a imagem de produção.

Essa abordagem também mantém a separação clara: a imagem da aplicação executa o workload, enquanto a imagem de debug é usada apenas durante sessões controladas de troubleshooting.

4. Use imagens de debug aprovadas e seguras

Imagens de debug frequentemente incluem ferramentas poderosas como tcpdump, strace, curl, dig, gerenciadores de pacotes e utilitários de shell. Use apenas imagens aprovadas de registries confiáveis.

Fixe as versões das imagens em vez de usar tags flutuantes:

kubectl debug my-pod -it --image=registry.example.com/debug-tools:1.4.2

As imagens aprovadas devem ser escaneadas em busca de vulnerabilidades e mantidas atualizadas. Elas devem conter as ferramentas de que suas equipes realmente precisam, sem pacotes desnecessários.

O acesso também deve ser controlado com RBAC. Nem todo usuário deve poder criar containers efêmeros, anexar-se a workloads sensíveis ou iniciar sessões de debug em nível de node. A depuração de node pode expor sistemas de arquivos do host e informações em nível de sistema, por isso deve ser limitada a operadores confiáveis — combine isso com a flag --profile (restricted ou baseline) sempre que possível, para não conceder mais acesso do que a sessão precisa.

5. Remova os pods de debug e documente a sessão

Remova os pods de debug copiados após o troubleshooting para evitar acúmulo e uso desnecessário de recursos.

kubectl delete pod my-pod-debug

Containers efêmeros adicionados a pods existentes não podem ser removidos da spec do pod, mas param de rodar quando a sessão de depuração termina. Os pods copiados, no entanto, permanecem no cluster até serem excluídos.

Registre o que foi verificado, quais comandos foram executados e o que foi encontrado. Isso facilita a revisão do incidente e ajuda a melhorar os runbooks para problemas futuros.

Boas anotações devem incluir o pod ou node afetado, a imagem de debug usada, saídas importantes de comandos e a causa final. Isso ajuda outros engenheiros a não repetir a mesma investigação depois.

Reduza a depuração manual corrigindo proativamente riscos de resiliência com a PerfectScale

Comandos como kubectl debug são essenciais quando você precisa investigar um pod com crash, um processo travado ou um problema em nível de node em tempo real, mas a maioria desses incidentes tem origem em configurações incorretas de recursos que poderiam ter sido detectadas antes. A PerfectScale aumenta de forma autônoma a resiliência e o desempenho do Kubernetes fazendo right-sizing dos workloads, prevenindo downtime e otimizando o uso de recursos para 99,99% de disponibilidade, para que sua equipe passe menos tempo abrindo sessões interativas de debug e mais tempo entregando. Em vez de esperar um pod falhar para então recorrer a containers efêmeros, a PerfectScale identifica e corrige na origem os riscos de resiliência que causam essas falhas.

Principais recursos da PerfectScale:

• Correção automática de problemas: identifica e corrige instantaneamente riscos de resiliência para maximizar o uptime e eliminar latência, prevenindo erros de configuração (sem CPU request, sem memory request, sem memory limits) e problemas de subprovisionamento de recursos como OOM, CPU throttling e eviction.
• Fortalecimento da infraestrutura: oferece visibilidade holística dos seus nodes para expor configurações incorretas de forma proativa, prevenir o over-commitment de nodes com recomendações precisas de memory limit, validar node affinities e taints e escolher os tipos de node mais adequados para seus pods.
• Priorização orientada por impacto: concentra sua equipe nos problemas mais críticos em tempo real com priorização automática avançada e alinha os alertas aos seus SLAs e SLOs para manter os níveis de serviço dentro da meta.
• Alertas em tempo real e integrações com ticketing: envia notificações instantâneas via Slack, MS Teams ou Datadog e permite escalar qualquer problema para um fluxo de trabalho estabelecido criando um ticket com um clique.
• Ampla cobertura de riscos: detecta continuamente evictions, out of memory, suspeitas de memory leaks, CPU throttling, restarts de pods, HPA atingindo o máximo de réplicas e requests e limits de CPU e memória subprovisionados ou não definidos.

Saiba mais sobre como a PerfectScale pode manter seus clusters estáveis e reduzir a necessidade de troubleshooting manual na plataforma de otimização de performance para Kubernetes.

FAQ

Para que serve o comando kubectl debug?

O kubectl debug é usado para solucionar problemas em workloads e nodes do Kubernetes de forma interativa. Ele pode anexar um container efêmero a um pod em execução, criar uma cópia modificada de um pod com crash ou iniciar um pod de debug em um node — tudo sem precisar de ferramentas de depuração já incluídas na imagem de destino.

Como usar o kubectl debug em um pod?

Execute kubectl debug <pod-name> -it --image=busybox para anexar um container efêmero de debug a um pod em execução. Adicione --target=<container-name> para compartilhar o namespace de processos com um container específico, ou --copy-to=<new-pod-name> para depurar uma cópia em vez do pod ativo (útil para pods que travam na inicialização).

Como usar o kubectl debug em um node?

Execute kubectl debug node/<node-name> -it --image=ubuntu para criar um pod de debug que roda nos namespaces do host do node com o sistema de arquivos raiz do node montado em /host. O padrão é o profile general, que não concede acesso privilegiado — use --profile=sysadmin se precisar de permissões completas em nível de root.

Qual é a sintaxe do comando kubectl debug?

A forma geral é kubectl debug (POD | TYPE/NAME) [flags], usada mais comumente com --image para definir a imagem do container de debug, -it para um terminal interativo, --target para direcionar a um container específico e --copy-to para depurar uma cópia do pod.

Qual a diferença entre kubectl debug e kubectl exec?

O kubectl exec executa um comando dentro de um container existente, usando a própria imagem do pod, por isso só funciona se essa imagem já tiver as ferramentas de que você precisa. O kubectl debug anexa um container (ou pod) separado com qualquer imagem que você escolher, o que é essencial para containers mínimos ou distroless que não têm shell algum.

O kubectl debug modifica o pod original ou seus containers?

Adicionar um container efêmero com kubectl debug não reinicia nem modifica os containers existentes do pod — apenas adiciona um container temporário ao lado deles. Usar --copy-to vai além e cria um pod separado, deixando o original completamente intocado.

Preciso limpar os pods criados pelo kubectl debug?

Sim, para qualquer pod criado com --copy-to. Esses pods persistem no cluster até você excluí-los com kubectl delete pod <debug-pod-name>. Containers efêmeros adicionados diretamente a um pod existente não precisam de limpeza separada — eles param de rodar quando a sessão termina, embora continuem listados na spec do pod.