Your own Docker registry with Kubernetes and Rancher

TL;DR: Deploy a private docker registry in just 5 minutes!

Image for post
Image for post
Containers, containers, containers!

Why your own private registry?

The main reason is for privacy.

If your are working with private code, you need to use a private registry. Among the available options we have Docker Hub, Azure Container Registry, GitLab … and your cluster!

Other reason is the flexibility.

I prefer my own registry in my cluster because we use a lot of containers for our DevOps cycle: testing, pipelines, etc. If you use a cheap cloud provider for the storage in the cluster, you have a private registry with endless possibilities.


  • A Kubernetes cluster managed by Rancher.
    If you haven’t it, use the following post to create one in just 15 minutes.
  • Cert-manager installed in the cluster.
    Not already? No problem, follow this guideline
  • A domain/subdomain to use for your registry.
  • 5 minutes? Do you have it? Great, let’s go!

1. Redirect your domain

I don’t like to remember IP addresses. And you?

We’ll use the subdomain “” for our registry.

You need to enter in your domain provider portal where the domain “” was registered and add a A DNS record or CNAME record.

The IP address or CNAME domain/subdomain must point to your load balancer IP in your cluster.

Made the association, it is only a matter of minutes that it is already ready.

You can check it with “nslookup” CLI tool. For example, if we associate the IP to “”, we obtain an output like the following.

% nslookup
Non-authoritative answer:

2. Install Docker Registry

Enter in your Rancher panel and go to your cluster. Then, access to the namespace where you will create the registry. For example, “default”.

Click in “App” and then in the “Launch” button.

Search for the “docker-registry” app.

Image for post
Image for post
Here is our target!

Select it to prepare the installation.

We use the following settings:

  • Name: docker-registry
  • Namespace: default
  • Secret settings. Here we need to specify a “htpasswd” format user:secret. In our example, we create the user “admin” with the password “itsasecret”.
    You can get it with the following command. Put the output (admin:$2…10K) in the field “Docker Registry Htpasswd Authentication”
% docker run --rm --entrypoint htpasswd registry:2 -Bbn admin itsasecret
  • Check “Persistent Volume Enabled” for use an external volume. In our case, we use Hetzner storage class “hcloud-volumes” as “Default StorageClass for Docker Registry”. About the size of the image, use 50GB for example.
  • In “Services and load balancing”, just select “ClusterIP” for “Docker Registry Service Type”. We setup the load balancer in the next step.

All right! Just press on “Launch” and wait until the pod is running.

Image for post
Image for post
Preview of Docker Registry settings before launch

3. Setup the ingress

Right now our container only works internally in our cluster.

We’ll specify a nginx-ingress to access it from everywhere.

Here the keys are in:

  • Cert-manager annotation for request a “Let’s Encrypt” free TLS certificate.
  • TLS options for store the certificate and specify the domain
  • Service settings: service name and port.

We apply it

% kubectl apply -f ingress-docker-registry.yaml

4. Upload your first image

Ready to test your docker registry?

We use the “hello-world” docker container.

First, we need to login to your registry with the credentials. In our example: admin / itsasecret.

% docker login
Username: admin
Login Succeeded

Before upload, we get the image.

% docker pull hello-worldUsing default tag: latest
latest: Pulling from library/hello-world
0e03bdcc26d7: Pull complete
Digest: sha256:6a65f928fb91fcfbc963f7aa6d57c8eeb426ad9a20c7ee045538ef34847f44f1
Status: Downloaded newer image for hello-world:latest

Now, we need to add a tag under our registry domain.

% docker tag hello-world:latest

The real test, the “push it!”

% docker push
The push refers to repository []
9c27e219663c: Pushed
latest: digest: sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042 size: 525

Voilá! Your own private docker registry works!

Please, if you liked it, give it a round of applause. And if you want to know more about DevOps, Kubernetes, Docker, etc … follow me! KR

Image for post
Image for post

Written by

CTO @ & Beyond-Full-stack developer #go #python #kubernetes

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store