Как устранить ImagePullBackOff в Kubernetes

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

• Как работает загрузка образов
• Проверка базовых вещей
• Управление входом в реестр
• Ограничения скорости реестра
• Чеклист и план действий

Что такое ImagePullBackOff

ImagePullBackOff — это состояние Pod в Kubernetes, означающее, что Kubelet на узле несколько раз не смог загрузить указанный образ и теперь ждёт перед новой попыткой. Это сигнал о том, что загрузка образа не удалась повторно; контейнер при этом не запускается, пока образ не станет доступен.

Определение термина: ImagePullBackOff — кратко, состояние ожидания повтора после нескольких неудачных попыток загрузки образа.

Важно: ImagePullBackOff не обязательно означает, что реестр недоступен — это общее состояние, которое охватывает ошибки пути, теги, аутентификацию, сетевые проблемы и лимиты скорости.

Как работает загрузка образов

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

Повторные попытки: если загрузка не удалась (ошибочный путь, отказ аутентификации или сетевая проблема), Kubelet будет повторять попытки с экспоненциальной задержкой, увеличивая интервал между попытками до предела (обычно до ~5 минут). Пока не закончится блокировка, Pod остаётся в ImagePullBackOff.

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

Проверка базовых вещей

1. Проверка имени образа и тега

• Убедитесь, что image и tag в манифесте написаны без опечаток.
• Полный формат: [registry/][namespace/]image[:tag]
• Если tag опущен, по умолчанию используется latest — иногда это нежелательно.

2. Просмотр состояния Pod и событий

Используйте kubectl describe для подробной информации (он показывает события и сообщения ошибок):

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

В разделе Events вы увидите последовательность: Scheduled → Pulling → Failed / BackOff. Читайте поле Message для деталей.

Примеры сообщений и что они обычно означают:

• manifest for image:tag not found — образ существует, но указан неверный тег.
• does not exist or no pull access — либо образ/путь неверны, либо нет доступа (аутентификация/разрешения).
• unauthorized: authentication required — проблема с учётными данными.
• denied: requested access to the resource is denied — права доступа или политика реестра.

3. Попытка локальной загрузки

Проверьте с вашей рабочей станции или VM:

docker pull registry.example.com/my-image:tag
# или
podman pull registry.example.com/my-image:tag

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

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

Чтобы Kubelet мог получить доступ к приватным реестрам, нужно создать Kubernetes Secret с Docker-конфигурацией и сослаться на него в манифесте Pod через imagePullSecrets.

Пример безопасного способа создать секрет через kubectl (рекомендуется):

kubectl create secret docker-registry image-pull-secret \
  --docker-server=registry.example.com \
  --docker-username=demo-user \
  --docker-password='my-password-or-token' \
  --docker-email=me@example.com \
  --namespace my-namespace

Полный пример манифеста Secret и Pod (YAML):

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

Пояснения:

• .dockerconfigjson должен содержать валидный Docker JSON в Base64.
• Пароль часто заменяют на token/API key. На Docker Hub с включённой 2FA — нужно использовать access token.
• Альтернативно можно использовать secret типа kubernetes.io/basic-auth для некоторых реестров, но стандартной практикой остаётся dockerconfigjson.

Проверка привязки:

kubectl get secret image-pull-secret -n my-namespace -o yaml
kubectl get pod my-pod -n my-namespace -o yaml | grep imagePullSecrets -A 3

Если узлы используют приватные блоки сети, убедитесь, что kubelet может разрешать DNS и обращаться по HTTPS к реестру.

Ограничения скорости реестра и их влияние

Если URL, тег и учётные данные в порядке, причиной могут быть лимиты скорости реестра. Пример: Docker Hub ограничивает количество бесплатных неаутентифицированных pull-запросов за период (значения и политика Docker Hub опубликованы компанией Docker). В активных кластерах это ограничение легко исчерпывается.

Как это проявляется: сообщение об ошибке выглядит похоже на ошибку аутентификации или отказ в доступе — однотипные симптомы, но корень в лимите.

Короткие стратегии смягчения:

• Временная мера: дождаться окончания периода и перезапустить Pod.
• Долговременная: настроить локальный pull-through cache или внутренний реестр (Harbor, Artifactory, Azure ACR/GCP Artifact Registry/ECR), чтобы снизить количество внешних обращений.
• Предварительное протягивание образов на узлы (pre-pull) через DaemonSet или init-скрипты.
• Использовать imagePullPolicy: IfNotPresent для уменьшения частоты повторных загрузок при частых перезапусках.

