Installing Docker Registry with Helm¶

In my homelab, I'm setting up a private Docker registry using Helm to efficiently store and manage container images. This registry allows me to host and distribute container images within my Kubernetes cluster.

Prerequisites¶

Before installing the Docker Registry, ensure the following prerequisites are met:

A functional Kubernetes cluster with K3s, including a master node and one or more worker nodes.
Helm, the Kubernetes package manager, installed on the master node.
SSH access to the master node.

Installation¶

I'll install the Docker Registry using Helm by following these steps:

Add the Docker Registry Helm Repository¶

I'll begin by adding the Docker Registry Helm chart repository to Helm:

helm repo add docker-registry https://twuni.github.io/docker-registry.helm
helm repo update

Now, Helm is aware of the Docker Registry Helm chart.

Create a Values YAML File¶

Create a custom values file like this:

persistence:
  enabled: true
  size: 10Gi

ingress:
  enabled: true
  ingressClassName: "traefik"
  hosts:
    - host: registry.fromej.nl
      paths:
        - /
  tls:
    - hosts:
      - registry.fromej.nl
      secretName: wildcard-fromej-tls

In this custom values file:

persistence is enabled, specifying a persistent volume size of 10Gi.
ingress is enabled with the ingressClassName set to "traefik" to use Traefik as the Ingress controller.
The hosts section defines the host as registry.fromej.nl and the path as /.
The tls section specifies TLS configuration with the host as registry.fromej.nl and the secret name as wildcard-fromej-tls.

Install the Docker Registry with Distribution¶

Run the following command to install the Docker registry using Helm and the values file you created:

helm install my-distribution distribution/docker-distribution -f registry-values.yaml

Replace my-distribution with a name of your choice.

Access the Docker Registry¶

To access your private Docker registry, you'll need to configure Docker to authenticate with the registry and provide the necessary credentials. Here's how you can do it:

Use the docker login command to log in to your private registry. Replace registry.fromej.nl with your registry's hostname and provide your username and password or authentication token as needed.

docker login registry.fromej.nl

You will be prompted to enter your credentials.

Pull Images¶

After logging in, you can use docker pull to retrieve images from your private registry. Specify the full image name, including the registry's hostname and image tag:

docker pull registry.fromej.nl/my-image:tag

Replace my-image with the name of the image you want to pull and tag with the image's version or tag.

Push Images¶

To push images to your private registry, use the docker push command. After building and tagging your Docker image, push it to the registry:

docker push registry.fromej.nl/my-image:tag

This command pushes the image to your private registry, making it available for deployment on your Kubernetes cluster.

Deploy to Kubernetes¶

When deploying your applications on your Kubernetes cluster, ensure that your Kubernetes manifests specify the image path with the hostname of your private registry. For example:

spec:
  containers:
    - name: my-container
      image: registry.fromej.nl/my-image:tag

By specifying the full image path in your Kubernetes manifests, your cluster will be able to pull the image from your private registry when deploying pods.

With these steps, you can access and manage your private Docker registry, pulling and pushing container images as needed for your applications running in your homelab Kubernetes cluster.

Adding a private registry to K3s¶

Based on k3s docs

Adding a private registry is done through adding them to registries.yaml. This should be in /etc/rancher/k3s/.

Standard this file does not exist, so we create it first on our master node:

touch /etc/rancher/k3s/registries.yaml

With your favorite editor edit the file. Here is the yaml file i have created for my own Gitea registry.

mirrors:
  git.fromej.nl:
    endpoint:
      - "https://git.fromej.nl"
configs:
  "git.fromej.nl":
    auth:
      username: <my_user>
      password: <super_secret_password>

Some explenation on the structure

mirrors: these should contain the url of your registry placed in the endpoint attribute
configs: add the username and password you normally use to login to your registry

registry.yaml should be on every node

It's important to have this registry.yaml file on every node, since it will fail pulling images on that node if the file is not there. This will result in ImagePullBackOff statusses if the pod is scheduled on a node that does not contain the registry.yaml

Copying `registry.yaml` to workers¶

In comes ansible again

Make sure the directory exists

ansible workers -b -m file -a "path=/etc/rancher/k3s state=directory"

Copy the file

ansible workers -b -m copy -a "src=/etc/rancher/k3s/registries.yaml dest=/etc/rancher/k3s/registries.yaml"

Restart K3s services¶

The registry file is only loaded into K3s on startup, so we need to reboot the services

On the master node

systemctl restart k3s

For restarting the worker nodes services

ansible workers -b -m shell -a "systemctl restart k3s-agent"

cluster-2 | CHANGED | rc=0 >>

cluster-1 | CHANGED | rc=0 >>

cluster-3 | CHANGED | rc=0 >>