# ImagePullBackOff до старта GPU-процесса: образ, registry и Secret

Диагностика: ImagePullBackOff до старта GPU-процесса: образ, registry и Secret. Признаки, последовательность проверки, рабочий пример и критерии восстановления.

Автор: Команда Retrivium
Обновлено: 2026-11-01
Канонический URL: https://retrivium.ai/ru/journal/kubernetes-imagepullbackoff-registry-auth/
Language: ru

ImagePullBackOff возникает до запуска приложения: kubelet не может получить образ и повторяет попытки с backoff. Начните с Pod events, имени образа и registry credentials. Настройка CUDA или увеличение VRAM не исправляет недоступный image manifest.

## Найдите первую ошибку pull

Сохраните image reference из действующего Pod template, namespace, ServiceAccount и события. Последний статус BackOff часто скрывает первоначальный текст Failed pull: неверное имя, отсутствие доступа, проблема DNS или сертификата. Уточните, какой узел выполняет загрузку. Успешный docker pull на ноутбуке подтверждает только доступ из другой среды с другими credentials. Не копируйте полный auth config в отчёт: для расследования достаточно типа ошибки и имени используемого Secret.


[Официальный источник 1](https://kubernetes.io/docs/concepts/containers/images/).

## Проверьте область imagePullSecrets

Secret должен существовать в том namespace, где создан Pod, и содержать подходящие registry credentials. imagePullSecrets задаются на уровне Pod; их также можно прикреплять через ServiceAccount для новых Pod. Сопоставьте имя registry, включая путь к образу, с записью авторизации. FailedToRetrieveImagePullSecret указывает, что kubelet не смог получить указанный Secret. Такой случай отличается от корректно полученных, но отвергнутых registry credentials, поэтому действия должны сохранять эту границу.


[Официальный источник 2](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).

## Разберите две похожие ситуации

В учебном namespace inference Pod ссылается на regcred, который создан только в namespace tools. Исправление имени пользователя в самом Secret не поможет, пока ссылка недоступна в нужной области. Во втором случае Secret найден, но тег образа отсутствует в registry. Здесь требуется проверить публикацию и image reference. Имена namespace приведены для объяснения механизма, а не описывают существующий кластер или готовую инфраструктуру Retrivium.

| Признак события | Направление проверки |
| --- | --- |
| Secret не найден | Namespace и ссылка |
| Unauthorized | Credentials и registry scope |
| Manifest неизвестен | Репозиторий, тег или digest |
| TLS/DNS error | Сеть и доверие со стороны узла |

## Учтите pull policy

Сохраните imagePullPolicy и фактический digest доступного образа. Политика задаётся при создании объекта и не обязана автоматически меняться вслед за заменой тега. Кешированный образ на одном узле может скрыть проблему, которая проявится на новом узле без кеша. Проверяйте исправление там, где pull действительно выполняется. Не удаляйте все локальные образы ради диагностики без понимания влияния на соседние workload и возможности повторной загрузки.

## Подтвердите запуск нового экземпляра

После исправления дождитесь успешного pull и создания контейнера, затем отдельно проверьте старт приложения. Исчезновение ImagePullBackOff не подтверждает работоспособность GPU или готовность модели. Сохраните имя образа, digest, namespace, источник credentials без значения и ключевые события до/после. При следующем rollout этот артефакт поможет отличить повторный отказ registry от ошибки уже запущенного процесса. Длинный backoff не означает, что Kubernetes прекратил попытки; учитывайте расписание повторов при наблюдении результата.

Связанные разборы: [vllm docker first launch](/ru/journal/vllm-docker-first-launch/); [software stack reproducibility](/ru/journal/software-stack-reproducibility/).