Introduction

When Kubernetes cannot pull from a private image registry, the root cause is usually one of four things: bad credentials, the secret is not attached to the workload, the image reference is wrong, or the node cannot reach the registry. The fastest way to solve it is to read the Pod events first and then verify the registry authentication path end to end.

Start With the Pod Events

Kubernetes usually tells you exactly where the pull failed.

kubectl describe pod my-app-abc123

Look for messages such as:

• 'ErrImagePull'
• 'ImagePullBackOff'
• 'unauthorized'
• 'manifest unknown'
• 'x509: certificate signed by unknown authority'
• 'dial tcp connection errors'

Those messages narrow the problem immediately. unauthorized usually means credentials or permissions. manifest unknown usually means the repository path or tag is wrong. TLS and connection errors point to network or certificate problems.

Create the Registry Secret Correctly

For a generic private Docker registry, create a docker-registry secret in the same namespace as the workload.

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 reference it from the Pod or Deployment:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: my-app
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: my-app
10  template:
11    metadata:
12      labels:
13        app: my-app
14    spec:
15      containers:
16        - name: my-app
17          image: registry.example.com/team/my-app:1.2.3
18      imagePullSecrets:
19        - name: regcred

The secret must be in the same namespace as the Pod. That single detail causes many failed pulls.

Verify the Image Reference Exactly

Before blaming Kubernetes, confirm the image path and tag are real.

docker pull registry.example.com/team/my-app:1.2.3

If that fails from a machine with valid credentials, the issue is not inside the cluster. Common mistakes include:

• using the wrong registry hostname
• pushing to one repository path and deploying from another
• forgetting the tag and relying on latest
• pulling from a private mirror while the image actually lives elsewhere

manifest unknown is the classic sign of this class of error.

Attach the Secret to a ServiceAccount When Many Pods Need It

If multiple workloads in one namespace use the same registry, attaching the secret to the ServiceAccount reduces repetition.

kubectl patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"regcred"}]}'

New Pods using that ServiceAccount will then inherit the pull secret automatically.

This is often cleaner than repeating imagePullSecrets in every manifest, though some teams still prefer explicit references per workload.

Check Node Reachability and TLS

Even with correct credentials, the node still has to reach the registry.

Things to verify:

• DNS resolution from the node
• firewall or proxy rules
• registry certificate trust
• whether the cluster is allowed to access the internet or the private network hosting the registry

If the error mentions TLS trust, the node runtime may not trust your internal certificate authority. If the error is a timeout or refused connection, it is usually networking rather than Kubernetes manifest syntax.

Cloud Registries Often Use Better Native Integrations

For registries such as ECR, GCR, Artifact Registry, or ACR, it is often better to use node IAM roles or workload identity instead of a static Docker password secret. Static secrets work, but they create rotation and security overhead.

If you are on a managed cloud platform, check whether the cluster can authenticate to the registry automatically through its cloud identity model.

Common Pitfalls

• Creating the secret in one namespace and deploying the Pod in another.
• Misspelling the image name or tag and mistaking it for an auth failure.
• Forgetting to reference the pull secret from the workload or ServiceAccount.
• Debugging only the Deployment and never reading the Pod events.
• Using static credentials for cloud registries when native identity integration is available.

Summary

• Start with kubectl describe pod because the event messages usually identify the failure class.
• Create the registry secret correctly and keep it in the same namespace as the workload.
• Make sure the secret is actually attached through imagePullSecrets or a ServiceAccount.
• Verify the image path and tag independently from Kubernetes.
• If auth is correct, investigate node networking and TLS trust next.