K3s – Add a private DNS entry – CoreDNS

Managing Custom DNS in K3s with CoreDNS

In a local development environment or home lab, you often lack a dedicated DNS server. Eventually, you’ll need your Kubernetes pods to resolve external resources—like a local Gitlab instance or a NAS—by hostname rather than IP.

In K3s, the easiest way to handle this is by modifying the CoreDNS ConfigMap. Think of this as the cluster-wide equivalent of an /etc/hosts file.

1. Edit the CoreDNS Configuration

To add custom host entries, you need to edit the CoreDNS configuration directly:

kubectl edit cm coredns -n kube-system

2. Add Your Custom Hosts

Look for the NodeHosts section in the YAML. This section maps IP addresses to hostnames. Add your entries following the existing pattern. In this example, I’ve added gitlab.home:

  NodeHosts: |
    192.168.0.2 controller-node
    192.168.0.3 node-01
    192.168.0.4 gitlab.home
kind: ConfigMap

3. Apply the Changes

CoreDNS doesn’t always pick up ConfigMap changes instantly. To force the new DNS settings to take effect, restart the deployment:

kubectl rollout restart deployment coredns -n kube-system

4. Verify the Setup

The best way to test if your pods can see the new hostname is by running a temporary busybox pod to perform a lookup:

kubectl run busybox --image=busybox:1.28 --restart=Never --rm -it -- nslookup gitlab.home

More info on CoreDNS – https://coredns.io/