The containerd Image-Path Bug That Looked Bigger Than It Was

Symptom

I had to change the web-app image reference so containerd could resolve it correctly. The Kubernetes objects were fine; the image identity was the broken part.

The symptom pointed at the wrong layer. A deployment can be structurally correct while the runtime cannot resolve the image reference you gave it.

My first rule: identify the stage of failure

source -> image build -> registry identity -> Helm value -> node runtime pull -> container start

What I checked

I checked image reference, registry reachability, node pull events, image digest, running container image ID before changing anything.

Where the problem actually was

The root cause was this: A deployment can be structurally correct while the runtime cannot resolve the image reference you gave it. The practical lesson was simple: Always debug image identity and registry resolution as a separate layer from application startup.

Prevention checklist

• Do not pair mutable latest tags with assumptions about reproducibility.
• Promote the same built artifact across environments.
• Use an explicit registry/repository path.
• Prefer immutable tags or digests for releases.
• Verify the node can pull the artifact.