Kubernetes Private Registry: Why, Setup, and imagePullSecrets

Worker nodes pull images from a registry when Pods start. This guide covers registry access, cluster pull credentials, and referencing images from Pod or Deployment manifests.

Quick Reference

Lab defaults: authenticated registry at 192.168.56.108:5000 (labuser / labpass) and, for comparison, open registry at 192.168.56.108:5001. Substitute your own hostnames and credentials in production.

Why Kubernetes needs a container registry

Three facts explain why a registry sits in the path:

• A container image is a packaged filesystem and metadata
• Kubernetes schedules Pods; it does not host image storage
• The registry is the handoff between build tools on your laptop and pulls on worker nodes

Skipping the push step is the most common beginner mistake. Local Podman or Docker storage is not visible to remote nodes.

For the full build-and-tag workflow, see Build and push container images. This article focuses on registry setup and how the cluster authenticates when it pulls.

Two independent choices are often lumped together as “public vs private”:

Kubernetes cares about the second pair when deciding whether imagePullSecrets are required:

• An internal registry can allow anonymous pulls on a trusted network
• A registry on the internet can still require credentials for each repository

Public registries already run on the internet. You do not install them for normal Kubernetes work — you reference a public image name in a manifest:

registry.k8s.io/pause:3.10
docker.io/library/nginx:alpine

For this path you do not need:

• A registry container on your lab host
• An imagePullSecret when the repository allows anonymous pulls

The lab sections below run internal registries on your LAN so you can compare anonymous and authenticated pulls on the same host.

Part 1 — Set up and publish to an internal registry

Open registry without authentication (port 5001)

On a trusted lab network, you can run registry:3 without REGISTRY_AUTH:

• Anyone who can reach the host may push and pull
• That is convenient for learning
• It is unsafe on open networks — use authentication when the host is broadly reachable

sudo mkdir -p /opt/lab-registry-open/data
sudo podman run \
  -d \
  --name lab-registry-open \
  -p 5001:5000 \
  -v /opt/lab-registry-open/data:/var/lib/registry:Z docker.io/library/registry:3

Anonymous catalog access should succeed. Registry health checks use the curl command with -w to print only the HTTP status code:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5001/v2/_catalog

Sample output:

200

200 means no login is required.

Authenticated registry with htpasswd (port 5000)

When the internal registry must enforce access control, enable htpasswd basic authentication. The rest of this article uses port 5000 with credentials.

Install htpasswd if needed. On Rocky or RHEL nodes, install the tools package with dnf command:

sudo dnf install -y httpd-tools

Create storage, auth file, and a lab user:

sudo mkdir -p /opt/lab-registry/{data,auth}
sudo htpasswd -Bbn labuser labpass | sudo tee /opt/lab-registry/auth/htpasswd > /dev/null

Start the registry with Podman:

sudo podman run \
  -d \
  --name lab-registry \
  -p 5000:5000 \
  -v /opt/lab-registry/data:/var/lib/registry:Z \
  -v /opt/lab-registry/auth:/auth:Z \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Lab Registry" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd docker.io/library/registry:3

On SELinux-enforcing RHEL-family hosts, append :Z to bind mounts so Podman can relabel host directories for container access.

Confirm the container is running:

sudo podman ps --filter name=lab-registry --format '{{.Names}} {{.Status}}'

Sample output:

lab-registry Up 5 seconds

Anonymous catalog access should fail; authenticated access should succeed:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5000/v2/_catalog

Sample output:

401

curl -s -u labuser:labpass http://127.0.0.1:5000/v2/_catalog

Sample output:

{"repositories":[]}

401 without credentials confirms authentication is enabled. The empty list is normal before the first push.

Build and push the test image

Allow insecure pushes to the lab registries from your workstation:

sudo tee /etc/containers/registries.conf.d/999-lab-registry.conf <<'EOF'
[[registry]]
location = "192.168.56.108:5000"
insecure = true

