This article is also available in German: Was ist eine private Docker Registry…?

Introduction

Containers form the backbone of modern cloud infrastructures – whether you’re running applications, microservices, or databases.
For containers to work efficiently, their images must be stored, versioned, and managed in a central location.
This is exactly what Docker Registries are for.

With K3Nova, our interactive CLI tool, you can not only install production-ready K3s clusters but also automatically provision your own private Docker Registry that seamlessly integrates into your cluster.

In this article, you’ll learn:

• What a Docker Registry is
• Which types of registries exist
• Why having your own private registry makes sense
• How K3Nova automates the setup of a private registry
• How to build, push, and use your own container images in the cluster

What is a Docker Registry?

A Docker Registry is a central repository where container images are stored, managed, and distributed.
It acts as a “library” for your images and allows you to:

• Store → Images are versioned and stored centrally
• Share → Developers, CI/CD pipelines, and clusters can access them
• Manage → Control access rights, tags, and versions
• Deploy → Images can be pulled from any host using docker pull or containerd

Examples of public registries

• Docker Hub
• GitHub Container Registry
• Google Artifact Registry
• Quay.io

These platforms are convenient, but in production environments they often pose challenges: no full control, dependency on third parties, and sometimes limitations on speed and access.

Why having your own private registry makes sense

Especially in Kubernetes clusters – particularly when dealing with sensitive data or proprietary code – it’s highly recommended to host your own images internally.

Advantages of a private Docker Registry:

• Security You decide who gets access
• Speed Images are loaded directly from your local network
• Stability No dependency on external registries
• Integration Perfectly integrated into CI/CD pipelines
• Cost control No rate limits like on Docker Hub

Docker Registry in K3Nova

If you run container images in your Kubernetes cluster, you need a central solution to provide those images.
Docker Registries enable exactly that – and with K3Nova, you can seamlessly integrate your own local private registry into your K3s cluster.

The benefits:

• No external dependencies
• Faster image provisioning
• Perfect integration with Traefik and Kubernetes
• Access via registry.local:5000 without additional TLS configuration

Requirements

• A working K3s cluster, installed e.g. with K3Nova
• Traefik as the Ingress Controller (automatically integrated via K3Nova)
• Cert-Manager (optional, only required for public HTTPS usage)
• NFS Provisioner for PVC or another Persistent Volume (PV)
• k3nova-config.json with enabled local registry support

{
  "docker_registry": {
    "local": true,
    "url": "registry.local",
    "pvc_storage_capacity": "10Gi",
    "user": "registry",
    "pass": "123456"
  }
}

Step 1 – Configure /etc/hosts

To resolve registry.local on your local machine, add an entry to the /etc/hosts file:

sudo tee -a /etc/hosts <<EOF
# Local Docker Registry
<IP-of-first-control-plane-node>   registry.local
EOF

Note:
Replace <IP-of-first-control-plane-node> with the IP address of your first control-plane node.

Step 2 – Enable insecure registry

Since we are running the local registry without TLS, Docker needs to explicitly allow this connection.

Docker Desktop (macOS / Windows)

1. Open Settings → Docker Engine
2. Add the following to the JSON section:

{
  /* ... existing settings ... */
  "features": {
    "buildkit": true
  },
  "insecure-registries": ["registry.local:5000"]
}

3. Click Apply & Restart.

Docker CLI / Linux

On Linux, you can configure it directly:

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "insecure-registries": ["registry.local:5000"]
}
EOF
sudo systemctl restart docker

Step 3 – Install local registry with K3Nova

Start K3Nova:

k3nova

Select in the interactive menu:
📦 Install Local Docker Registry

K3Nova automatically handles:

• Deployment of the registry in the cluster
• Configuration of the IngressRouteTCP via Traefik
• Service setup at registry.local:5000
• Persistent storage via NFS

Step 4 – Use the registry

1. Log in

docker login registry.local:5000

If authentication is configured, provide your username and password.

2. Build image

Assuming you have a Go-based API project:

docker build -t registry.local:5000/my-api:v1 .

3. Push image

docker push registry.local:5000/my-api:v1

4. Use image in the cluster

Once the image is in your local registry, you can use it directly in deployments or stateful sets:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-api
  template:
    metadata:
      labels:
        app: my-api
    spec:
      containers:
        - name: my-api
          image: registry.local:5000/my-api:v1
          ports:
            - containerPort: 8080

Step 5 – Kubernetes imagePullSecrets

If you secured your local registry with username/password, Kubernetes needs to know the credentials.

1. Create secret

kubectl create secret docker-registry my-private-docker-registry \
  --docker-server="http://registry.local:5000" \
  --docker-username="myuser" \
  --docker-password="mypassword" \
  --namespace="default"

2. Reference secret in the deployment

spec:
  imagePullSecrets:
    - name: my-private-docker-registry

Step 6 – Integration with Traefik

K3Nova integrates your registry seamlessly via IngressRouteTCP.
Traffic on registry.local:5000 is directly routed to the internal registry service in the cluster.
Advantage: No manual routing, no additional load balancers, full control.

Best practices with Docker Registry & K3Nova

• Use TLS → Even though K3Nova supports HTTP, HTTPS is recommended for production.
• Use versioning → Always work with proper image tags (v1, v2, latest).
• Automate with CI/CD → Use GitHub Actions or GitLab CI to push images directly to the registry.
• Monitor storage → The registry can grow quickly; plan enough storage capacity.
• Set up backups → K3Nova can automate NFS snapshots.

Conclusion

Having your own Docker Registry gives you full control over your container images and makes your Kubernetes workflow more stable, faster, and secure.
With K3Nova, setting it up couldn’t be easier: one click in the CLI, and you get a fully integrated private registry within your cluster.