Kubectl ImagePullBackOff: причины и решение ошибки Kubernetes

Что означает ошибка ImagePullBackOff

Ошибка ImagePullBackOff — это состояние Kubernetes-пода, указывающее, что kubelet (агент на ноде) не смог загрузить контейнерный образ из указанного репозитория. После серии неудачных попыток kubelet входит в режим BackOff, задерживая последующие попытки, чтобы избежать бесконечных запросов и перегрузки сети.

В выводе kubectl get pods вы увидите статус ImagePullBackOff или ErrImagePull. Полное сообщение в событиях (Events) обычно содержит детали: Failed to pull image, Image not found, unauthorized: authentication required или dial tcp timeout.

Эта проблема возникает на этапе создания контейнера и предотвращает переход пода в состояние Running.

Причины возникновения

1. Некорректное имя образа — опечатка в названии репозитория, образа или тега (например, docker.io/library/nginx:lates вместо latest).
2. Образ не существует — указанный тег или дайджест образа отсутствуют в репозитории (удалён или никогда не существовал).
3. Проблемы с доступом к репозиторию — сетевая недоступность Docker Hub или приватного registry, firewall блокирует порт 443/80, DNS-проблемы.
4. Отсутствие или неверные секреты — для приватного репозитория не указан imagePullSecrets или секрет содержит неверные credentials.
5. Недостаток дискового пространства на ноде — kubelet не может сохранить временные слои образа.
6. Несовместимость архитектуры — образ собран для другой архитектуры (например, linux/arm64), чем у ноды (linux/amd64).
7. Ограничения registry — превышен лимит запросов (rate limit) на Docker Hub для анонимных запросов.

Способ 1: Проверьте и исправьте имя образа

Чаще всего проблема — в опечатке. Убедитесь, что в манифесте пода или deployment указано полное и корректное имя образа.

1. Посмотрите события пода:

   kubectl describe pod <имя_пода> | grep -A 5 Events
   

   
   Обратите внимание на строки Failed и ErrImagePull.
2. Проверьте поле Image в спецификации:

   kubectl get pod <имя_пода> -o jsonpath='{.spec.containers[0].image}'
   

3. Если имя неверное, исправьте манифест (deployment, pod, statefulset) и примените заново:

   kubectl edit deployment <имя_deployment>
   

   
   или

   kubectl apply -f исправленный_манифест.yaml
   

💡 Совет: Используйте полные имена образов с реестром, например docker.io/library/nginx:1.25 вместо nginx:latest, чтобы избежать неоднозначностей.

Способ 2: Проверьте доступность образа в репозитории

Убедитесь, что образ действительно существует и доступен для загрузки.

1. Попробуйте загрузить образ с любой ноды кластера (или локально, если используете Docker):

   docker pull <образ>
   

   
   Если используете containerd:

   ctr image pull <образ>
   

2. Если образ приватный, убедитесь, что вы аутентифицированы:

   docker login <registry>
   

   
   Для containerd настройте credentials в /etc/containerd/config.toml.
3. Если образ отсутствует, найдите правильный тег или дайджест в репозитории и обновите манифест.

Способ 3: Настройте imagePullSecrets для приватных репозиториев

Если образ находится в приватном registry, Kubernetes должен иметь права на его загрузку.

1. Создайте секрет Docker registry (если ещё нет):

   kubectl create secret docker-registry regcred \
     --docker-server=<registry_url> \
     --docker-username=<username> \
     --docker-password=<password>
   

2. Добавьте секрет в сервис-аккаунт, используемый подом (по умолчанию default):

   kubectl patch serviceaccount default \
     -p '{"imagePullSecrets": [{"name": "regcred"}]}'
   

   
   Или укажите напрямую в спецификации пода/deployment:

   spec:
     containers:
     - name: myapp
       image: myregistry/myapp:latest
     imagePullSecrets:
     - name: regcred
   

3. Проверьте, что секрет применился:

   kubectl get pod <имя_пода> -o yaml | grep imagePullSecrets
   

Способ 4: Проверьте ресурсы и сеть ноды

Иногда проблема не в образе, а в среде выполнения.

1. Дисковое пространство: подключитесь к ноде, где запускается под, и проверьте свободное место:

   df -h
   

   
   Если место заканчивается, очистите неиспользуемые образы:

   docker system prune -a
   

   
   или для containerd:

   ctr image prune
   

2. Сеть и DNS: проверьте доступность registry с ноды:

   ping <registry_url>
   curl -v https://<registry_url>/v2/_catalog
   

   
   Убедитесь, что нет блокировки firewall.
3. Архитектура: если нода имеет архитектуру, отличную от образа (например, ARM), потребуется образ для нужной архитектуры. Проверьте архитектуру ноды:

   kubectl get node <имя_ноды> -o jsonpath='{.status.nodeInfo.architecture}'
   

   
   И найдите образ с соответствующей платформой в теге (например, nginx:1.25-alpine-arm64).

Способ 5: Анализ логов kubelet и событий

Если предыдущие шаги не дали результата, углубитесь в логи компонентов.

1. Получите расширенные события пода с фильтрацией:

   kubectl get events --field-selector involvedObject.name=<имя_пода> --sort-by='.lastTimestamp'
   

2. Найдите ноду, на которой планируется запуск пода:

   kubectl get pod <имя_пода> -o wide
   

3. Подключитесь к этой ноде и просмотрите логи kubelet:

   journalctl -u kubelet -f --no-pager
   

   
   Ищите строки, содержащие Failed to pull image или ImagePullBackOff. Там может быть указана более точная причина (например, x509: certificate signed by unknown authority для самоподписанных сертификатов).
4. Если используется самоподписанный registry, добавьте его сертификат в доверенные на всех нодах кластера.

Профилактика

• Всегда указывайте явный тег или дайджест образа вместо latest в production-манифестах.
• Проверяйте образы перед деплоем: запускайте docker pull на тестовой ноде.
• Управляйте секретами централизованно: используйте инструменты вроде External Secrets или HashiCorp Vault для автоматического создания imagePullSecrets.
• Мониторьте свободное место на нодах и настройте автоматическую очистку неиспользуемых образов (например, через kubelet параметр --image-gc-high-threshold).
• Используйте private registry с аутентификацией по умолчанию, а не анонимный доступ.
• Тестируйте образы на всех целевых архитектурах при использовании мульти-платформенных нод.