Aller au contenu

Runbook : ImagePullBackOff

Alerte : ImagePullBackOff (PrometheusRule, severity critical)

Symptôme :

Le pod <pod> n'arrive pas à télécharger l'image <image> depuis Harbor ou un registry externe.

Severity : 🔴 critical — notif Slack #akko-critical, répétition 30 min

Diagnostic

1. Identifier l'image qui échoue

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl describe pod -n akko <pod> | grep -A3 "Failed to pull"

2. Vérifier les events (détail de l'erreur)

kubectl get events -n akko --sort-by='.lastTimestamp' | grep -i "pull" | tail -10

3. Tester le pull manuellement depuis un worker

ssh root@<node> 'crictl pull <image>'
# ou sur un k3s avec containerd :
ssh root@<node> 'ctr -n k8s.io images pull <image>'

Causes fréquentes + correctif

Cause Symptôme (events) Correctif
Image inexistante manifest unknown Vérifier le tag dans helm/akko/values.yaml vs Harbor UI. Rebuild + push via CI.
Tag :latest mutable Pull OK hier, échec aujourd'hui R08 violée — épingler à YYYY.MM. Correctif : values.yaml + commit.
Auth Harbor expirée 401 Unauthorized Vérifier imagePullSecrets (kubectl get secret harbor-creds -n akko). Recréer si expiré.
Rate limit Docker Hub toomanyrequests Éviter Docker Hub — mirror via Harbor (voir harbor.fr.md).
NetworkPolicy bloque Harbor connection refused vers l'IP Harbor Vérifier la NetworkPolicy autorise l'egress sur port 30500.
DNS interne cassé no such host kubectl get svc -n harbor + test nslookup depuis un pod.

Correctif pérenne (R02 : zero workaround)

Jamais : kubectl edit deployment pour changer l'image à chaud.

Toujours : 1. Éditer helm/akko/values.yaml ou values-netcup.yaml avec le bon tag 2. Commit + push 3. La CI rebuild + deploy 4. Vérifier que le pod est Running

Si l'image doit être rebuild : 1. Éditer le Dockerfile dans docker/<image>/ 2. Commit + push — le workflow deploy-netcup.yml détecte les paths docker/** et relance le build

Prévention

  • Tag pinning (R08) : tous les tags doivent être YYYY.MM — jamais :latest. Linter CI : grep -rn ':latest' helm/ docker/ | grep -v example
  • Politique de rétention Harbor : configurer la rétention 90 jours + les 5 derniers tags pour éviter les purges accidentelles.
  • Registry de secours : prévoir un mirror Harbor pour les images upstream (postgres, python, jupyter) si Docker Hub pose problème.

Lessons learned

  • L08 — Tout tag :latest finit par casser. La règle R08 est stricte, zéro tolérance.

Liens utiles