Debugging ImagePullBackOff on a private registry

What's really being asked

This checks both knowledge of the imagePullSecrets mechanism and a disciplined troubleshooting approach to ImagePullBackOff.

The full answer

Kubelet pulls images on the node and needs credentials for private registries. You create a Secret of type kubernetes.io/dockerconfigjson, typically with kubectl create secret docker-registry, holding the registry host, username, and password or token. You attach it via imagePullSecrets in the pod spec or, more durably, on the ServiceAccount the pod uses so all its pods inherit it. ImagePullBackOff means repeated pull failures with exponential backoff. Troubleshoot by running kubectl describe pod and reading the Events: the message distinguishes a not-found image or wrong tag, an authentication failure pointing at a missing or stale secret, and connection errors pointing at node networking or registry reachability. Verify the secret exists in the right namespace, decode it to confirm the host matches, and check token expiry for cloud registries.

The mistakes people make

Recreating the pod repeatedly without reading events. Putting the secret in the wrong namespace. Assuming a cluster-wide secret without referencing it. Confusing ImagePullBackOff with CrashLoopBackOff.

What usually comes next

What is the difference from CrashLoopBackOff? Why must the secret be in the pod's namespace? How do cloud registries avoid static secrets? What does the backoff schedule look like?

A concrete example

A pod shows ImagePullBackOff. kubectl describe pod reveals an event: failed to authorize, unauthorized. You check the secret and find imagePullSecrets references regcred but the Secret lives in a different namespace than the pod. You recreate the dockerconfigjson Secret in the pod's namespace, confirm the registry host string matches the image reference exactly, and the next pull succeeds.