Kubernetes Service DNS Discovery

Kubernetes Service DNS Discovery refers to the specific implementation of DNS resolution for Kubernetes Services, covering the cluster DNS component, the exact record schema it publishes, and the resolver configuration injected into every pod that makes short-name lookups work automatically without hardcoded addresses.

Cluster DNS Component

CoreDNS as the Default Implementation

Kubernetes clusters run a cluster DNS service, most commonly CoreDNS, deployed as pods within the kube-system namespace and exposed through its own ClusterIP Service, typically named kube-dns for historical compatibility even when CoreDNS is the actual implementation running behind it.

kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl get service kube-dns -n kube-system

Watching the API for Record Generation

CoreDNS watches Service and EndpointSlice objects through the Kubernetes API and dynamically generates corresponding DNS records, meaning DNS records are never manually authored for Services — they are derived entirely from cluster state and updated automatically as Services and their endpoints change.

DNS Record Schema

Fully Qualified Domain Name Structure

Every Service receives a fully qualified domain name following a fixed pattern: <service-name>.<namespace>.svc.<cluster-domain>, where <cluster-domain> defaults to cluster.local unless explicitly configured otherwise at cluster creation.

ledger-api.prod-payments-ledger.svc.cluster.local

A and AAAA Records for ClusterIP Services

A standard ClusterIP Service resolves to an A record (or AAAA for IPv6) pointing directly at its stable virtual IP, meaning repeated lookups of the same Service name return the same address regardless of backing pod churn, since the ClusterIP itself does not change.

SRV Records for Named Ports

CoreDNS also publishes SRV records for each named port on a Service, encoding the protocol and port name into the record name, which allows consumers to discover both an address and the correct port for a named port without hardcoding the port number separately.

nslookup -type=SRV _http._tcp.ledger-api.prod-payments-ledger.svc.cluster.local

Multiple A Records for Headless Services

For headless Services (clusterIP: None), DNS instead returns multiple A records, one per ready backing pod, rather than a single virtual IP, allowing a resolver to enumerate individual pod addresses directly.

nslookup ledger-db.prod-payments-ledger.svc.cluster.local

Per-Pod DNS Records for StatefulSets

When a headless Service fronts a StatefulSet, each pod additionally receives its own stable per-pod DNS name, combining the pod's ordinal hostname with the Service name, allowing a specific StatefulSet member to be addressed individually and consistently across restarts.

ledger-db-0.ledger-db.prod-payments-ledger.svc.cluster.local

Pod-Side Resolver Configuration

Injected resolv.conf

Every pod, unless explicitly configured otherwise, has its /etc/resolv.conf populated by the kubelet to point at the cluster DNS Service's ClusterIP as the nameserver, along with a search list that enables short-name resolution.

nameserver 10.96.0.10
search prod-payments-ledger.svc.cluster.local svc.cluster.local cluster.local
options ndots:5

The ndots Option and Lookup Cost

The ndots:5 option instructs the resolver to first attempt each search domain suffix for any name with fewer than five dots before falling back to treating the name as fully qualified, which is why a short name like ledger-api triggers several sequential DNS queries — one per search suffix — before finally resolving, a detail relevant to diagnosing DNS-related latency in high-throughput workloads.

dnsPolicy Configuration

A pod's dnsPolicy field controls whether it uses the cluster DNS resolver at all; ClusterFirst, the default, routes cluster-domain queries to CoreDNS and falls back to the node's upstream DNS for external names, while Default bypasses cluster DNS entirely, inheriting the node's own resolver configuration instead.

spec:
  dnsPolicy: ClusterFirst

Custom DNS Configuration

dnsConfig for Fine-Grained Overrides

The dnsConfig field allows a pod to append additional nameservers, search domains, or resolver options on top of whatever dnsPolicy provides, used when a workload needs to resolve names from an external DNS zone not otherwise reachable through the cluster's default resolver chain.

spec:
  dnsPolicy: ClusterFirst
  dnsConfig:
    nameservers:
      - 10.10.0.53
    searches:
      - internal.partner-network.example.com

Caching Behavior

Local Resolver Caching

Many cluster configurations deploy a per-node DNS caching layer (such as NodeLocal DNSCache) in front of the central CoreDNS deployment, reducing per-lookup latency and CoreDNS load for high-QPS workloads, while still deferring to CoreDNS as the authoritative source for any cache miss.