Depuração de Implantações com Falha: Identificando Erros Comuns de YAML e Configuração

As falhas de implantação no Kubernetes geralmente se manifestam como pods presos em Pending, ImagePullBackOff, CrashLoopBackOff ou zero réplicas disponíveis. A causa geralmente é visível nos eventos, mas você precisa inspecionar a Implantação, o ReplicaSet e os Pods na ordem correta.

Este guia percorre as verificações que geralmente encontram erros de YAML, problemas de pull de imagem, probes ruins, restrições de recursos e regras de agendamento que impedem que sua implantação se torne saudável.

Os Primeiros Passos: Verificando o Status da Implantação e Eventos

Quando uma implantação falha, seus primeiros passos de diagnóstico devem sempre envolver a verificação do recurso primário em si e dos eventos associados aos seus ReplicaSets e Pods gerenciados. Isso fornece a visão de mais alto nível do que o Kubernetes está tentando fazer e por que está falhando.

1. Inspecionando a Saúde da Implantação

Use kubectl get deployments para ver o status geral. Observe especificamente as colunas READY, UP-TO-DATE e AVAILABLE. Uma discrepância aqui indica um problema com os Pods subjacentes.

kubectl get deployments <nome-da-implantação>

Se o status da implantação mostrar poucas ou zero réplicas prontas, prossiga para verificar o ReplicaSet.

2. Revisando Eventos do ReplicaSet e do Pod

Os ReplicaSets gerenciam o número desejado de Pods. Se a implantação falhar, o ReplicaSet geralmente é a fonte da cascata de erros. Use o comando describe no ReplicaSet, que geralmente é nomeado <nome-da-implantação>-<hash>:

kubectl describe rs <nome-do-replicaset>

Crucialmente, examine a seção Eventos na parte inferior da saída. Esta seção detalha ações recentes, incluindo tentativas de agendamento, falhas de pull de imagem e problemas de montagem de volume. Esses eventos são frequentemente a prova definitiva.

Finalmente, verifique os próprios Pods, pois eles relatam a falha imediata:

kubectl get pods -l app=<rótulo-do-seu-app>
kubectl describe pod <nome-do-pod>

Procure pelos campos State e Reason na descrição do pod. Razões comuns incluem ImagePullBackOff, ErrImagePull, CrashLoopBackOff e Pending.

Erros Comuns de Configuração em Manifestos YAML

Configurações incorretas em seus arquivos YAML são a causa mais frequente de falhas de implantação. Esses erros podem variar de simples erros de indentação a problemas estruturais complexos.

1. Erros de Sintaxe e Estrutura YAML

As APIs do Kubernetes são extremamente sensíveis à sintaxe YAML correta (indentação, espaçamento e tipos de dados). Se o YAML for inválido, kubectl apply geralmente falhará imediatamente, informando que não pode analisar o arquivo.

Melhor Prática: Use um Linter Sempre valide sua sintaxe YAML antes de aplicar. Ferramentas como yamllint ou suporte IDE integrado podem detectar erros básicos de sintaxe imediatamente.

Exemplo de um erro estrutural comum: Mapeamento ou indentação incorretos.

# INCORRETO: containers pertence a spec.template.spec, não diretamente a spec.template
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      labels:
        app: my-app
    containers:
      - name: my-app
        image: myregistry/myapp:v1

Posicionamento correto:

spec:
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: myregistry/myapp:v1
          ports:
            - containerPort: 8080

2. Erros de Referência e Pull de Imagem

Se os Pods entrarem em ImagePullBackOff ou ErrImagePull, o problema está relacionado ao acesso à imagem do contêiner.

• Erro de Digitação no Nome/Tag da Imagem: Verifique novamente a grafia do repositório da imagem, nome e tag.
• Autenticação de Registro Privado: Se estiver puxando de um registro privado, certifique-se de ter criado um segredo de pull de imagem e referenciado-o como imagePullSecrets na especificação do Pod.

# Trecho mostrando o uso de ImagePullSecret
spec:
  imagePullSecrets:
    - name: my-registry-secret
  containers:
    - name: my-app
      image: private.example.com/my-app:v1