[[registry]]
location = "192.168.56.108:5001"
insecure = true
EOF

Build a small image and publish it to both internal registries:

mkdir kubernetes-private-registry-demo && cd kubernetes-private-registry-demo

<!-- index.html -->
<!DOCTYPE html>
<html><body><h1>Private registry demo v1.0.0</h1></body></html>

# Containerfile
FROM docker.io/library/nginx:alpine
COPY index.html /usr/share/nginx/html/index.html

podman build -t localhost/web:v1.0.0 .
podman tag localhost/web:v1.0.0 192.168.56.108:5001/web:v1.0.0
podman push --tls-verify=false 192.168.56.108:5001/web:v1.0.0

Confirm the open-registry tag exists:

curl -s http://192.168.56.108:5001/v2/web/tags/list

Sample output:

{"name":"web","tags":["v1.0.0"]}

Push the same image to the authenticated registry on port 5000:

podman tag localhost/web:v1.0.0 192.168.56.108:5000/web:v1.0.0
podman login 192.168.56.108:5000 -u labuser -p labpass --tls-verify=false
podman push 192.168.56.108:5000/web:v1.0.0 --tls-verify=false

Confirm the authenticated-registry tag exists:

curl -s -u labuser:labpass http://192.168.56.108:5000/v2/web/tags/list

Sample output:

{"name":"web","tags":["v1.0.0"]}

Configure nodes for HTTP registries

Registry transport on nodes depends on how the host is exposed:

• Production — use HTTPS with a trusted certificate
• Lab — plain HTTP on a private network is common
• containerd default — HTTPS only; each node needs an explicit HTTP endpoint for port 5000, 5001, or any internal registry hostname

On every node that pulls from an internal HTTP registry, ensure /etc/containerd/config.toml exposes the per-host certificate directory. In the containerd 2.x plugin tree, add or confirm:

[plugins."io.containerd.cri.v1.images".registry]
  config_path = "/etc/containerd/certs.d"

Do not duplicate this table if your file already defines config_path. Official containerd documentation places config_path in the main configuration.

Create a per-host directory under /etc/containerd/certs.d/ for each registry endpoint. Example for the authenticated lab registry on port 5000:

Create /etc/containerd/certs.d/192.168.56.108:5000/hosts.toml:

server = "http://192.168.56.108:5000"