Чеклист — быстрый план действий при ImagePullBackOff

1. kubectl describe pod -n — прочитать Events и Message.
2. kubectl get pod -o yaml — проверить image и imagePullSecrets.
3. docker pull с вашей машины — проверить доступность реестра и тег.
4. Проверить секреты: kubectl get secret -n -o yaml.
5. Проверить network policy / firewall / DNS на узлах.
6. Проверить лимиты реестра и логи доступа реестра.
7. Если приватный реестр — подтвердить, что token действителен.
8. При необходимости включить кэш/прокси или переместить образы в внутренний реестр.

Playbook для инженера (SRE / Platform)

Шаг 1 — мгновенные проверки (5–15 минут):

• Откройте Events через kubectl describe.
• Выполните docker pull локально.
• Проверяйте .dockerconfigjson у secret.

Шаг 2 — среднесрочные (15–60 минут):

• Проверить сетевые пути от узлов к реестру (telnet/ curl на порт 443, DNS resolution).
• Посмотреть логи kubelet на проблемных узлах.
• Переместить образ в internal registry (временно) и изменить манифест.

Шаг 3 — устойчивое решение (1 день+):

• Настроить pull-through cache или internal registry.
• Автоматизировать обновление imagePullSecrets с системой управления секретами.
• Добавить мониторинг метрик pull-ошибок и алертинг.

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

• Pod запускается успешно и остаётся в состоянии Running.
• Количество ошибок ImagePullBackOff уменьшено до 0 для одного выпуска.
• Метрики доступа к реестру в норме (меньше, чем лимит для выбранного плана).

Роли и обязанности (кто что делает)

• Разработчик: проверить image и tag, убедиться, что CI пушит образ в правильный репозиторий.
• SRE/Оператор кластера: проверить сеть, kubelet, secrets, и применить временные исправления.
• Платформенная команда: организовать внутренний реестр/кэш и контролировать лимиты и учётные данные.

Ментальные модели и когда это не сработает

Модель 1 — «Путь → Доступ → Лимиты»: сначала проверьте путь и тег, затем права доступа, затем внешние лимиты.

Когда эта методика может не сработать:

• Если узел изолирован сетевым правилом (NetworkPolicy/Firewall на уровне хоста), локальный docker pull может работать, а узлы кластера — нет.
• Если реестр возвращает неполные/ошибочные manifest’ы (коррумпированные индексы), простая проверка пути не выявит проблему — потребуется диагностика реестра.

Быстрые подсказки и конфигурации

• Используйте imagePullPolicy: IfNotPresent чтобы снизить частоту загрузок для неизменяемых тегов.
• Для критичных сервисов храните образы в приватном internal registry с репликацией.
• Для CI/CD: помечайте сборки уникальными immutable-тегами (semver + build id) и не полагайтесь на latest.

Короткое руководство по безопасности и конфиденциальности

• Не храните пароли в открытых репозиториях. Используйте менеджеры секретов (Vault, SealedSecrets, External Secrets).
• Ограничьте доступ к реестру по IP или через VPN, если возможно.
• Регулярно ротацируйте сервисные токены и используйте минимальные права доступа.

Итог — что делать прямо сейчас

1. Выполните kubectl describe и прочитайте Message в Events.
2. Проверяйте путь и тег образа — исправьте опечатки.
3. Настройте imagePullSecrets или обновите токен.
4. Если причина — лимит реестра, настройте кэш или внутренний реестр.

Важно: если вы видите ImagePullBackOff после единственной попытки — проверьте сеть и логи kubelet; если проблема повторяется — следуйте чеклисту выше.

Краткое резюме

• ImagePullBackOff — это показатель проблемы с загрузкой образа: путь, аутентификация, сеть или лимиты.
• kubectl describe даёт первичную телеметрию; docker pull помогает локальной проверке.
• Секреты dockerconfigjson и imagePullSecrets — стандарт для приватных реестров.
• Для долгосрочной стабильности рекомендуется внутренний реестр или pull-through cache.

Последующие шаги: примените чеклист, настройте мониторинг и автоматизацию ротации токенов для снижения риска повторения.