ImagePullBackOff в Kubernetes: причины и решение

Иллюстрация с логотипом Kubernetes

Быстрые ссылки

How Image Pulls Work
Check The Basics
Managing Registry Logins
Registry Rate Limits
Summary

Как работают загрузки образов

Kubernetes скачивает образ, когда вы создаёте новый деплоймент или обновляете существующий, изменив ссылку на тег образа. Загрузкой управляет процесс Kubelet на каждом рабочем узле. Каждый образ, указанный в манифесте Pod, должен быть доступен всем узлам кластера, чтобы любой из них мог запланировать контейнер.

Ошибка загрузки может произойти из‑за неправильного пути к образу, проблем с аутентификацией или сетевых ошибок. При неудаче Kubernetes откладывает следующую попытку загрузки. Интервал между попытками увеличивается экспоненциально до максимума в пять минут.

Когда Pod находится в состоянии ImagePullBackOff, это означает, что было несколько последовательных неудачных попыток загрузки и Kubernetes ожидает перед новой попыткой. Контейнер не стартует, пока образ не станет доступен.

Вы можете оставить Pod в этом состоянии, если причина временная (сеть, удалённый реестр). Kubernetes автоматически повторит попытки. Если ошибка не временная, приступайте к отладке с приведённых ниже шагов.

Проверка основ

Сначала проверьте очевидное. Ссылка на образ в манифесте действительно существует? Нет ли опечаток в пути реестра или теге образа?

Используйте команду describe, чтобы получить подробную информацию о состоянии Pod:

kubectl describe pod my-pod --namespace my-namespace

Эта команда даёт больше данных, чем kubectl get pod. В разделе Events отображается последовательность событий жизненного цикла Pod. Первое событие — Scheduled; далее должно идти Pulling при первой попытке загрузки. Если загрузка не удалась, вы увидите Failed или BackOff. Если Kubernetes продолжает повторять попытки, эти события будут повторяться.

Скриншот события ImagePullBackOff в Kubernetes

Читайте поле Message у событий — оно часто раскрывает корень проблемы. Примеры типичных сообщений:

manifest for image:tag not found — образ существует, но указан несуществующий тег.
does not exist or no pull access — либо образ не найден, либо у узла нет доступа к реестру (аутентификация).

Если путь и тег корректны, вероятно проблема в аутентификации.

Управление входом в реестр

Для приватных образов нужно, чтобы узел был залогинен в реестр. В Kubernetes это делается через секреты, которые затем указываются в Pod манифесте.

Поле Pod называется imagePullSecrets. Оно должно ссылаться на Kubernetes Secret с Docker‑совместимыми данными конфигурации.

Пример корректного YAML для секрета и Pod:

apiVersion: v1
kind: Secret
metadata:
  name: image-pull-secret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: eyJhdXRocyI6eyJyZWdpc3RyeS5leGFtcGxlLmNvbSI6eyJ1c2VybmFtZSI6ImRlbW8tdXNlciIsInBhc3N3b3JkIjoibXktcGFzc3dvcmQifX19
---
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - name: my-container
    image: registry.example.com/my-image:latest
  imagePullSecrets:
  - name: image-pull-secret

В этом примере .dockerconfigjson содержит Base64‑версию Docker JSON с учётными данными для registry.example.com. Kubelet на узлах использует этот фрагмент как часть config.json, когда пытается загрузить образ.

Тип используемых учётных данных зависит от реестра. Часто поле password фактически хранит персональный токен доступа или API‑ключ. Для Docker Hub с включённой двухфакторной аутентификацией требуется access token, сгенерированный в настройках аккаунта.

Важно: храните секреты безопасно и ограничивайте доступ через RBAC.

Ограничения частоты запросов реестра

Даже при корректном пути и аутентификации вы можете столкнуться с лимитами реестра. Docker Hub ограничивает использование публичных образов: 100 pull‑запросов каждые 6 часов для анонимных клиентов и 200 pull‑запросов каждые 6 часов при наличии учётных данных.

В активном кластере с частыми деплойментами этот лимит легко превысить. Ошибки из‑за лимитов выглядят похоже на проблемы с аутентификацией. Нужно дождаться, когда пройдёт отсчёт лимита, и затем Kubernetes сможет загрузить образ.

Долгосрочные способы снизить риск превышения лимитов:

Развёртывание в кластере внутреннего регистра (registry mirror) для кэширования образов.
Проксирование через локальный кэш (например, registry‑mirror, Artifactory, Harbor).
Использование частных реестров облачных провайдеров (ECR/GCR/ACR) с более лояльными лимитами.

