ImagePullBackOff/ErrImagePull

O que é ImagePullBackOff?

ImagePullBackOff ou ErrImagePull significa que o Kubernetes não conseguiu baixar a imagem do contêiner do registro de contêineres. Como resultado, o Pod não pode ser iniciado.

Dica:
ErrImagePull = O Kubernetes não conseguiu baixar a imagem.
ImagePullBackOff = O Kubernetes está tentando baixar a imagem novamente com atrasos crescentes (backoff).

Sintomas

• O Pod permanece no estado ImagePullBackOff ou ErrImagePull.
• O contêiner nunca inicia.
• O status do Pod permanece como Pending ou ContainerCreating.
• Os eventos mostram falhas na extração de imagens.

Exemplo:

´´´txt
NAME READY STATUS RESTARTS AGE
nginx-pod 0/1 ImagePullBackOff 0 2m
´´´

Causas comuns

• Nome da imagem incorreto.
• Tag de imagem incorreta.
• Falha na autenticação do registro privado.
• imagePullSecrets ausente ou incorreto.
• O registro está inacessível devido a problemas de rede.
• A imagem foi excluída ou não existe no registro.

Como diagnosticar

1. Descreva o Pod

´´´bash
kubectl describe pod -n ​​
´´´

Verifique a seção Eventos em busca de erros como:

´´´txt
Failed to pull image
ImagePullBackOff
ErrImagePull
Unauthorized
Manifest unknown
´´´

2. Verifique o nome e a etiqueta da imagem.

Verifique se o nome da imagem, o repositório e a tag estão corretos.

Exemplo:

´´´txt
image: nginx:1.27
´´´

Um erro de digitação no nome ou na tag da imagem fará com que o download falhe.

3. Verifique ImagePullSecrets

´´´bash
kubectl get secret
´´´

Verifique se o Pod faz referência ao segredo correto:

´´´txt
imagePullSecrets:

• name: regcre
  ´´´

4. Validar credenciais de registro (repositório)

Verifique se as credenciais do registro Docker são válidas e não expiraram.

6. Testar a conectividade do registro

Verifique se o nó de trabalho consegue acessar o registro de contêineres.

Exemplos:

´´´bash
ping
curl https://
´´´

Como consertar

• Corrija o nome e o tag da imagem.
• Crie ou atualize o imagePullSecrets.
• Verifique se as credenciais do registro são válidas.
• Para registros privados, verifique a autenticação, o TLS e a conectividade de rede.
• Pré-carregue a imagem nos nós de trabalho, se necessário (para ambientes restritos).
• Envie a imagem novamente se ela tiver sido excluída ou estiver faltando.

ErrImagePull é a falha inicial ao extrair a imagem, enquanto ImagePullBackOff significa que o Kubernetes continua tentando novamente com atrasos crescentes até que a imagem possa ser extraída com sucesso.

Comandos importantes

´´´bash
kubectl describe pod
kubectl get secret
kubectl describe secret
´´´

Pontos chave

ErrImagePull é a falha inicial ao baixar a imagem, enquanto ImagePullBackOff significa que o Kubernetes continua tentando novamente, com intervalos crescentes, até que a imagem seja baixada com sucesso.