Kubernetes DNS Explained: CoreDNS and Service Name Resolution
Learn Kubernetes DNS, CoreDNS, Service name resolution, namespaces, search domains, headless Services, SRV records and DNS troubleshooting with practical examples.
Kubernetes DNS Explained: CoreDNS and Service Name Resolution
Understand how Kubernetes turns Service names into usable network endpoints, how CoreDNS integrates with the Kubernetes API, and how to troubleshoot DNS failures.
Introduction
In a Kubernetes cluster, applications rarely communicate by hard-coding the IP address of another Pod or Service. Pods can be recreated, Services can have changing backend endpoints, and applications are often distributed across namespaces. Kubernetes DNS provides a consistent naming mechanism so workloads can discover Services using names.
CoreDNS is the DNS server commonly deployed as the Kubernetes cluster DNS add-on. Kubernetes publishes information about Services and Pods that can be used by cluster DNS, while kubelet configures Pod DNS settings so containers can resolve Services by name. The CoreDNS Service itself is named `kube-dns` for historical compatibility.
This article explains the complete resolution path, DNS names, namespaces, search domains, CoreDNS, Service records, headless Services, SRV records, troubleshooting, and practical production considerations.
1. What Is Kubernetes DNS?
Kubernetes DNS is the cluster DNS system that provides DNS records for Kubernetes resources such as Services and, depending on the configured DNS implementation and resource, Pods. It allows an application to use a stable DNS name instead of relying on a changing IP address.
• A Service gets a predictable DNS name.
• A Pod can query the cluster DNS server using its configured DNS settings.
• CoreDNS watches Kubernetes resources and serves DNS answers for the configured cluster domain.
• Service DNS records provide stable discovery even when backend Pod IPs change.
Kubernetes documentation specifies DNS behavior for Services and Pods, including namespace-qualified names, normal Services, headless Services and SRV records.
2. Why DNS Is Important in Kubernetes
Imagine an application named `frontend` that calls an API running in three Pods:
Those Pod IP addresses are not a stable application interface. During a Deployment rollout or Pod replacement, the backend Pods can change. Instead of putting those addresses into application configuration, create an `api` Service and have the frontend call `api`.
The application now depends on a stable logical name while Kubernetes maintains the changing backend endpoint set.
3. CoreDNS: The DNS Server in Kubernetes
CoreDNS is commonly deployed as the Kubernetes DNS add-on. The Kubernetes documentation notes that the Service for CoreDNS is named `kube-dns` for backward compatibility with the older kube-dns add-on.
The label `k8s-app=kube-dns` is retained for compatibility even when the DNS implementation is CoreDNS.
The CoreDNS configuration is commonly stored in a ConfigMap named `coredns` in the `kube-system` namespace. The exact Corefile contents can vary by Kubernetes distribution and cluster configuration.
4. High-Level DNS Resolution Flow
The DNS part of the process determines the address associated with the requested DNS name. For a normal Service, the DNS answer points to the Service cluster IP. Service traffic routing then takes place through the Kubernetes Service dataplane.
DNS resolution and Service traffic routing are therefore related but distinct layers.
5. How a Pod Gets Its DNS Configuration
kubelet configures Pod DNS settings. A typical Pod using cluster DNS receives a `/etc/resolv.conf` containing a cluster DNS nameserver and DNS search domains.
A configuration may look similar to:
The exact nameserver, search domains and additional entries depend on the cluster configuration. `cluster.local` is the common default cluster domain, but Kubernetes allows another cluster domain to be configured.
6. Kubernetes DNS Search Domains
Search domains make short Service names practical. Suppose a client Pod is running in the `frontend` namespace and needs to call a Service named `api` in the same namespace.
The DNS resolver can use the Pod's search list to expand the short name. A query for `api` can therefore resolve to the Service in the client's namespace.
The search behavior is controlled by the Pod's DNS configuration and the resolver's behavior. Kubernetes commonly configures `ndots:5`, which affects when the resolver attempts search-list expansion.
7. Kubernetes Service DNS Names
For a normal Service, Kubernetes defines DNS names in the following general form:
For example, with Service `orders`, namespace `production`, and cluster domain `cluster.local`:
Kubernetes documentation states that normal Services receive A and/or AAAA records depending on the Service IP families, and those records resolve to the Service cluster IP.
8. Short Name vs Namespace-Qualified Name vs FQDN
The short name is convenient for applications inside the same namespace. The namespace-qualified form is useful when crossing namespace boundaries. The fully qualified name is useful for diagnostics and configurations where an explicit DNS identity is desirable.
9. Namespace Is Part of Service Discovery
DNS queries that do not specify a namespace are limited to the namespace of the Pod making the query. Consider:
This query looks for `api` in the `frontend` namespace:
To resolve the Service in `backend`, specify its namespace:
Or use:
A large number of Kubernetes DNS incidents are caused by an application using a short name when the target Service is in another namespace.
10. Normal Service DNS Resolution
A normal Service has a cluster IP. Suppose:
The DNS name `orders.production.svc.cluster.local` resolves to the Service cluster IP. Traffic sent to that cluster IP is then handled by the Service dataplane and forwarded toward appropriate backend endpoints.
The DNS response is therefore not a list of all backend Pod IPs for a normal Service. The client normally receives the Service's stable cluster IP.
11. Headless Services
A headless Service is created with `clusterIP: None`.
Unlike a normal Service, the DNS record for a headless Service resolves to the set of IP addresses of the selected Pods. This is useful when clients need endpoint-level discovery instead of a single virtual Service IP.
Headless Services are commonly relevant to StatefulSet-based systems and distributed applications that need to identify individual members.
12. Service DNS and StatefulSets
StatefulSets provide stable network identities for their Pods. When a StatefulSet uses a headless Service, DNS can expose stable names associated with individual Pods.
For example, a StatefulSet Pod might have a DNS identity following the pattern:
The exact name depends on the StatefulSet, Service, namespace and cluster domain. This pattern is different from normal load-balanced Service access because the client can address an individual StatefulSet member.
13. SRV Records
Kubernetes DNS also supports SRV records for named Service ports. SRV records allow clients to discover both the service port and the DNS name associated with the service.
The SRV record follows the pattern:
For a normal Service, the SRV result refers to the Service DNS name. For a headless Service, SRV records can provide multiple answers corresponding to the Pods backing the Service.
SRV records are particularly useful for applications and protocols that support service discovery through DNS SRV semantics.
14. Pod DNS Names
Kubernetes also defines DNS behavior for Pods. Pod DNS records are more specialized than Service discovery and should not normally replace Service-based application communication.
A common application pattern is to use a Service as the stable interface and let Kubernetes manage the changing backend Pod set. Pod-specific DNS names become more relevant for StatefulSet and headless-Service designs where individual endpoints matter.
15. CoreDNS and the Kubernetes API
CoreDNS needs Kubernetes resource information to answer cluster DNS queries. The Kubernetes DNS debugging documentation notes that CoreDNS must be able to list and watch relevant resources such as Services and EndpointSlices.
A typical CoreDNS permission set includes access to resources such as:
• services
• endpoints
• endpointslices.discovery.k8s.io
• pods
• namespaces
If these permissions are missing or incorrectly configured, CoreDNS may be unable to produce correct answers for cluster resources.
16. What Is the CoreDNS Corefile?
CoreDNS is configured through a Corefile. In Kubernetes installations, the Corefile is commonly stored in the `coredns` ConfigMap in `kube-system`.
A Corefile can configure plugins responsible for Kubernetes-aware DNS, forwarding external queries, caching, health, metrics and other behavior. Do not copy a Corefile from another cluster without understanding the Kubernetes distribution and networking environment because the configuration can vary.
The Kubernetes DNS debugging documentation shows a Corefile using plugins such as `kubernetes`, `forward`, `cache`, `health`, `prometheus`, `reload`, `loop` and `loadbalance`.
17. Internal vs External DNS
Kubernetes DNS is primarily responsible for cluster-local DNS behavior. When an application queries an external domain, CoreDNS can forward queries to upstream resolvers according to its configuration.
The application does not need to know which upstream DNS server is used. It asks the DNS resolver configured in its Pod. CoreDNS can handle cluster-local names and forward queries outside the cluster as configured.
18. What Happens When a Pod Executes nslookup?
1. `nslookup` uses the resolver configuration inside the Pod.
2. The query is sent to the configured cluster DNS Service.
3. CoreDNS receives the query.
4. CoreDNS processes the Kubernetes DNS zone and resource information.
5. CoreDNS returns the DNS response.
6. The application or DNS utility receives the address.
For a normal Service, the returned address is the Service cluster IP. The subsequent connection to that IP is handled by Kubernetes Service networking.
19. DNS Resolution Does Not Guarantee Application Connectivity
A successful DNS lookup only proves that the DNS layer returned an answer. It does not prove that the application is listening, the Service has usable endpoints, a NetworkPolicy permits traffic, or the Service dataplane is functioning correctly.
20. Troubleshooting Kubernetes DNS
Use a temporary diagnostic Pod or an existing Pod with DNS tools.
Then test:
The official Kubernetes DNS troubleshooting guide uses `nslookup kubernetes.default` as a basic cluster DNS test.
21. Check the Pod DNS Configuration
Check the following:
• Is the `nameserver` pointing to the expected cluster DNS Service?
• Does the `search` line contain the expected namespace and cluster-domain suffixes?
• Is `ndots` configured as expected?
The search path can vary by cluster and cloud provider, so do not assume every cluster will show exactly the same `/etc/resolv.conf`.
22. Check CoreDNS Pods
If CoreDNS Pods are not running or are repeatedly restarting, investigate their status and logs.
The `k8s-app=kube-dns` label is used for CoreDNS for backward compatibility with the historical kube-dns add-on.
23. Check the CoreDNS Service
The Kubernetes DNS Service is named `kube-dns`, even when CoreDNS is the implementation. This is a compatibility convention, not evidence that the cluster is necessarily running the old kube-dns implementation.
24. Check CoreDNS EndpointSlices
If the DNS Service has no usable endpoints, Pods may be unable to reach the DNS server even if the DNS Pods themselves appear to exist.
25. Check CoreDNS Permissions
CoreDNS needs appropriate permissions to watch the Kubernetes resources used for DNS. Missing EndpointSlice permissions, for example, can prevent CoreDNS from correctly resolving Service backends.
If you modify RBAC, make the change only after confirming that the problem is actually an authorization problem. Avoid broad permissions simply to make DNS work.
26. Inspect CoreDNS Queries
For advanced troubleshooting, the CoreDNS configuration can be modified to enable query logging. The official Kubernetes DNS debugging guide demonstrates adding the `log` plugin to the Corefile.
After the configuration propagates, generate a DNS query and inspect the CoreDNS logs. This can help determine whether the query is reaching CoreDNS and how CoreDNS is processing it.
Query logging can produce substantial log volume, so enable it temporarily and deliberately in production environments.
27. Common DNS Failure Scenarios
28. DNS and NetworkPolicy
NetworkPolicy can affect whether Pods are allowed to communicate with the DNS Service. A workload may have correct DNS configuration and a healthy CoreDNS deployment but still fail to resolve names if its egress traffic to the cluster DNS endpoint is blocked.
When implementing restrictive egress policies, explicitly account for required DNS traffic according to the cluster's DNS architecture.
• Identify the DNS Pods or DNS Service used by the cluster.
• Allow required DNS traffic from application Pods.
• Test DNS after applying NetworkPolicy changes.
• Do not assume application connectivity and DNS connectivity are the same policy requirement.
29. DNS Performance and Caching
DNS resolution adds a lookup step before many network connections. CoreDNS supports caching, and Kubernetes also provides an optional NodeLocal DNSCache architecture for clusters where reducing DNS-related latency and connection tracking pressure is beneficial.
NodeLocal DNSCache runs a DNS caching agent on each Node and can reduce the need for Pods to traverse the normal Service path to reach CoreDNS. It is an optimization and operational architecture choice, not a prerequisite for ordinary Kubernetes DNS.
Before introducing DNS caching changes, measure the actual DNS workload and understand the cluster's existing DNS topology.
30. Practical Microservices Example
Consider an application with three namespaces:
The frontend can call the API using:
The API can call the database Service using:
The applications do not need to know the changing Pod IP addresses behind those Services.
31. Hands-On Lab: Explore Kubernetes DNS
Create a test Deployment and Service:
Check the Service:
Create a DNS test Pod:
From inside the Pod:
Then test HTTP:
Now delete one backend Pod:
The Service DNS name remains stable while the backend endpoint set changes.
32. Production Best Practices
• Use Service DNS names rather than hard-coded Pod IP addresses for normal application communication.
• Use short Service names within the same namespace for simple application configuration.
• Use namespace-qualified names for cross-namespace communication.
• Use fully qualified names when explicit DNS identity is useful for configuration or troubleshooting.
• Verify Service selectors and EndpointSlices when a DNS name resolves but traffic fails.
• Treat DNS resolution and application connectivity as separate troubleshooting layers.
• Monitor CoreDNS health, resource consumption and errors in production clusters.
• Avoid unnecessary changes to the CoreDNS Corefile; understand distribution-specific configuration before modifying it.
• When using restrictive NetworkPolicies, ensure application Pods can reach cluster DNS.
• Use headless Services only when endpoint-level discovery is required.
• Measure DNS behavior before introducing NodeLocal DNSCache or other optimization layers.
• Use readiness probes so endpoints reflect whether application instances should receive normal traffic.
33. Common Mistakes
Using the wrong namespace
A short name such as `api` searches in the client's namespace. Use `api.backend` for a Service in another namespace.
Assuming cluster.local is universal
It is the common default cluster domain, but the cluster domain can be configured differently.
Confusing CoreDNS with the kube-dns Service name
The DNS implementation can be CoreDNS while the Kubernetes Service remains named `kube-dns` for compatibility.
Assuming DNS resolution means the application is healthy
DNS can work while the Service has no usable endpoints or the application is not listening.
Debugging only from outside the cluster
Kubernetes Service DNS is designed for workloads inside the cluster. Test from a Pod to reproduce the application's DNS environment.
Changing CoreDNS before checking basic configuration
First inspect `/etc/resolv.conf`, namespace, Service existence, CoreDNS Pods, Service and EndpointSlices.
34. Interview Questions
What is Kubernetes DNS?
Answer: It is the cluster DNS mechanism that provides DNS records for Kubernetes resources such as Services and enables workloads to discover Services by name.
What is CoreDNS?
Answer: CoreDNS is the DNS server commonly deployed as the Kubernetes cluster DNS add-on.
Why is the CoreDNS Service called kube-dns?
Answer: For historical compatibility with the older kube-dns add-on.
What does a normal Service DNS record resolve to?
Answer: The Service cluster IP, represented by an A and/or AAAA record depending on the Service IP families.
What does a headless Service resolve to?
Answer: The IP addresses of the Pods selected by the Service rather than a Service cluster IP.
What is the normal Service FQDN pattern?
Answer: `<service>.<namespace>.svc.<cluster-domain>`.
Why does `service` sometimes fail while `service.namespace` works?
Answer: The client Pod is likely in a different namespace from the Service.
What is the role of EndpointSlices in DNS?
Answer: They provide Kubernetes endpoint information that DNS implementations such as CoreDNS can use to resolve Service-related records and that Service dataplanes use for traffic routing.
Does CoreDNS perform Service load balancing?
Answer: For a normal Service, DNS resolves to the Service cluster IP. The subsequent Service traffic routing is handled by the Service dataplane rather than by DNS returning all backend Pods.
What should you check first when Kubernetes DNS fails?
Answer: Check the Pod's `/etc/resolv.conf`, namespace/name, CoreDNS Pods, the `kube-dns` Service, EndpointSlices and CoreDNS logs.
35. Production DNS Checklist
• Can a test Pod resolve `kubernetes.default`?
• Can application Pods resolve required Services by short name?
• Can cross-namespace Services be resolved using namespace-qualified names?
• Does `/etc/resolv.conf` point to the expected cluster DNS nameserver?
• Are CoreDNS Pods Ready?
• Does the `kube-dns` Service exist and have endpoints?
• Can CoreDNS access Services and EndpointSlices through RBAC?
• Are NetworkPolicies allowing required DNS traffic?
• Are external DNS queries forwarded successfully?
• Are CoreDNS resource usage and error rates monitored?
36. Summary
Kubernetes DNS provides the naming layer that makes Service-based application communication practical. Applications can use names such as `api`, `api.backend`, or `api.backend.svc.cluster.local` instead of tracking changing Pod IP addresses.
CoreDNS is commonly used to implement cluster DNS. It integrates with Kubernetes resource information to answer DNS queries for Services and Pods. Normal Services resolve to a stable Service cluster IP, while headless Services resolve to the selected Pod IPs.
For troubleshooting, follow the layers in order: confirm the DNS name and namespace → inspect `/etc/resolv.conf` → test cluster DNS → check CoreDNS Pods and logs → check the `kube-dns` Service and EndpointSlices → verify RBAC → investigate NetworkPolicy and upstream DNS → finally test Service and application connectivity.
Once these layers are understood, Kubernetes DNS stops being a mysterious background component and becomes a predictable part of the Kubernetes networking architecture.
37. Related Kubernetes Topics
• Kubernetes Service Explained: ClusterIP, NodePort and LoadBalancer
• Kubernetes Service Discovery: How Pods Find Other Pods
• Kubernetes Pod Networking Explained
• Kubernetes EndpointSlice Explained
• Kubernetes Ingress Explained
• Kubernetes Gateway API Explained
• Kubernetes NetworkPolicy Explained
• Kubernetes StatefulSet Explained
Official Kubernetes References
DNS for Services and Pods — https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
Debugging DNS Resolution — https://kubernetes.io/docs/tasks/administer-cluster/dns-debugging-resolution/
Debug Services — https://kubernetes.io/docs/tasks/debug/debug-application/debug-service/
Customizing DNS Service — https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/
Using NodeLocal DNSCache in Kubernetes Clusters — https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/