Domine a Observabilidade e Troubleshooting em Kubernetes e K3s: Guia Prático e Completo para o Dia a Dia

A observabilidade e o troubleshooting são habilidades indispensáveis para quem lida com Kubernetes, seja em clusters corporativos, ambientes OpenShift ou em instalações mais leves como o K3s. Saber investigar problemas, coletar dados relevantes e interpretar o comportamento do cluster acelera a resolução de incidentes e garante a saúde das aplicações.

1. Entendendo os Eventos no Kubernetes

Os eventos são a primeira pista sobre o que está acontecendo no cluster. Eles registram desde a criação de pods até falhas de agendamento e erros de inicialização.

Como listar eventos

kubectl get events --sort-by='.metadata.creationTimestamp'

Esse comando exibe todos os eventos ordenados cronologicamente, do mais antigo ao mais recente. Em clusters muito ativos, filtre por namespace ou recurso:

kubectl get events -n seu-namespace --field-selector involvedObject.name=nome-do-pod

Principais tipos de eventos

• FailedScheduling – o pod não conseguiu ser agendado.
• BackOff – falha repetida ao iniciar o container.
• Unhealthy – probes (liveness/readiness) estão falhando.

Esses indicadores ajudam a identificar falta de recursos, erros de configuração ou problemas de imagem.

2. Inspecionando o Estado dos Recursos

kubectl describe

Fornece detalhes completos de um recurso, incluindo a lista de eventos recentes.

kubectl describe pod meu-pod -n seu-namespace

Além da configuração, o output mostra status dos containers, condições atuais e mensagens de erro (pull de imagem, falha de probes, etc.).

Outros recursos

kubectl describe svc meu-servico
kubectl describe node meu-node
kubectl describe deployment meu-deployment

3. Logs e Acesso Interativo

Visualizando logs

kubectl logs meu-pod -n seu-namespace

Para pods com mais de um container:

kubectl logs meu-pod -c nome-do-container

Logs de containers que já terminaram (útil para crash loops):

kubectl logs meu-pod -n seu-namespace --previous

Execução de comandos dentro do container

kubectl exec -it meu-pod -- /bin/sh
# ou, se houver bash:
kubectl exec -it meu-pod -- /bin/bash

Dentro do pod, teste conectividade, DNS, etc., usando curl, ping, nslookup.

4. Diagnóstico de Rede: DNS, Services e Endpoints

Problemas de rede são causas frequentes de falhas.

Verificando DNS interno

nslookup google.com
nslookup nome-do-servico.seu-namespace.svc.cluster.local

Se a resolução falhar, o CoreDNS (ou equivalente) pode estar com problema.

Serviços e Endpoints

Listar serviços:

kubectl get svc -n seu-namespace

Detalhar um serviço:

kubectl describe svc meu-servico -n seu-namespace

Verificar os endpoints associados:

kubectl get endpoints meu-servico -n seu-namespace

Endpoints vazios indicam que o selector de labels não está encontrando pods, que probes podem estar falhando ou que os pods estão offline.

Testes dentro do cluster

curl http://meu-servico:porta/
# ou usando o IP do endpoint:
curl http://<IP-do-endpoint>:porta/

5. Métricas: Metrics Server e Prometheus

Metrics Server

Coleta métricas leves (CPU, memória) de pods e nodes em tempo real, habilitando comandos como:

kubectl top pods -n seu-namespace
kubectl top nodes

• K3s: normalmente já vem incluído; basta garantir que está ativo.
• Kubernetes padrão: instale com o manifesto oficial:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Prometheus (visão geral)

Prometheus é a solução de monitoramento avançado mais usada no ecossistema Kubernetes. Ele faz scraping de endpoints expostos por pods, nodes e componentes do cluster, armazenando séries temporais para consultas, alertas e visualizações (geralmente com Grafana).

• Por que usar? Histórico de métricas, alertas configuráveis, dashboards customizados.
• OpenShift: o Prometheus já vem integrado e habilitado nas versões recentes.

6. Padrão Mental para Debug: “O que eu esperava vs. o que o cluster está fazendo”

1. Hipótese – o que deveria acontecer?
   • O pod inicia sem erros.
   • O serviço encaminha requisições ao pod.
   • As métricas mostram uso estável.
2. Realidade – o que o cluster está fazendo?
   • Consulte eventos e describe para mensagens de erro.
   • Analise logs em busca de falhas de aplicação ou de inicialização.
   • Teste DNS e conectividade interna.
   • Verifique métricas para detectar gargalos ou consumo inesperado.
3. Diferença – onde há divergência?
   • Falha ao puxar a imagem.
   • CrashLoopBackOff.
   • Pod não agendado.
   • Serviço sem endpoints.
4. Ação – foco na causa raiz
   • DNS problemático → revisar CoreDNS.
   • Crash → checar imagem, variáveis de ambiente, probes.
   • Rede → analisar políticas de rede, selectors e serviços.

Considerações finais

Dominar os comandos e conceitos deste guia forma a base para uma rotina de observabilidade e troubleshooting eficiente em Kubernetes e K3s. A prática constante reduz o tempo de investigação, aumenta a disponibilidade e melhora o desempenho das cargas de trabalho.

Dica profissional: automatize consultas recorrentes com scripts ou ferramentas (por exemplo, kubectl wrappers) para acelerar ainda mais o processo de diagnóstico.

Referência rápida de comandos