Pulling from Private Registries with imagePullSecrets

Your company stores its container images in a private registry. No one outside the organization can pull them without credentials. Kubernetes needs those credentials too, but you do not hardcode them into the Pod spec where every developer on the team can read them. Instead, you store them in a Secret and reference that Secret from the Pod. The kubelet reads the Secret at pull time and authenticates against the registry on behalf of the Pod.

Storing credentials in a Secret

Docker registry credentials are stored as a Secret of type kubernetes.io/dockerconfigjson. This type is exactly what it sounds like: a base64-encoded version of the JSON config file that Docker writes to ~/.docker/config.json when you run docker login. Kubernetes knows how to hand this to the container runtime when pulling an image.

You create this Secret with a single command:

kubectl create secret docker-registry my-registry-creds --docker-server=registry.example.com --docker-username=myuser --docker-password=mypassword

After creating it, confirm the Secret exists and has the correct type:

kubectl get secret my-registry-creds

The output will show the type as kubernetes.io/dockerconfigjson. You can also describe it to see its metadata, though the data field will be redacted in normal output:

kubectl describe secret my-registry-creds

Referencing the Secret in a Pod

Once the Secret exists, you reference it in the Pod spec under spec.imagePullSecrets. Create the manifest:

nano private-pod.yaml

# illustrative only
apiVersion: v1
kind: Pod
metadata:
  name: private-pod
spec:
  imagePullSecrets:
    - name: my-registry-creds
  containers:
    - name: app
      image: registry.example.com/myapp:1.0

imagePullSecrets is a list, so you can reference multiple Secrets if the Pod needs images from more than one private registry. Apply the manifest:

kubectl apply -f private-pod.yaml

Then describe the Pod to verify that the pull secret was picked up:

kubectl describe pod private-pod

Look at the Image: field to confirm the full image reference, and at the Events section to see whether the pull succeeded. In a real cluster, the kubelet would contact registry.example.com, present the credentials from the Secret, and pull the image. In the simulator the image is resolved locally, but the pull secret reference is validated against cluster state.

Attaching pull secrets to a ServiceAccount

Referencing imagePullSecrets on every individual Pod spec gets tedious quickly, especially in a namespace with dozens of Pods. There is a cleaner approach: attach the pull secret to the namespace’s ServiceAccount instead.

Every Pod in Kubernetes uses a ServiceAccount. Unless you specify one, it uses the default ServiceAccount of its namespace. If you patch imagePullSecrets onto that ServiceAccount, every Pod that uses it will inherit the pull secret automatically, with no change to individual Pod specs.

kubectl patch serviceaccount default -p '{"imagePullSecrets":[{"name":"my-registry-creds"}]}'

You can now authenticate Kubernetes against a private registry, store the credentials safely in a Secret, and apply them at Pod or ServiceAccount scope. The remaining question is: once Kubernetes has access to the image, when does it actually pull? That is controlled by imagePullPolicy, which is the subject of the next lesson.