Пошаговый плейбук для устранения ImagePullBackOff

Ниже — практическая последовательность действий. Пройдите шаги по порядку, пока причина не станет ясна.

Сбор первичных данных
- Выполните kubectl describe pod и сохраните Events и Message.
- Посмотрите kubectl get pods -o wide для состояния узлов.
- Попробуйте kubectl logs для других контейнеров в Pod, если они есть.
Проверка манифеста
- Сверьте образ и тег с реестром.
- Убедитесь, что нет лишних пробелов и опечаток.
Локальная проверка доступа
- На машине с доступом к интернету выполните docker pull registry.example.com/my-image:tag.
- Если локально pull проходит, вероятнее всего, проблема на стороне кластера (сеть, DNS, NAT).
Проверка учётных данных
- Если сообщение указывает на отказ в доступе, проверьте Secret и формат .dockerconfigjson.
- Убедитесь, что Secret применён в том Namespace, где запускается Pod.
- Выполните kubectl get secret image-pull-secret -o yaml и проверьте наличие данных.
Сетевая диагностика на узлах
- Подключитесь к узлу и выполните curl/ping к реестру.
- Проверьте ограничение egress/нат и proxy.
Проверка лимитов реестра
- Если есть вероятность превышения лимита pull, проверьте логи реестра или политику провайдера.
- Подумайте о локальном кэше образов.
Повторный запуск
- После исправления запроса удалите Pod или пересоздайте контроллер: kubectl delete pod my-pod — контроллер пересоздаст его с корректными параметрами.

Важно: фиксируйте и автоматизируйте успешный путь восстановления, чтобы сократить время отклика в будущем.

Decision tree для быстрого решения

flowchart TD
  A[Pod в ImagePullBackOff] --> B{Сообщение в Events}
  B -->|manifest not found| C[Проверьте тег и путь]
  B -->|no pull access| D[Проверьте секреты и права]
  B -->|rate limit| E[Проверьте лимиты реестра и кэш]
  B -->|network error| F[Проверьте сеть и DNS на узлах]
  C --> G[Исправьте манифест и перезапустите]
  D --> H[Переcоздайте/обновите Secret и перезапустите]
  E --> I[Настройте внутренний реестр или proxy]
  F --> J[Диагностика узлов и NAT]

Чек-листы по ролям

Разделите действие между командами — это ускорит восстановление.

DevOps инженер

Проверить kubectl describe pod и события.
Проверить Secret в Namespace.
Попытаться локально pull образа.
Перезапустить Pod.

Разработчик образа

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

Платформенный инженер

Проверить сетевые правила, прокси и NAT на узлах.
Настроить registry mirror или internal registry.
Следить за лимитами и рекомендациями провайдера.

Критерии приёмки

Чтобы считать проблему решённой, подтвердите:

Pod переходит в состояние Running и остаётся стабильным в течение минимум одного полного периода health‑check в приложении.
kubectl describe pod больше не показывает события Failed/BackOff, связанных с image pull.
Если были изменения в секретах или реестре, они задокументированы и добавлены в систему управления конфигурацией.

Фактбокс — ключевые числа и поведение

Максимальная задержка между попытками pull: до 5 минут.
Docker Hub: 100 pull каждые 6 часов для анонимных, 200 pull каждые 6 часов с учётными данными.
Тип секрета для Docker: kubernetes.io/dockerconfigjson.

Частые варианты, когда методы не помогают

Образы хранятся в приватном реестре за корпоративным firewall — нужна настройка egress и прокси.
Узлы используют нестандартные CA — Kubelet не доверяет TLS реестра.
Реестр возвращает специфичные ошибки (например, 429) — требуется оперативное взаимодействие с провайдером.

Глоссарий

Kubelet: агент Kubernetes на каждом узле, отвечающий за запуск контейнеров.
Pod: минимальная исполняемая единица в Kubernetes, содержащая один или несколько контейнеров.
imagePullSecrets: ссылка в Pod на секрет с учётными данными для реестра.

Итог

ImagePullBackOff — симптом проблемы с доступностью образа, аутентификацией или лимитами реестра. Начинайте с чтения событий через kubectl describe, проверяйте путь и тег образа, затем учётные данные и сетевую доступность. Если проблема системная (лимиты или сеть), решите её на уровне платформы: внутренний реестр или прокси обычно помогают навсегда снизить частоту сбоев.

Summary: Kubelet повторяет попытки pull с экспоненциальным backoff. Быстрая проверка манифеста, секретов и сети решает большинство случаев. Для производства рекомендуем встроенный кэш образов.