ImagePullBackOff: проверяем имя образа, доступ к registry и imagePullSecrets

Новый релиз уже появился в Deployment, но контейнер не начал работу. В списке Pod написано ImagePullBackOff. Здесь ещё рано смотреть журнал приложения: процесс из образа не запущен. Kubernetes пытался скачать образ, получил ошибку и увеличивает паузу между попытками. Чтобы исправить причину, нужен текст последней попытки, а не только её короткий статус.

Находим исходную ошибку загрузки

kubectl -n demo describe pod api-7d9b8f-demo
kubectl -n demo get pod api-7d9b8f-demo -o yaml

В Events найдите Failed с подробным сообщением. Manifest unknown или not found направляют к имени репозитория и версии; unauthorized и denied — к аутентификации и правам; timeout — к доступности адреса; x509 — к доверию сертификату или имени сервера. Формулировки различаются у container runtime и registry, поэтому сохраните полное сообщение. Back-off pulling image описывает паузу, а не первопричину.

Из YAML выпишите полный image именно проблемного контейнера, включая registry, путь, tag либо digest. Проверьте также initContainers: загрузка основного приложения может даже не начаться, пока недоступен подготовительный образ. Сравнивать нужно с фактически созданным Pod. Ошибка в шаблоне Deployment могла быть исправлена, а старый Pod всё ещё сохраняет предыдущую спецификацию.

Правильное имя ещё не даёт права на скачивание

Путь registry.example.com/team/api:2026-10-29 и team/api:2026-10-29 ведёт к разным местам: без адреса registry используется стандартный реестр. При ручной проверке с ноутбука успешный docker pull подтверждает доступ ноутбука и его учётных данных. Образ в Kubernetes скачивает runtime на узле. Его сеть, доверенные центры сертификации и способы получения credentials могут отличаться.

Для обычного приватного registry Pod ссылается на Secret через imagePullSecrets. Секрет должен находиться в том же namespace. Имя произвольно, содержимое должно подходить нужному адресу registry, а токен — иметь право чтения выбранного репозитория. Проверять только существование Secret недостаточно, однако печатать его данные в общий журнал расследования тоже не нужно.

kubectl -n demo get secret registry-pull -o jsonpath="{.type}"
kubectl -n demo get serviceaccount default -o yaml

Для распространённого формата ожидается kubernetes.io/dockerconfigjson. Если Secret добавлен в ServiceAccount после создания Pod, уже существующий Pod не получает автоматически новую ссылку в своей спецификации. Проверьте imagePullSecrets самого Pod и пересоздавайте его через управляющий workload после исправления шаблона или ServiceAccount. Не изменяйте ServiceAccount вслепую: им могут пользоваться другие приложения.

Минимальная связь Pod с секретом

Следующий манифест показывает место поля. Образ registry.example.com — явный заполнитель: перед применением нужен ваш опубликованный образ, а в demo уже должен существовать registry-pull. В Deployment поле располагается под spec.template.spec.

apiVersion: v1
kind: Pod
metadata:
  name: private-image-check
  namespace: demo
spec:
  imagePullSecrets:
    - name: registry-pull
  containers:
    - name: api
      image: registry.example.com/team/api:2026-10-29

Секрет можно создать из отдельного подготовленного Docker config, содержащего только нужную запись. Команда ниже читает локальный файл; его нужно заранее получить разрешённым способом и не сохранять в Git. Конфигурация Docker с credHelpers или credsStore может ссылаться на внешний credential helper вместо хранения самих данных, поэтому её нельзя считать готовым переносимым секретом без проверки формата.

kubectl -n demo create secret generic registry-pull --from-file=.dockerconfigjson=./registry-config.json --type=kubernetes.io/dockerconfigjson

Если Secret с таким именем уже существует, create завершится ошибкой. Обновление действующего секрета оформляйте через принятый в проекте способ управления секретами, сохраняя возможность ротации. Не передавайте пароль прямо в аргументах shell ради быстрого эксперимента: он может попасть в историю и список процессов. Адрес registry и набор прав проверяйте у владельца хранилища.

Проверяем результат по новым событиям

После исправления дождитесь следующей попытки или запустите новый Pod контролируемым развёртыванием. Успех загрузки виден по Pulled, затем Created и Started. Если ошибка сменилась с unauthorized на x509, вы устранили только первый барьер. Для TLS требуется корректная цепочка и доверие на узлах; отключение проверки сертификата создаёт другую проблему и не исправляет конфигурацию доверия.

Проверьте, на каких узлах повторяется ошибка. Если один и тот же образ загружается на части worker, а на одном постоянно возникает timeout или x509, это аргумент исследовать сетевой выход и доверие именно этого узла. Если все новые Pod получают denied, вероятнее общая проблема credentials или прав репозитория. Локальный кэш образа способен скрывать ошибку доступа на давно работающих узлах, поэтому факт успешного старта старой реплики ещё не подтверждает текущий pull-доступ.

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

Наконец, проверьте Ready приложения. Успешное скачивание доказывает доступность артефакта, но старт может остановиться на конфигурации или миграции. Для облачного registry дополнительно учитывайте принятый в кластере механизм выдачи credentials узлам. Итог расследования должен связывать исходное сообщение с исправленным именем, правом или сетевым условием.

Ещё по теме

• DNS в Kubernetes отвечает медленно: проверяем CoreDNS, search и ndots
• Forbidden в Kubernetes: проверяем ServiceAccount, Role и RoleBinding

Продолжить изучение

Хотите увереннее разворачивать приложения и разбирать сбои в кластере? Сети, конфигурация, хранилища и обновления входят в программу «Kubernetes с нуля до PRO».