Skip to content
Back to the playbook

Fixing ImagePullBackOff caused by private-registry credentials

Kuberneteskubectlrevision 1

Diagnostic tree

  1. In progressPod stuck in ImagePullBackOff pulling from a private registryA working `docker pull` of the same image on a developer's laptop is a red herring for this branch of the problem — it only proves the registry credentials are valid somewhere, not that the pod has them. Kubelet pulls images using the pod's own imagePullSecrets (or its ServiceAccount's), which is a completely separate credential path.
View the whole map (7 more steps)
  • Read the exact pull error
  • This isn't a credentials problem
  • Confirm the pod actually references an imagePullSecrets entry
  • Fix: attach an image pull secret to the namespace's default ServiceAccount
  • Check the referenced secret exists in this namespace with the right registry host
  • Fix: the token is stale — regenerate the secret with current credentials
  • Fix: the secret is missing, in the wrong namespace, or has the wrong registry host

What to test

Pod stuck in ImagePullBackOff pulling from a private registry

A working `docker pull` of the same image on a developer's laptop is a red herring for this branch of the problem — it only proves the registry credentials are valid somewhere, not that the pod has them. Kubelet pulls images using the pod's own imagePullSecrets (or its ServiceAccount's), which is a completely separate credential path.

What happened?

Passed