Automating local domains for minikube

Ingress configuration and domain-based routing are an essential feature of the kubernetes ecosystem. While they are important enough to be included as minikube addons out of the box, integrating them seamlessly in a local testing setup is not exactly intuitive.

Preparing minikube

To get automated domains working, we first need to ensure minikube is up and the necessary addons are enabled. First start minikube:

minikube start

Ensure it is running properly with

kubectl get nodes

This should show one node as output:

NAME      STATUS  ROLES          AGE  VERSION
minikube  Ready   control-plane  8h   v1.28.3

Next enable the ingress and ingress-dns addons:

minikube addons enable ingress
minikube addons enable ingress-dns

Verify that they were installed properly by running

minikube addons list

The installed addons should be marked with a green checkmark icon.

Host setup with NetworkManager

To get our automated local domains to work, we need to instruct the host system to use our minikube instance as a DNS server for the local domain. Most linux distributions will include NetworkManager, check if yours does by running

systemctl status NetworkManager.service

If this shows a running service, you can install the configuration as a dnsmasq plugin:

sudo mkdir /etc/NetworkManager/dnsmasq.d/
echo "server=/kube/$(minikube ip)" | sudo tee /etc/NetworkManager/dnsmasq.d/minikube.conf

Next, ensure that the file /etc/NetworkManager/NetworkManager.conf contains the line dns=dnsmasq in the [main] section, it should look similar to this:

[main]
dns=dnsmasq

And finally, restart the NetworkManager service to apply the changes

systemctl restart NetworkManager.service

Your host will now automatically resolve every minikube ingress ending in .kube.

Host setup with resolvconf

If your host does not have NetworkManager installed, you may be running resolvconf for dns resolution instead - this can also be used to automate local minikube ingress domains. First, append the local dns config to your resolvconf base:

echo -e "search kube\nnameserver $(minikube ip)\ntimeout 5" >> /etc/resolvconf/resolv.conf.d/base

Then just update the resolvconf config:

sudo resolvconf -u

Your host will now automatically resolve every minikube ingress ending in .kube.

Testing the setup

Now that both minikube and the host are configured, let's test if the setup is working. We will deploy a simple test app with an ingress using the sample.kube domain. Note that since we set up minikube for dns resolution, you should not need to manually add sample.kube to /etc/hosts, it should be working automatically.

Start by deploying a sample application

kubectl create deployment web --image=gcr.io/google-samples/hello-app:1.0

Expose a ClusterIP service for it

kubectl expose deployment web --type=ClusterIP --port=8080

And create an ingress routing traffic from sample.kube to the service

kubectl create ingress web --rule="sample.kube/=web:8080" --class=nginx

If your configuration is correct, you should now be able to access http://sample.kube in your browser and see the "Hello, world" message from the application we just deployed.

Your new automated local domain resolution can handle all domains ending in .kube without ever touching /etc/hosts again. This is also true for subdomains of any nesting depth, for example deploying an ingress for a.b.c.d.e.kube will also resolve normally to your minikube ingress.