O que o kubectl debug não te conta: a lacuna silenciosa na evidência de incidentes

O que o kubectl debug não te conta: a lacuna silenciosa na evidência de incidentes

Este artigo analisa por que sessões de kubectl debug não retêm seu histórico de execução na API do Kubernetes após o término. Devido a decisões de design que excluem os campos lastState e contagem de restarts para containers efêmeros, evidências críticas de incidentes, logs e códigos de saída são perdidos assim que o status do pod é alterado. A conclusão é que equipes de SRE precisam implementar log estruturado externo ou capturas via Watch API para garantir a auditabilidade necessária.

A sessão que não deixou rastro

Uma sessão de kubectl debug pode conter a única observação direta de um estado falho do sistema. No entanto, uma vez que a sessão termina, o Kubernetes não retém o contexto de encerramento dessa sessão na sua API. Isso não é um bug do kubectl — trata-se de uma decisão fundamental de design da API do Kubernetes para containers efêmeros.

Quando o estado do pod muda, a API do Kubernetes deixa de expor o contexto de terminação da sessão de debug. O código de saída que codificou sua descoberta, a duração da sessão e qual container você alvo não são mantidos pela API após atualizações subsequentes no pod.

Veja como isso acontece e o que significa para o seu workflow de resposta a incidentes.

Como reproduzir em três comandos

Você não precisa de um cluster especial para notar essa lacuna; qualquer cluster Kubernetes 1.25+ é suficiente.

Passo 1 — Deploy de um pod para teste:

Copiarkubectl run debug-target --image=nginx:alpine -n default
kubectl wait --for=condition=Ready pod/debug-target -n default

Passo 2 — Inicie uma sessão de debug, rode por 10 segundos e encerre com um código específico:

Copiarkubectl debug debug-target -n default \
  --image=busybox:1.36 \
  --target=nginx \
  -it -- sh -c "echo 'finding: connection pool exhausted'; sleep 10; exit 42"

Nota: --target é um recurso da CLI kubectl que roteia o container de debug para o namespace de processos do container alvo. Este parâmetro não é armazenado como campo na API do pod.

Passo 3 — Logo após o encerramento, inspecione o status do container efêmero:

Copiarkubectl get pod debug-target -n default \
  -o jsonpath='{.status.ephemeralContainerStatuses[*]}' | jq .

Resultado:

Copiar{
  "containerID": "containerd://...",
  "image": "busybox:1.36",
  "name": "debugger-xxxxx",
  "ready": false,
  "state": {
    "terminated": {
      "exitCode": 42,
      "finishedAt": "2026-04-17T16:43:56Z"
    }
  }
}

O código de saída é visível apenas enquanto a entrada em State.Terminated persiste. No momento em que qualquer evento modifica o pod, esse contexto é substituído e o código de saída anterior torna-se inobservável. Se você tentar acessar os logs após o fim da sessão:

Copiarkubectl logs debug-target -c debugger-xxxxx -n default
# Error from server (NotFound): container "debugger-xxxxx" not found

Não existe um lastState para recorrer. Uma vez que o estado atual muda, o contexto de terminação se perde.

Por que o design da API priorizou isso?

Esta não é uma falha, mas uma decisão explícita. O tipo EphemeralContainerStatus na API do Kubernetes (v1.32) não inclui um campo lastState, diferentemente de um container convencional:

• ContainerStatus.lastState: Preserva o registro de término anterior (código de saída, tempos, motivo) e sobrevive a restarts.
• EphemeralContainerStatus: Não possui equivamente, pois containers efêmeros são definidos como "não reiniciáveis em caso de falha".

O que é perdido na prática?

Sinal de Investigação	Visível após mudança de estado do Pod?
Código de Saída	Apenas enquanto State.Terminated existir
Duração da Sessão	Não disponível
Container Alvo (--target)	Não gravado como campo da API
Logs do container de debug	Inacessíveis após terminação

Qual o impacto na resposta a incidentes?

Em um cenário de handoff entre engenheiros de plantão SRE, a perda desses dados significa que o segundo engenheiro muitas vezes precisará recomeçar do zero. Para ambientes regulados (PCI-DSS, SOC 2), a ausência de logs auditáveis sobre quem acessou o container e o que foi feito cria um risco operacional de conformidade significativo.

O que pode ser feito?

1. Logging em nível de aplicação: Convenção de equipe para exportar logs para volumes compartilhados ou sistemas de log centralizados (SIEM).
2. Captura via Watch API: Ferramentas que monitoram o ciclo de vida do pod podem capturar o bloco State.Terminated antes que ele seja substituído por um evento subsequente.
3. Observabilidade Externa: Enviar resultados de debug para sistemas externos de auditoria.

Vale uma KEP?

A introdução de um histórico mínimo de terminação para containers efêmeros, replicando algo similar ao lastState, seria uma evolução natural para SIG Node ou SIG Instrumentation, dado que o kubectl debug se tornou uma ferramenta de linha de frente nas operações modernas.

---

Artigo originalmente publicado por Shamsher Khan, CNCF Community Member em Cloud Native Computing Foundation.

Perguntas Frequentes

• Por que o Kubernetes descarta os logs do meu container de debug?
  Os containers efêmeros foram projetados sem semântica de reinicialização. Diferente de containers regulares, a API do Kubernetes não mantém o campo lastState para eles, resultando na perda dos metadados de término assim que o status do pod muda.

• Como posso garantir a rastreabilidade em investigações complexas?
  Como a API não armazena logs ou metas de target após a exclusão do container, a recomendação é enviar logs de diagnóstico para volumes persistentes, sistemas de logging centralizados ou utilizar a Watch API para capturar o evento de término em tempo real.

• Isso pode afetar a conformidade (compliance) da minha empresa?
  Sim. Regras como PCI-DSS ou controles de SOC 2 exigem auditoria de acesso e ações operacionais. Como o Kubernetes não registra nativamente quem acessou qual container via debug ou por quanto tempo, auditorias podem identificar uma lacuna de rastreabilidade.