Kubernetes imagePullSecret Generator
Build the .dockerconfigjson a private registry pull needs, with the registry key written the way the kubelet matches it. Give it the image you are pulling and it checks the key against what that reference resolves to, which is the mismatch that fails as though the image did not exist.
imagepullsecret.yaml
updates as you typeCommon mistakes
These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
Writing the Docker Hub registry URL by hand
It must be https://index.docker.io/v1/ exactly. Anything else, including docker.io, produces a secret that authenticates nothing and the pull silently falls back to anonymous.
Instead:Use the exact URL. This is the single most common failure with pull secrets.
Using an Opaque secret
The type must be kubernetes.io/dockerconfigjson and the key must be .dockerconfigjson with the leading dot. An Opaque secret with the same content is ignored with no error.
Instead:Set both the type and the key exactly.
Creating the secret in the wrong namespace
Pull secrets are namespaced and not shared. A secret in default does nothing for a pod in production.
Instead:Create it in every namespace that pulls, or attach it to the service account.
What an imagePullSecret is, and the four ways it silently does nothing
A pull secret is one JSON file, the same one Docker writes to ~/.docker/config.json, wrapped in a Secret of a specific type. The kubelet reads it before pulling an image from a private registry. Every way of getting it wrong produces the same symptom, ImagePullBackOff, with a registry error that reads as though the image does not exist, so the shape below is worth knowing rather than copying.
The registry key has to match what the image resolves to
The kubelet looks the credential up by the registry the image reference resolves to. Docker Hub is the case that catches everyone: its key is a URL left over from the v1 registry API, not the host in the image reference and not the host the pull goes to. A Secret keyed on docker.io applies cleanly, mounts cleanly, matches nothing, and the pull falls back to anonymous.
nginx:1.27 -> https://index.docker.io/v1/
myuser/private-app:1.0 -> https://index.docker.io/v1/
ghcr.io/org/app:1.0 -> ghcr.io
localhost:5000/app -> localhost:5000
1234.dkr.ecr.eu-west-1... -> 1234.dkr.ecr.eu-west-1.amazonaws.com
# Docker's rule: the part before the first slash is a
# registry only if it has a dot or a colon in it, or is
# exactly localhost. Otherwise it is a Docker Hub user.The type and the key are both exact, and the dot is part of the key
The Secret type must be kubernetes.io/dockerconfigjson and the key inside it must be .dockerconfigjson with the leading dot. An Opaque Secret with the same content is ignored. A key written without the dot is ignored. Neither produces an error at apply time, because both are valid objects: the failure arrives later, on the node, as a pull that was never authenticated.
type: kubernetes.io/dockerconfigjson
stringData:
.dockerconfigjson: |-
{"auths": ...}
# The older format still exists and is not the same:
# type: kubernetes.io/dockercfg
# key: .dockercfg
# body: the auths map WITHOUT the "auths" wrapper
# Mixing the two is the second most common version
# of this mistake.What is inside the file, and why auth is the field that matters
The JSON is a map of registry to credential. Each credential carries a username, a password and an auth field, and auth is base64 of username:password. Most registries read auth and ignore the other two, which is why a config with only username and password works against one registry and returns 401 from another. base64 here is a transport detail from the format, not protection.
{
"auths": {
"https://index.docker.io/v1/": {
"username": "myuser",
"password": "dckr_pat_xxx",
"auth": "bXl1c2VyOmRja3JfcGF0X3h4eA=="
}
}
}
echo bXl1c2VyOmRja3JfcGF0X3h4eA== | base64 -d
myuser:dckr_pat_xxxTwo ways to attach it, and only one of them covers pods you did not write
imagePullSecrets on a pod spec covers that workload. On a ServiceAccount it covers every pod that uses the account, which includes pods created by operators and charts whose manifests you do not control, and it is the route most people want. The catch is timing: the account's list is copied onto a pod when the pod is created, so patching the ServiceAccount does nothing for pods that already exist.
# per workload
spec:
imagePullSecrets:
- name: regcred
containers: [...]
# per ServiceAccount, applies to every pod using it
kubectl patch serviceaccount default -n prod \
-p '{"imagePullSecrets":[{"name":"regcred"}]}'
# and the Secret is namespaced: five namespaces
# pulling the same private image need five copies.Where a static secret is the wrong answer entirely
An ECR authorization token expires 12 hours after it is issued, so a Secret built from one works today and breaks overnight, on a pod that merely rescheduled. Use the node's IAM role through the ECR credential provider, the credential helper, or a CronJob that recreates the Secret. Google's key file has the opposite problem: it never expires, so it works until it leaks, and Workload Identity removes it. The kubelet also has its own credentials on the node, which is why identical manifests pull on one cluster and not another.
# ECR: valid for 12 hours from issue
aws ecr get-login-password --region eu-west-1
# GCR / Artifact Registry with a key file
username: _json_key
password: <the entire key.json, newlines and all>
# On EKS and GKE the node credential provider often
# means no pull secret is needed at all, which is why
# the missing one is not noticed until a workload
# moves to a differently built cluster.