[host."http://192.168.56.108:5000"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true

Repeat the same pattern for 192.168.56.108:5001/hosts.toml when you run the no-authentication registry on port 5001.

Restart containerd and kubelet. On systemd nodes, use systemctl command to reload both daemons after registry trust changes:

sudo systemctl restart containerd kubelet

Confirm containerd loaded the registry path:

sudo containerd config dump | grep -A2 'registry'

Sample output:

[plugins."io.containerd.cri.v1.images".registry]
      config_path = "/etc/containerd/certs.d"

Without the node configuration, pulls fail with http: server gave HTTP response to HTTPS client even when credentials are correct. Part 2 tests cluster pulls against the images you just published.

Part 2 — Test direct and authenticated image pulls

Public image without imagePullSecrets

apiVersion: v1
kind: Pod
metadata:
  name: public-pull
  namespace: registry-access-demo
spec:
  containers:
    - name: pause
      image: registry.k8s.io/pause:3.10

kubectl create namespace registry-access-demo
kubectl apply -f public-pull.yaml

kubectl get pod public-pull -n registry-access-demo

Sample output:

NAME          READY   STATUS    RESTARTS   AGE
public-pull   1/1     Running   0          8s

kubelet pulled registry.k8s.io/pause:3.10 without a pull Secret.

Internal anonymous pull (port 5001)

Deploy a Pod that references the image you pushed to port 5001:

apiVersion: v1
kind: Pod
metadata:
  name: internal-open-pull
  namespace: registry-access-demo
spec:
  containers:
    - name: web
      image: 192.168.56.108:5001/web:v1.0.0

kubectl apply -f internal-open-pull.yaml

kubectl get pod internal-open-pull -n registry-access-demo

Sample output:

NAME                 READY   STATUS    RESTARTS   AGE
internal-open-pull   1/1     Running   0          8s

No imagePullSecrets were required.

Authenticated pull without credentials (expected failure)

Deploy a Pod that references the image on port 5000 without pull credentials:

apiVersion: v1
kind: Pod
metadata:
  name: private-pull-fail
  namespace: registry-access-demo
spec:
  containers:
    - name: web
      image: 192.168.56.108:5000/web:v1.0.0

kubectl apply -f private-pull-fail.yaml

Sample events from kubectl describe pod private-pull-fail -n registry-access-demo:

Warning  Failed  kubelet  Failed to pull image "192.168.56.108:5000/web:v1.0.0": ... authorization failed: no basic auth credentials
Warning  Failed  kubelet  Error: ErrImagePull
Warning  Failed  kubelet  Error: ImagePullBackOff

The registry is reachable, but kubelet has no username or password. Remove the failed Pod before Part 3:

kubectl delete pod private-pull-fail -n registry-access-demo

Part 3 — Create and use imagePullSecrets

imagePullSecrets is a Pod-spec field that lists Secret names. Each pull Secret must satisfy:

• Type — kubernetes.io/dockerconfigjson (recommended) or legacy kubernetes.io/dockercfg
• Data key — .dockerconfigjson, a JSON document in the same shape as Docker or Podman auth files
• Scope — namespace-scoped; kubelet reads it when pulling for Pods in that namespace

Pod spec.imagePullSecrets  →  Secret name (namespace-scoped)
        ↓
Secret type kubernetes.io/dockerconfigjson
        ↓
Key .dockerconfigjson holds registry host → auth entry
        ↓
kubelet passes credentials to containerd during pull

Three common ways to create that Secret:

All methods produce the same Secret type. Pick based on where credentials already exist.

Option 1 — docker-registry Secret

kubectl create secret docker-registry builds the .dockerconfigjson content for you. Use it when you know the registry hostname, username, and secret string.

For the lab registry:

kubectl create secret docker-registry regcred \
  --namespace=registry-access-demo \
  --docker-server=192.168.56.108:5000 \
  --docker-username=labuser \
  --docker-password='labpass'

Sample output:

secret/regcred created

Confirm the type:

kubectl get secret regcred -n registry-access-demo

Sample output:

NAME      TYPE                             DATA   AGE
regcred   kubernetes.io/dockerconfigjson   1      1s

The --docker-password flag accepts passwords and tokens. The name is historical from Docker Hub:

Cloud docs may label tokens ACCESS_TOKEN or REGISTRY_TOKEN. Kubernetes does not read those variable names — paste the token string into --docker-password.

Option 2 — import Podman or Docker auth file

If you already ran podman login, copy the auth file into a Secret instead of retyping credentials:

kubectl create secret generic regcred-from-file \
  --namespace=registry-access-demo \
  --from-file=.dockerconfigjson="${XDG_RUNTIME_DIR}/containers/auth.json" \
  --type=kubernetes.io/dockerconfigjson

Docker default path:

kubectl create secret generic regcred-from-file \
  --namespace=registry-access-demo \
  --from-file=.dockerconfigjson="$HOME/.docker/config.json" \
  --type=kubernetes.io/dockerconfigjson

The file must contain an auths entry for the registry hostname in your image: field. It cannot rely on:

• credsStore alone
• credHelpers alone

If either is present without a direct auths entry, kubelet cannot use the file. Create the Secret with Option 1 instead.

Option 1 and Option 2 create interchangeable Secrets. Use one pull Secret name in the Pod (regcred or regcred-from-file).

Option 3 — manual Secret manifest

For GitOps pipelines, embed base64-encoded .dockerconfigjson in a manifest:

apiVersion: v1
kind: Secret
metadata:
  name: regcred-manual
  namespace: registry-access-demo
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: <base64-encoded-docker-config>

Generate the JSON with kubectl create secret docker-registry --dry-run=client -o yaml and copy the data field, or encode an auth file with base64 -w0. Treat the manifest like a password file.

Attach to a Deployment

Reference the Secret from the Pod template:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: private-web
  namespace: registry-access-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: private-web
  template:
    metadata:
      labels:
        app: private-web
    spec:
      imagePullSecrets:
        - name: regcred
      containers:
        - name: web
          image: 192.168.56.108:5000/web:v1.0.0
          imagePullPolicy: IfNotPresent

Apply and verify:

kubectl apply -f private-web.yaml

Sample output:

deployment.apps/private-web created

kubectl rollout status deployment/private-web -n registry-access-demo --timeout=90s

Sample output:

deployment "private-web" successfully rolled out

kubectl get pods -n registry-access-demo -l app=private-web

Sample output:

NAME                           READY   STATUS    RESTARTS   AGE
private-web-5875c679f6-2mn56   1/1     Running   0          15s
private-web-5875c679f6-8p7r2   1/1     Running   0          15s

Both Pods pulled the private image after imagePullSecrets supplied credentials.

Attach to a ServiceAccount

Repeating imagePullSecrets in every Deployment is tedious. Attach the registry Secret to a ServiceAccount instead:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: private-registry
  namespace: registry-access-demo
imagePullSecrets:
  - name: regcred

kubectl apply -f private-registry-sa.yaml

Reference the ServiceAccount from the Pod template and remove duplicate imagePullSecrets unless you intentionally override them:

spec:
  template:
    spec:
      serviceAccountName: private-registry

Kubernetes copies ServiceAccount imagePullSecrets into new Pods that do not already define their own list. See Kubernetes ServiceAccounts for token and automount details.

A Pod can list multiple pull Secrets when it uses images from more than one private registry:

imagePullSecrets:
  - name: quay-regcred
  - name: internal-regcred

imagePullPolicy, tags, and digests

imagePullPolicy tells kubelet whether to contact the registry when a container starts:

Omitted fields default from the image reference:

• :latest or no tag — Always
• Any other explicit tag — IfNotPresent
• Digest reference — IfNotPresent

Kubernetes sets this default when the object is first created. Changing the image reference later does not automatically change an existing imagePullPolicy field.

After the private-web Pods were running, the node recorded this digest:

192.168.56.108:5000/web@sha256:79ab0838785cba5ae5a2ac5ca38397c50ab66f3f2f2dce9d2b88648a62a8faa0

Pin by digest when you need immutable rollouts:

image: 192.168.56.108:5000/web@sha256:79ab0838785cba5ae5a2ac5ca38397c50ab66f3f2f2dce9d2b88648a62a8faa0

Troubleshoot pull failures

Read Pod events first:

kubectl describe pod <pod-name> -n registry-access-demo

kubectl get events -n registry-access-demo --sort-by=.lastTimestamp

What's Next

• Choose a Kubernetes Workload Resource
• Kubernetes Pods and Pod Lifecycle
• Differences and When to Use Each

References

• Pull an image from a private registry
• Images
• Distribution registry configuration
• ServiceAccounts

Summary

Separate three concerns when you design registry access:

• Where images are stored — internet host versus internal host
• Whether authentication is enforced — anonymous pull versus credentials required
• How credentials are packaged — kubectl create secret docker-registry, auth-file import, or manual Secret

Direct pulls work for any registry that allows anonymous access, including an internal HTTP registry on a trusted network. When anonymous pulls are denied and the registry requires credentials, create a kubernetes.io/dockerconfigjson Secret in the Pod namespace and reference it through imagePullSecrets or a ServiceAccount.