How does DNS work in Kubernetes?
Kubernetes DNS is a cluster add-on, almost always CoreDNS, that runs as Pods in the kube-system namespace behind a Service named kube-dns. The kubelet writes each Pod’s /etc/resolv.conf to use that Service as its nameserver, with search domains for the Pod’s namespace, so a Pod can reach a Service as api, api.shop or api.shop.svc.cluster.local. CoreDNS answers names in the cluster domain from the Kubernetes API and forwards every other name to upstream resolvers.
The parts involved
- CoreDNS runs as a Deployment. Its kubernetes plugin watches Services and EndpointSlices through the API and answers from memory.
- The
kube-dnsService gives CoreDNS a fixed cluster IP. The Kubernetes documentation keeps the old name for compatibility with workloads that expect it. - The kubelet passes that IP to every Pod through its
--cluster-dnssetting, and the cluster domain,cluster.localby default, through--cluster-domain. - The Corefile in the
corednsConfigMap configures CoreDNS. The default one answers cluster names with a 30 second TTL, forwards other names to the resolvers in the node’s/etc/resolv.confand caches answers for 30 seconds.
Which names exist
The DNS for Services and Pods page defines the record formats. With the default cluster domain:
| Object | Name | Answer |
|---|---|---|
| Service with a cluster IP | api.shop.svc.cluster.local | A or AAAA record with the cluster IP |
| Headless Service | postgres.db.svc.cluster.local | One A or AAAA record per ready Pod |
| Named Service port | _http._tcp.api.shop.svc.cluster.local | SRV record with the port number and target name |
| StatefulSet Pod behind a headless Service | postgres-0.postgres.db.svc.cluster.local | The Pod’s IP |
| Any Pod, by IP | 10-1-2-3.shop.pod.cluster.local | The Pod’s IP, if CoreDNS serves Pod records |
ExternalName Service | orders-db.shop.svc.cluster.local | CNAME to the external hostname |
Only ready Pods get records, unless the Service sets publishNotReadyAddresses: true. The article on Kubernetes Service types explains when to use a headless or ExternalName Service.
What a Pod’s resolv.conf contains
A Pod in the shop namespace gets a file like this:
nameserver 10.96.0.10
search shop.svc.cluster.local svc.cluster.local cluster.local
options ndots:5The search list is why short names work. A lookup for api is tried as api.shop.svc.cluster.local first, and api.billing becomes api.billing.svc.cluster.local on the second search domain.
Why external lookups cost extra queries
ndots:5 tells the resolver to try the search domains first for any name with fewer than five dots. External names rarely have five dots, so a lookup for api.stripe.com goes through this sequence:
api.stripe.com.shop.svc.cluster.local: NXDOMAINapi.stripe.com.svc.cluster.local: NXDOMAINapi.stripe.com.cluster.local: NXDOMAINapi.stripe.com: answered
Most resolvers ask for the IPv4 and IPv6 records separately, so one external lookup can become eight queries to CoreDNS. For services that call external APIs at high rates, that multiplies DNS load and adds latency to every new connection. Three fixes, from narrowest to broadest:
Write external names as fully qualified with a trailing dot, such as
api.stripe.com., which skips the search list. Some HTTP clients and TLS libraries handle the trailing dot badly, so test it.Lower
ndotsfor the Pod withdnsConfig:spec: dnsConfig: options: - name: ndots value: "2"Short in-cluster names such as
apiandapi.shopstill resolve through the search list.Run a node-level DNS cache, described below, so the extra queries stay on the node.
DNS policies
The dnsPolicy field on a Pod chooses where its DNS settings come from:
| Policy | Behavior |
|---|---|
ClusterFirst | The default. Cluster DNS with the search list above |
Default | Inherits the node’s resolver configuration. Despite its name, it is not the default |
ClusterFirstWithHostNet | Required for Pods with hostNetwork: true that need cluster names; without it they fall back to Default |
None | Ignores Kubernetes settings and uses only the Pod’s dnsConfig |
Since Kubernetes 1.28, a Pod can have up to 32 search domains with a total length of 2,048 characters.
NodeLocal DNSCache
Every lookup normally travels to a CoreDNS Pod, often on another node, through the kube-dns virtual IP. On iptables-based nodes that path uses NAT and connection tracking, and dropped UDP packets lead to timeouts that the NodeLocal DNSCache documentation puts at “usually up to 30s”.
NodeLocal DNSCache, stable since Kubernetes 1.18, runs a caching CoreDNS instance as a DaemonSet on every node and listens on a link-local address such as 169.254.20.10. Pods query their own node, avoiding the NAT path, and the cache talks to the central CoreDNS over TCP. It also gives per-node DNS metrics. Clusters with many Pods or heavy external lookups benefit most.
Common failure modes
| Symptom | Usual cause |
|---|---|
| Every lookup times out after you apply a network policy | A default-deny egress policy blocks UDP and TCP port 53 to CoreDNS; see how to set a default deny with network policies |
| CoreDNS Pods restart with a loop error | The node’s /etc/resolv.conf points at a local stub resolver such as systemd-resolved, so CoreDNS forwards to itself and its loop plugin stops it; see what CrashLoopBackOff means |
| Large responses fail in some images | Alpine 3.17 and earlier ship a musl resolver without TCP fallback, so answers over 512 bytes fail; the Kubernetes docs recommend Alpine 3.18 or later |
| Intermittent 5 to 30 second delays | Dropped UDP packets or conntrack races on busy nodes, or too few CoreDNS replicas for the query rate |
| A new Service is not found for a few seconds | Negative answers and records are cached by CoreDNS and by client libraries |
| External names fail, cluster names work | The upstream resolvers that CoreDNS forwards to are unreachable or blocked |
To test from inside the cluster, start a debug Pod with DNS tools and query a name that always exists, such as kubernetes.default.svc.cluster.local, then an external name. Compare the result with kubectl -n kube-system logs for the CoreDNS Pods.
DNS on Cloudfleet
On Cloudfleet Kubernetes Engine (CFKE), the CoreDNS Pods carry the label k8s-app: coredns, which the network policies guide uses in its DNS allow rule. For names outside the cluster, nodes and CoreDNS use public resolvers, and Enterprise clusters can use their own resolvers instead, as listed in the self-managed nodes requirements.