Error: ErrImagePull
Kubelet-ul nu a putut descărca imaginea containerului. Motivul exact e în evenimentele podului (kubectl describe pod): tag inexistent (not found), nume greșit sau registry privat (pull access denied, 401 Unauthorized). Corectează imaginea sau datele de acces; după câteva încercări statusul devine ImagePullBackOff.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Înainte să pornească un container, kubelet-ul de pe nod descarcă imaginea din registry (prin containerd). ErrImagePull e statusul afișat imediat după o încercare eșuată, iar Error: ErrImagePull apare în evenimente. Kubelet-ul reîncearcă, cu pauze tot mai mari, iar între încercări statusul este ImagePullBackOff.
Statusul în sine nu spune cauza. Ea e în evenimentul Failed de dinaintea lui, din kubectl describe pod: not found (tag sau imagine inexistentă), pull access denied (repository inexistent sau privat), 401 Unauthorized (lipsesc datele de acces), no such host sau i/o timeout (registry inaccesibil din nod).
La un Deployment, rolling update-ul păstrează podurile vechi în funcțiune cât timp cele noi nu pornesc, deci aplicația nu cade, dar actualizarea rămâne blocată.
De ce apare: cauzele frecvente
1Tag greșit
kubectl set image deploy/clinica nginx=nginx:1.72kubectl set image deploy/clinica nginx=nginx:1.271.72 nu există în registry, deci descărcarea eșuează mereu.
2Nume de imagine scris greșit
image: ngnix:1.27image: nginx:1.27Un repository inexistent dă pull access denied.
3Registry privat fără date de acces
image: registry.academia.ro/magazin-privat:1.0kubectl create secret docker-registry regcred ...
# imagePullSecrets: [{name: regcred}]Registry-ul cere autentificare; kubelet-ul o primește din imagePullSecrets.
Repară eroarea, direct în pagină
După o actualizare grăbită, Deploymentul clinica (site-ul unei clinici stomatologice) are poduri noi în ErrImagePull. Citește evenimentele unui pod nou ca să vezi imaginea încercată, corectează tag-ul la nginx:1.27 și verifică faptul că actualizarea se încheie.
Indiciu
În evenimentele podului, linia Failed to pull image arată imaginea exactă.
Reparația
Starea și motivul:
kubectl get pods -l app=clinica
kubectl describe pod -l app=clinica | grep 'Failed to pull' | tail -1NAME READY STATUS RESTARTS AGE
clinica-2z2qdzmqwr-pz5gq 0/1 ErrImagePull 0 13s
clinica-ctnghhwjl6-76qql 1/1 Running 0 32s
clinica-ctnghhwjl6-g2q47 1/1 Running 0 32s
Warning Failed 2s (x2 over 13s) kubelet Failed to pull image "nginx:1.72": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:1.72": failed to resolve reference "docker.io/library/nginx:1.72": docker.io/library/nginx:1.72: not foundTag-ul corect:
kubectl set image deployment/clinica nginx=nginx:1.27
kubectl rollout status deployment/clinicadeployment.apps/clinica image updated
deployment "clinica" successfully rolled outDe ce merge
ErrImagePull doar anunță că descărcarea a eșuat. Evenimentul Failed spune de ce: tag-ul 1.72 nu există. Podurile vechi au rămas în funcțiune, pentru că rolling update-ul nu le oprește până nu sunt gata cele noi. Cu tag-ul corect, Deploymentul creează o revizie nouă și termină actualizarea.
Alte forme ale mesajului
Error: ImagePullBackOffFailed to pull image "nginx:1.72": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:1.72": ...
Cum o eviți pe viitor
- Folosește tag-uri exacte, verificate (
nginx:1.27), nulatestși nu tag-uri scrise din memorie. - Verifică existența tag-ului înainte de livrare (
docker pullsau pagina registry-ului). - Pentru registry-uri private, pune
imagePullSecretsîn șablon sau pe ServiceAccount. - Urmărește livrarea cu
kubectl rollout status, ca să vezi imediat dacă podurile noi nu pornesc.
Întrebări frecvente
Care e diferența dintre ErrImagePull și ImagePullBackOff?
ErrImagePull e starea imediat după o încercare eșuată. ImagePullBackOff e pauza dintre încercări, care crește până la 5 minute. Cauza e aceeași.
Se rezolvă singur?
Doar dacă problema era temporară (rețea, registry căzut). Un tag inexistent nu apare niciodată, deci trebuie corectată imaginea.
Erori înrudite
Back-off pulling image "academia/magazin:v4" Kubelet-ul a încercat de mai multe ori să descarce imaginea, a eșuat și acum așteaptă înainte de încercarea următoare (ImagePullBackOff). Caută în evenimente motivul primei erori (not found, pull access denied, 401) și corectează imaginea; nu ajută să aștepți. Failed to pull image "nginx:1.99": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:1.99": failed to resolve reference "docker.io/library/nginx:1.99": docker.io/library/nginx:1.99: not found Repository-ul există, dar tag-ul cerut nu (aici nginx:1.99). Verifică tag-urile disponibile în registry și scrie unul real, de exemplu nginx:1.27; după corectare podurile pornesc. Failed to pull image "academia/magazn:v1": failed to pull and unpack image "docker.io/academia/magazn:v1": failed to resolve reference "docker.io/academia/magazn:v1": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed Registry-ul nu găsește repository-ul imaginii sau nu îți permite accesul: numele e scris greșit, majuscule în nume, ori imaginea e privată. Verifică numele complet (registry/organizație/imagine) și, pentru imagini private, adaugă imagePullSecrets. Învață Kubernetes de la zero, cu exerciții la fiecare lecție
Curs Kubernetes: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 12 lecții sunt gratuite.
