Pulling from a private registry requires credentials. Local builds use a login that stores a token, and orchestrators use an image pull secret. The goal is to keep credentials scoped, short-lived and out of images and source.
Before you start
You should be comfortable with docker pull and Kubernetes pods. This article covers registry authentication and pull secrets.
Step-by-step walkthrough
Step 1: Authenticate locally with a helper
docker login stores a credential, often via a credential helper that keeps it in the OS keychain rather than a plaintext file. The token should be scoped to pull or push as needed, so a leaked token has limited use.
Step 2: Provide pull credentials to orchestrators
Kubernetes pulls images using an imagePullSecret, a secret of type docker-registry referenced by the pod’s imagePullSecrets. The secret holds the registry credentials, and the kubelet uses them to pull. The credentials should be a token, not a user password.
Step 3: Scope and rotate
Give CI and clusters their own tokens with the least privilege they need — read-only for pull, write only where pushes happen. Rotate tokens and set expiry, and never bake credentials into a Dockerfile or image layer, where they are recoverable.
Worked scenario
The pod references a registry pull secret.
apiVersion: v1
kind: Pod
metadata:
name: app
spec:
imagePullSecrets:
- name: registry-credentials
containers:
- name: app
image: registry.example.com/app:1.2.3Walk through the example
The kubelet reads registry-credentials, a docker-registry secret, and uses it to pull app:1.2.3 from the private registry. The credentials live in the secret, not in the image or the manifest, so they can be rotated without rebuilding. The token can be read-only, since the cluster only pulls.
Common mistake
Putting credentials in a Dockerfile or a build arg, where they persist in the image history. Another is one long-lived admin token used everywhere, so a leak exposes every repository.
Verify the behavior
Pull a private image after logging in and confirm the credential helper is used. Create the pull secret and confirm a pod can pull without local credentials. Inspect the image history and confirm no credentials appear.
Interview exercise
Why is a per-environment token better than one shared credential?
Answer and reasoning
A per-environment token limits the blast radius of a leak and can be rotated independently, so a compromise in one environment does not expose the others. It also lets you scope permissions: read-only in clusters, write only in build systems. One shared credential gives every holder the union of all privileges.
Continue learning
Compare secret handling in Docker secrets in builds and Git secret management. Read the Kubernetes image pull secret documentation and try the Docker interview questions.