Custom DNS

CFKE runs CoreDNS on every node as the cluster DNS server. Pods use the CoreDNS instance on their own node. CoreDNS answers cluster names such as SERVICE.NAMESPACE.svc.cluster.local and forwards all other names to the node’s upstream resolvers.

You can extend this configuration with a coredns-custom ConfigMap in the kube-system namespace. Typical uses are forwarding a private zone to your own DNS servers, adding static host entries, or logging queries.

The coredns ConfigMap itself is managed by CFKE and cannot be edited.

How it works

CoreDNS imports every key of the coredns-custom ConfigMap by its suffix:

Key suffixImported asUse for
.serverAn additional server blockZones with their own upstream, such as a private domain
.overridePlugins inside the default server blockSettings for all names, such as hosts, rewrite or log

A ConfigMap can hold several keys of both kinds. Changes take effect within about a minute on every node, without restarting CoreDNS.

Forward a private zone

The following example sends all queries for corp.example.com to two DNS servers in your network:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  corp.server: |
    corp.example.com:53 {
        errors
        cache 30
        forward . 10.20.0.2 10.20.0.3
    }    

CoreDNS sends these queries from the node, so the DNS servers must be reachable from every node, for example through a VPN or a self-managed node in your network. To use DNS over TLS, write the upstream as tls://IP and add tls_servername inside the forward block.

Add static host entries

An .override key adds plugins to the default server block. The following example resolves two names to fixed addresses and passes every other name on:

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  hosts.override: |
    hosts {
        10.20.0.15 legacy-db.corp.example.com
        10.20.0.16 legacy-api.corp.example.com
        fallthrough
    }    

Without fallthrough, CoreDNS answers no other names.

Apply and verify

bash
kubectl apply -f coredns-custom.yaml

After about a minute, resolve a name from a Pod:

bash
kubectl run dns-test --rm -it --restart=Never --image=busybox:1.36 -- nslookup legacy-db.corp.example.com

To remove the customization, delete the ConfigMap. CoreDNS returns to the default configuration within about a minute.

Troubleshooting

CoreDNS checks each change before applying it. When a snippet contains an error, running CoreDNS Pods keep their last working configuration and log the error. A CoreDNS Pod that starts while the error is present fails to start until you fix or delete the ConfigMap. Check the logs after every change:

bash
kubectl logs -n kube-system -l k8s-app=coredns --tail=20

Avoid these common mistakes:

  • A .server key must not declare the zone .. The default server block already serves it, so CoreDNS rejects the duplicate.
  • Do not declare cluster.local in a .server key. The new block takes over all cluster names from the default server block, and Service discovery stops working.
  • Most plugins can appear only once per server block. An .override key that adds a plugin the default block already uses, such as cache, is rejected.

For the full list of plugins and their options, see the CoreDNS documentation.

On this page