A pod stuck in ImagePullBackOff is a short list of causes wearing one error message. The event log usually says failed to pull image and then something about authorisation or a timeout, which tells you which half of the list to check.
Cause one: the node role cannot read the registry
The kubelet pulls images, and the kubelet uses the node’s identity. If the node role lacks permission to read from the container registry, every pull fails with an authorisation error, including images that worked yesterday.
This is the most common cause after a cluster is rebuilt or a role is recreated. Check the node instance profile, not the pod’s service account, because the pod is not the one pulling.
Cause two: a private subnet with no route to the registry
A node in a private subnet needs a path to the registry endpoint. If the subnet has no NAT gateway, the pull needs a registry interface endpoint, and a route is not enough on its own: the endpoint must exist in the right availability zones.
The failure looks like a timeout rather than a permission error. That distinction is the fastest way to tell causes one and two apart.
Cause three: the image reference or tag is wrong
An image that exists locally but was never pushed, a tag that was overwritten, or a repository name with a typo all produce the same message. Check the exact reference the pod requests against what the registry reports.
This is common when a pipeline tags with a commit hash and the deployment manifest uses latest, or the reverse.
Cause four: the service account is not wired to the pull secret
For a private registry outside the cloud provider, an image pull secret has to be attached to the service account the pod runs as. Attaching it to the deployment’s pod spec works, and then a new deployment forgets it.
The durable pattern is to attach the secret to the service account and reference the account from the workload, so the credential follows the identity rather than the manifest.
Cause five: node disk pressure
A node with a full disk evicts images and cannot pull new ones. The error mentions space, but it is buried under the pull failure. Check node conditions and the kubelet’s disk usage.
This one surfaces after a while rather than at deploy time, which is why it is worth an alert on disk pressure rather than a dashboard nobody watches.
The order to check them
- Read the event, and separate authorisation from timeout.
- Authorisation: node role and registry policy.
- Timeout: subnet route, NAT or registry endpoint in the right zones.
- Neither: confirm the image reference exists.
- Intermittent: node disk pressure and registry rate limits.
That order resolves almost every case in under ten minutes, which matters because a failed rollout blocks every other deploy behind it.
Preventing the repeat
The permission and the route are infrastructure, so they belong in code alongside the cluster. A node role created by hand is a node role that will be recreated by hand, differently, after the next rebuild.
The cluster baseline, including identity and endpoint design, is described on managed Kubernetes services. If the pipeline is the other half of the problem, see DevOps and CI/CD services, and the network layer sits inside cloud landing zone setup.
