To pull from a private registry, create a docker-registry style Secret in the same namespace as the pod and reference it in imagePullSecrets, either on the pod or on its ServiceAccount. Keep one scoped credential per registry, rotate it, and know that newer Kubernetes can check credentials even for images already cached on the node.
What the docs say
The Kubernetes images documentation describes imagePullSecrets as the recommended approach to run containers based on images in private registries. The details to remember:
- The Secret must exist in the same namespace as the pod and be of type dockercfg or dockerconfigjson.
- Each item in the imagePullSecrets array can reference only one Secret in that namespace.
- You can set imagePullSecrets on a ServiceAccount so pods using it get the credential automatically.
- For several registries, create one Secret per registry.
- Credentials from a ServiceAccount are merged with a per-node Docker config file, if one exists.
A setup checklist
- Use a read-only pull credential. The credential should be able to pull, not push or delete.
- Scope it narrowly. Limit it to the repositories this workload needs.
- Prefer short-lived credentials where your registry and platform support them, and refresh them with automation.
- Create it per namespace. Because Secrets are namespaced, a credential in one namespace is not visible to pods in another, which is a boundary worth keeping.
- Attach it to the ServiceAccount so you do not repeat it in each manifest.
- Restrict who can read Secrets. Anyone who can read the Secret can copy the credential. Review RBAC for get and list on Secrets.
- Encrypt Secrets at rest in the cluster store. The OWASP cheat sheet notes Kubernetes stores secrets unencrypted by default, so add encryption or another tool.
- Rotate on a schedule and after staff or tooling changes.
The pre-pulled image gotcha
With IfNotPresent, a node that already holds an image uses the local copy and never contacts the registry. That means a pod in another namespace, with no valid credential, could run a private image that happens to be cached on the node.
The documentation describes a feature, in beta since v1.35 and enabled by default, under which Kubernetes validates image credentials for every image that requires credentials to be pulled, even if the image is already present on the node. Credentials that previously pulled successfully are validated locally without contacting the registry. A kubelet setting controls the behavior, with options that range from never verifying to always verifying. The default option does not verify preloaded images. New or rotated credentials require the image to be re-pulled from the registry.
Two practical points follow. Check your cluster version and settings rather than assuming the behavior. And if you rely on pre-pulled images in place of credentials, the docs note that all nodes need the same pre-pulled images.
Common failures
- ImagePullBackOff after rotation: the old Secret still referenced, or the new one is in the wrong namespace.
- Wrong Secret type, which the pull ignores.
- ServiceAccount not attached to the pod's account.
- Credential too narrow, missing a repository the pod needs.
Reduce reliance on static secrets
Where your platform allows it, use node-level or workload identity credential providers so no long-lived password sits in a Secret. This shortens the exposure window if a Secret leaks.
For pinning what runs once it is pulled, see imagePullPolicy defaults.
Safeguard's policies and gates can check manifests against your rules during review, and a free scan shows what is inside an image you pull.
Quick check
Can one Secret serve several namespaces?
No. The Secret must be in the same namespace as the pod, so you create it in each namespace that needs it.
Does a cached image mean no credentials are needed?
Historically it could. Newer Kubernetes can verify credentials for cached images, depending on version and kubelet settings, so check yours.
Sources
Last reviewed: 19 October 2026.
