Introduction

Using Minikube with a local Docker registry is a fast development workflow, but self-signed certificates add one extra requirement: every runtime that pulls images must trust your registry certificate authority. If trust is missing, image pulls fail even when the registry is reachable. The solution is to configure certificate trust consistently across registry, Minikube nodes, and your local build pipeline.

Understand the Trust Chain

A private registry over TLS needs a certificate that clients trust. With self-signed setups, trust does not exist by default. Minikube nodes run container runtime daemons that validate certificates during docker pull or containerd image fetch.

If trust is broken, common errors include:

• x509: certificate signed by unknown authority
• ImagePullBackOff
• repeated pull retries in pod events

Treat this as certificate distribution work, not Kubernetes YAML work.

Create and Install Certificate Authority Material

Generate a local CA and server certificate for the registry host name you actually use.

1# Example hostname used by clients
2REG_HOST=registry.dev.local
3
4# Generate CA
5openssl genrsa -out ca.key 4096
6openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt -subj "/CN=DevRegistryCA"
7
8# Generate server cert
9openssl genrsa -out server.key 2048
10openssl req -new -key server.key -out server.csr -subj "/CN=$REG_HOST"
11openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial   -out server.crt -days 825 -sha256

Mount server.crt and server.key in your registry container, and expose the registry using the same host name.

Trust the CA Inside Minikube

Copy CA certificate into Minikube and restart runtime services so pulls trust the registry.

1minikube start
2
3# Copy CA to minikube node trust location
4minikube ssh "sudo mkdir -p /usr/local/share/ca-certificates/dev-registry"
5cat ca.crt | minikube ssh "sudo tee /usr/local/share/ca-certificates/dev-registry/ca.crt >/dev/null"
6
7# Update trust store
8minikube ssh "sudo update-ca-certificates"
9
10# Restart container runtime if needed
11minikube ssh "sudo systemctl restart containerd || sudo systemctl restart docker"

After trust update, verify pull directly from the node:

minikube ssh "ctr -n k8s.io images pull $REG_HOST:5000/myapp:dev"

If direct pull works, Kubernetes pulls should also work when image names match.

Deploy and Validate in Kubernetes

Use full registry path in your Deployment and inspect events.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: myapp
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: myapp
10  template:
11    metadata:
12      labels:
13        app: myapp
14    spec:
15      containers:
16        - name: myapp
17          image: registry.dev.local:5000/myapp:dev
18          imagePullPolicy: Always

kubectl apply -f deploy.yaml
kubectl describe pod -l app=myapp

Check event messages first. They reveal certificate, DNS, or authentication failures quickly.

End-to-End Local Build and Deploy Loop

After trust setup, streamline your daily workflow with a repeatable sequence so developers do not troubleshoot certificates repeatedly.

1# Build image locally
2docker build -t registry.dev.local:5000/myapp:dev .
3
4# Push to local registry
5docker push registry.dev.local:5000/myapp:dev
6
7# Restart deployment to force pull
8kubectl rollout restart deployment/myapp
9kubectl rollout status deployment/myapp

If pull failures reappear after Minikube restarts, re-check CA files in the node and confirm runtime service restarts were applied. Automating CA copy and trust refresh in a setup script can remove manual drift between team members.

For teams using multiple Minikube profiles, repeat trust configuration per profile because each profile has isolated node state.

Common Pitfalls

A common pitfall is certificate host mismatch. If cert CN or SAN does not match the host in image names, TLS validation fails.

Another issue is trusting the CA on your laptop but not inside Minikube node runtime. Kubernetes pulls happen inside node runtimes, not from your local terminal session.

Some setups also forget DNS mapping for custom registry host names. If Minikube cannot resolve the hostname, trust configuration alone will not help.

Finally, avoid disabling TLS verification except for temporary local debugging. Proper trust setup is safer and closer to production behavior.

Summary

• Self-signed registry workflows require explicit CA trust on Minikube nodes.
• Match certificate host names with image registry host names exactly.
• Validate pulls directly on node runtime before debugging Kubernetes YAML.
• Use pod events to pinpoint certificate, auth, or DNS issues.
• Keep TLS verification enabled and fix trust instead of bypassing security.