Kubernetes "ImagePullSecret not found" on deploy in CI - Fix it

By Daniel Zoghalchali·Latchkey

A pod (or its ServiceAccount) names an imagePullSecrets entry that is not present in the namespace. Without it the kubelet has no credentials for the private registry and the pull fails - even though the registry and image are fine.

What this error means

kubectl describe pod warns Secret "regcred" not found or the pull fails with unauthorized. The pod stays in ImagePullBackOff / ContainerCreating.

kubectl

Warning  FailedMount  kubelet  MountVolume.SetUp failed for volume ... :
secret "regcred" not found

Common causes

Pull secret missing in the namespace

imagePullSecrets are namespace-scoped; the secret exists in another namespace or was never created here.

Name mismatch

The pod/ServiceAccount references a secret name that differs from the one created.

How to fix it

Create the pull secret in the right namespace

Create a docker-registry secret matching the referenced name and namespace.

Terminal

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=ci --docker-password="${REG_PASS}" \
  -n <namespace>

Wire it to the pod or ServiceAccount

Reference it via imagePullSecrets on the pod, or attach it to the ServiceAccount.
Confirm the name matches exactly and lives in the pod namespace.
Re-apply and confirm the image pulls.

How to prevent it

Provision pull secrets per namespace as part of the deploy bundle.
Attach the pull secret to the ServiceAccount so every pod inherits it.
Keep the secret name a single source-of-truth variable.

Frequently asked questions

What causes ""imagePullSecret not found""?