Introduction

When imagePullSecrets appears to be "not working," the secret is often not the real problem. Kubernetes can only use that secret to authenticate to the registry. If the image name, tag, registry hostname, secret namespace, or service-account wiring is wrong, you can still get errors that look like "image not found."

What imagePullSecrets Actually Does

imagePullSecrets provides registry credentials to the kubelet so it can pull a private image. It does not:

• fix an incorrect image name
• create the secret automatically in the right namespace
• override the service account if the pod does not reference it

A typical pod configuration looks like this:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: demo
5spec:
6  containers:
7    - name: app
8      image: registry.example.com/team/app:1.0.0
9  imagePullSecrets:
10    - name: regcred

That only works if regcred exists in the same namespace as the pod and contains valid credentials for registry.example.com.

Verify the Secret First

The usual command is:

1kubectl create secret docker-registry regcred \
2  --docker-server=registry.example.com \
3  --docker-username=myuser \
4  --docker-password=mypassword \
5  --docker-email=[email protected]

Then confirm the secret exists in the right namespace:

kubectl get secret regcred -n my-namespace
kubectl describe secret regcred -n my-namespace

It is also worth confirming the secret type. For registry pulls, Kubernetes expects a Docker config style secret, commonly kubernetes.io/dockerconfigjson. If the secret exists but contains the wrong structure, the pod still cannot authenticate to the registry correctly.

If the pod lives in my-namespace but the secret was created in default, the pull still fails. Namespace mismatches are one of the most common causes.

Check the Image Reference Carefully

Even with correct credentials, the image reference itself must be exact:

• registry hostname must match the real registry
• repository path must be correct
• tag must exist
• image case and separators must match exactly

Some private registries intentionally return a generic "not found" style error when authentication fails, which makes bad credentials and bad image names look similar. That is why you should validate both the secret and the image reference rather than assuming the error text tells the whole story.

Service Account Wiring Matters Too

Instead of putting imagePullSecrets on every pod, some teams attach the secret to the service account used by those pods:

1apiVersion: v1
2kind: ServiceAccount
3metadata:
4  name: app-sa
5imagePullSecrets:
6  - name: regcred

Then the pod references that service account:

spec:
  serviceAccountName: app-sa

If the pod uses a different service account than the one you configured, the secret will never be used.

Read Pod Events, Not Just the Final Status

The most useful diagnostic output is usually:

kubectl describe pod <pod-name> -n my-namespace

Look at the event section. It often reveals whether the real problem is:

• authentication failure
• name resolution problem
• wrong image tag
• secret not found

That is much more actionable than staring only at ImagePullBackOff.

Common Pitfalls

• Creating the registry secret in the wrong namespace.
• Assuming imagePullSecrets can compensate for a wrong image name or tag.
• Forgetting that the secret must match the actual registry hostname used in the image reference.
• Attaching the secret to one service account while the pod runs under another.
• Reading "image not found" too literally when some registries use that message for auth failures too.

Summary

• 'imagePullSecrets only supplies registry credentials; it does not fix image-reference mistakes.'
• Make sure the secret exists in the same namespace as the pod or attached service account.
• Verify the registry hostname, repository path, and tag exactly.
• Check pod events with kubectl describe pod to see the real pull failure details.
• Treat image-name issues, namespace wiring, and credential issues as separate checks, not one combined guess.