Como resolver ImagePullBackOff no Kubernetes
ErrImagePull é a falha ao baixar a imagem do container; ImagePullBackOff é o Kubernetes esperando cada vez mais entre uma tentativa e outra. O container nunca chega a rodar, então não há log da aplicação: a resposta está nos eventos do pod.
1. Leia a mensagem do evento
No fim do describe, o evento Failed traz o erro exato que o registry devolveu:
kubectl describe pod <pod> -n <namespace>O que a mensagem quer dizer
- not found ou manifest unknown: a imagem ou a tag não existe nesse registry. Confira erro de digitação, tag apagada ou imagem publicada em outro repositório.
- unauthorized, authentication required, 401 ou 403: o registry é privado e o pod não tem credencial válida.
- toomanyrequests: o Docker Hub limitou os pulls do IP de saída dos nós.
- i/o timeout, no such host ou dial tcp: o nó não alcança o registry (DNS, firewall, proxy ou cluster privado sem rota de saída).
- no matching manifest for linux/arm64 (ou amd64): a imagem não foi publicada para a arquitetura do nó.
2. Confira a imagem que o pod pede
kubectl get pod <pod> -n <namespace> \
-o jsonpath='{.spec.containers[*].image}'3. Registry privado: imagePullSecret
Crie um Secret do tipo docker-registry no mesmo namespace do pod e referencie em spec.imagePullSecrets, ou na ServiceAccount que o pod usa:
kubectl create secret docker-registry regcred -n <namespace> \
--docker-server=<registry> --docker-username=<usuario> --docker-password=<senha>
kubectl patch serviceaccount default -n <namespace> \
-p '{"imagePullSecrets":[{"name":"regcred"}]}'AKS com ACR e EKS com ECR
- No AKS, anexe o registry ao cluster com az aks update --attach-acr <acr>, que dá ao kubelet permissão de pull sem Secret.
- No EKS, a role IAM dos nós precisa de leitura no ECR (política AmazonEC2ContainerRegistryReadOnly), e o repositório precisa estar na mesma conta ou liberar a conta do cluster.
4. Depois de corrigir
O kubelet tenta de novo sozinho, mas a espera entre tentativas chega a 5 minutos. Para não esperar, reinicie o deploy:
kubectl rollout restart deployment/<nome> -n <namespace>Sem terminal, no Kubepier
No Kubepier, o pod em ImagePullBackOff aparece entre os pods com problema e o evento com a mensagem do registry sobe para o topo dos avisos, de qualquer cluster, no navegador ou no celular. No Pro, reiniciar o deploy é um clique.