Este é o capítulo que você vai reler. Kubernetes não esconde o problema: ele te dá estados, eventos e logs. O difícil é saber em que ordem olhar.

Selo do curso: comandos válidos para Kubernetes 1.35. Substitua nomes/namespaces pelos seus.

O método em 6 passos

1. O que está acontecendo? kubectl get pods -o wide
2. Por que? kubectl describe pod <pod> (olhe os Events no fim)
3. O app reclamou? kubectl logs <pod> e --previous
4. O nó está saudável? kubectl describe node <node>, kubectl top
5. A rede/config está certa? endpoints, DNS, secrets, probes
6. Preciso entrar no pod? kubectl exec ou kubectl debug

O estado conta a história

Status	Primeira pergunta	Comando
Pending	o scheduler conseguiu agendar?	describe pod → Events
ContainerCreating	imagem/volume/CNI?	describe pod
ImagePullBackOff	a imagem existe/tem acesso?	Events + imagePullSecrets
CrashLoopBackOff	por que o processo morre?	logs --previous
OOMKilled	estourou memória?	describe → Last State
RunContainerError	entrypoint/permissão?	logs, describe
Terminating	finalizer/PDB/nó?	describe, get pdb
Completed	Job terminou?	normal para Jobs

Pending

O pod foi criado, mas não foi agendado.

kubectl describe pod <pod> | tail -30

Causas comuns:

• Recursos insuficientes (Insufficient cpu/memory).
• nodeSelector/affinity impossível.
• Taint no nó sem toleration.
• PVC não vinculado (pod has unbound immediate PersistentVolumeClaims).
• Quota do namespace estourada.
• Anti-affinity obrigatória sem nó disponível.

Caso real: durante a manutenção de um worker, pods de Elasticsearch e RabbitMQ ficaram Pending porque a anti-affinity exigia um nó por réplica e só havia dois nós agendáveis. Não era falta de recurso; era regra de distribuição.

ContainerCreating e ImagePullBackOff

kubectl describe pod <pod> | grep -A6 Events

• Imagem inexistente/tag errada: o registry responde 404.
• Registry privado: falta imagePullSecret.
• Rate limit: Docker Hub sem autenticação.
• Arquitetura errada: imagem amd64 em nó arm64.
• Imagem só em cache em alguns nós: se o pod for reagendado, falha.

Caso real: uma imagem existia em cache em dois nós e não no terceiro. Quando o pod foi reagendado, entrou em ErrImagePull. “Funcionava” até o nó mudar.

CrashLoopBackOff

O container inicia e morre. O log atual pode estar vazio; use o anterior:

kubectl logs <pod> --previous
kubectl describe pod <pod> | grep -A5 'Last State'

Causas:

• Variável de ambiente/secret ausente.
• Dependência indisponível (banco, fila, DNS).
• Permissão de arquivo/volume.
• OOMKilled (limite de memória).
• Liveness matando o app antes de terminar o boot.

Caso real: o app subia, o Flyway aplicava a migration e o guard de credenciais derrubava o processo. O log atual mostrava só o começo; o --previous mostrou a exceção.

OOMKilled

kubectl describe pod <pod> | grep -i oom
kubectl top pod <pod>

Sintomas: Last State: Terminated, Reason: OOMKilled. Aumente o limite com base no uso real, não no chute. Memória de JVM/Node precisa de margem para off-heap.

Probes mal configuradas

• readinessProbe falhando: pod Running mas 0/1, fora do Service.
• livenessProbe agressiva: reinício em loop durante o boot.
• startupProbe ausente em app lenta: liveness mata antes de subir.

kubectl describe pod <pod> | grep -A4 -i probe

Rede e DNS

kubectl -n <ns> get endpoints <service>
kubectl -n <ns> run dns --image=busybox:1.36 --rm -it --restart=Never -- nslookup <service>

Se o DNS falha, verifique CoreDNS e NetworkPolicy. Se o Service não tem endpoints, o selector está errado ou o pod não está Ready.

Entrar no pod

kubectl exec -it <pod> -- sh
kubectl debug -it <pod> --image=busybox:1.36 --target=<container>

kubectl debug é útil quando a imagem não tem shell. Para nós, kubectl debug node/<node> cria um pod privilegiado — use com cuidado.

Eventos do cluster

kubectl get events -A --sort-by=.lastTimestamp | tail -30
kubectl -n <ns> get events --sort-by=.lastTimestamp

Eventos expiram (1h por padrão). Se o problema foi ontem, você precisa de logs/monitoramento, não de get events.

Erros de permissão e admissão

• forbidden: RBAC do ServiceAccount.
• admission webhook denied: policy/PSA.
• failed quota: ResourceQuota.
• LimitRange: request/limit fora do permitido.

kubectl auth can-i list pods --as=system:serviceaccount:<ns>:<sa>

Checklist de diagnóstico

• [ ] get pods -o wide (nó, IP, restarts).
• [ ] describe pod com Events.
• [ ] logs e logs --previous.
• [ ] describe node e top.
• [ ] endpoints/DNS.
• [ ] secrets/configmaps/probes.
• [ ] eventos do namespace.
• [ ] RBAC/admission.

Glossário

• Event: registro efêmero de decisão do cluster.
• BackOff: espera exponencial antes de nova tentativa.
• OOMKilled: morte por limite de memória.
• Ephemeral container: container de diagnóstico anexado ao pod.
• Admission webhook: validação/mutação na entrada da API.

Próximo

Temporada 1 concluída. Na Temporada 2 vamos aprofundar storage, configuração, operadores e backup — começando por PV, PVC, NFS e local-path.

Próximo: Curso Kubernetes 11 — Storage: PV, PVC, NFS e local-path