Context
ImagePullBackOff describes repeated image-pull failure and a retry delay. It is not a diagnosis of bad credentials. The image name might be wrong, the registry may be unreachable, or the Pod may reference a Secret that does not exist in its namespace. Start with the kubelet's event message and follow the exact Pod configuration.
Prerequisites are the failing Pod name, namespace, expected registry hostname, and permission to read workload metadata and events. Secret-reading permissions are sensitive. Most early checks need only a Secret's name and type; do not print its encoded data or paste registry credentials into an incident ticket.
1. Classify the first pull error
kubectl -n shop describe pod catalog-abc
kubectl -n shop get pod catalog-abc -o yaml
kubectl -n shop get deployment catalog -o yaml
Read the event preceding the backoff message. Distinguish a missing pull Secret from registry authorization failure, an absent manifest, or a network timeout. Compare the live Pod's image with the intended repository and tag or digest. The live Pod matters because a recently updated Deployment template does not retroactively rewrite existing Pod specifications.
2. Check namespace and Secret type
kubectl -n shop get secret registry-reader -o jsonpath='{.metadata.name}{" "}{.type}{"\n"}'
kubectl -n shop get serviceaccount catalog -o yaml
The names here are illustrative. imagePullSecrets reference Secrets in the same namespace as the Pod. A similarly named Secret in another namespace does not satisfy the reference. Docker-registry pull Secrets use the supported Docker configuration Secret types. A generic application Secret with a token under an arbitrary key is not automatically a registry configuration.
3. Follow ServiceAccount attachment
Compare the Pod's serviceAccountName and imagePullSecrets with the ServiceAccount used when that Pod was admitted. ServiceAccounts can supply default image-pull references to newly created Pods. Updating that ServiceAccount is therefore different from changing an existing Pod's pull references.
For an explicitly illustrative example, the registry-reader Secret exists in platform, while catalog runs in shop. A developer's local docker login succeeds, but those workstation credentials do not establish that the shop Pod has a usable Secret. The correction is a namespace-scoped credential provisioning change under the team's secret-management procedure, followed by verification of the next intended Pod creation.
Locate the failure boundary
| Event or observation | Meaning to investigate | Safe next evidence |
|---|---|---|
| FailedToRetrieveImagePullSecret | Reference cannot be retrieved | Name, namespace and Secret existence |
| Unauthorized or denied | Registry credential or repository access | Registry-side authentication audit |
| Manifest unknown | Repository or image reference | Approved registry image listing |
| Timeout or TLS error | Registry connectivity or trust | Runtime and registry connection evidence |
If the Secret exists, confirm through a trusted credential workflow that its registry key matches the image's registry hostname and port. Check token expiration and repository scope without publishing token contents. A browser login or a successful pull on one previously cached node is incomplete verification.
Apply a narrow correction and prove it
Correct the workload reference, namespace provisioning, image reference, or registry permission that the evidence identifies. Use the normal deployment process to create a test Pod with the intended ServiceAccount. Verify the image is pulled, the resulting image identity is expected, and the workload starts. Avoid repeatedly deleting production Pods while the credential issue remains unresolved.
Maintain an inventory of registry credentials, namespace owners, repository scope, and rotation method. During rotation, exercise an uncached pull in a controlled environment. Monitor pull-failure events by registry and namespace, retaining sanitized messages so expiration failures can be distinguished from a missing image.
Explore Clouvenix containers kubernetes for implementation and operational handover.
Technical reference
Private registry pulls, container image credentials and Secret references.