3. Violações de Solicitações e Limites de Recursos

Se um Pod permanecer no status Pending e os eventos mencionarem recursos insuficientes, os nós do cluster não podem satisfazer os requisitos de CPU ou memória definidos no YAML.

Verifique os limites especificados em seu manifesto de implantação:

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

Etapas de Solução de Problemas:

1. Use kubectl describe nodes para ver a capacidade disponível.
2. Se você vir eventos como 0/3 nodes are available: 3 Insufficient cpu, você deve diminuir as requests em seu YAML ou adicionar mais nós ao cluster.

Problemas de Configuração Avançados

Além da sintaxe básica e pull de imagens, configurações complexas envolvendo rede, armazenamento e agendamento podem levar a falhas difíceis de diagnosticar.

1. Probes Mal Configurados (Liveness e Readiness)

Se um Pod transitar para CrashLoopBackOff, geralmente significa que o contêiner inicia, mas falha imediatamente em uma verificação, ou inicia, mas falha repetidamente em seu probe de prontidão.

• Liveness Probes: Se isso falhar repetidamente, o Kubernetes reinicia o contêiner. Verifique kubectl describe pod <nome-do-pod> para eventos de falha de probe e kubectl logs <nome-do-pod> --previous após uma reinicialização.
• Readiness Probes: Se isso falhar, o Pod continua em execução, mas é mantido fora dos endpoints do Service. Certifique-se de que o caminho, a porta e o código de resposta esperado correspondam ao que seu aplicativo está realmente servindo.

Exemplo de um erro comum de Readiness Probe: Mirar na porta errada ou esperar HTTP quando o aplicativo expõe apenas TCP.

2. Falhas de Volume e PersistentVolumeClaim (PVC)

Se os Pods estiverem pendentes devido a problemas de volume, inspecione o status do PVC:

kubectl get pvc <nome-do-pvc>

Se o status do PVC for Pending, significa que o cluster não conseguiu encontrar uma StorageClass correspondente ou um PersistentVolume adequado para se vincular. Verifique os eventos do PVC para erros de vinculação específicos.

3. Regras de Afinidade e Anti-Afinidade

Regras de agendamento complexas, como nodeAffinity ou podAntiAffinity, podem impedir involuntariamente que um Pod seja agendado se nenhum nó satisfizer todos os critérios. Se os Pods permanecerem Pending e os eventos mencionarem restrições de agendamento, revise essas regras.

Por exemplo, se você exigir que um Pod seja executado em um nó com um rótulo específico (nodeSelector) que nenhum nó existente possui, o Pod nunca será agendado.

# Exemplo: Restringindo a implantação a nós rotulados como 'disktype: ssd'
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

Dica de Solução de Problemas: Comente temporariamente nodeSelector ou regras de affinity restritivas. Se o Pod for agendado com sucesso, você sabe que o problema está nos critérios de seleção.

Fluxo de Trabalho de Depuração

Ao enfrentar uma implantação com falha, siga este caminho estruturado:

1. Status da Implantação: kubectl get deployments -> As réplicas estão relatando prontas?
2. Eventos do Pod: kubectl describe pod <pod-com-falha> -> Verifique a seção Eventos para erros imediatos (ImagePull, OOMKilled, problemas de Volume).
3. Logs do Contêiner: kubectl logs <pod-com-falha> -> Se o contêiner iniciar, mas falhar (CrashLoopBackOff), a lógica do aplicativo ou os probes de liveness são suspeitos.
4. Verificação de Recursos: Se o Pod estiver Pending, verifique restrições de recursos (Insufficient cpu/memory) ou falhas de vinculação de volume (status do PVC).
5. Validação de Configuração: Revise o YAML para indentação, nomes de campo corretos e valores de recursos válidos (requests/limits).

Trabalhe a partir das evidências do cluster em vez de adivinhar. Verifique status, eventos, logs, recursos e estrutura do manifesto nessa ordem e, em seguida, faça a menor alteração de YAML que corresponda ao erro encontrado.