kubernetes

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.

By Shubhankar Tripathi • • 5 min read

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:

api-7d8c9f6b5d-a1b2c   10.244.1.10
api-7d8c9f6b5d-c3d4e   10.244.2.14
api-7d8c9f6b5d-f5g6h   10.244.3.21


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`.

http://api:8080


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.

kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl get svc -n kube-system
kubectl get endpointslice -n kube-system   -l kubernetes.io/service-name=kube-dns


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

Application
    |
    | DNS query: api
    v
Pod DNS configuration
    |
    v
Cluster DNS Service
    |
    v
CoreDNS
    |
    | Kubernetes-aware DNS lookup
    v
Service DNS record
    |
    v
Service ClusterIP
    |
    v
Service dataplane
    |
    v
Backend Pod


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.

kubectl exec -it <pod-name> -- cat /etc/resolv.conf


A configuration may look similar to:

search default.svc.cluster.local svc.cluster.local cluster.local
nameserver 10.96.0.10
options ndots:5


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.

curl http://api:8080


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:

<service-name>.<namespace>.svc.<cluster-domain>


For example, with Service `orders`, namespace `production`, and cluster domain `cluster.local`:

orders.production.svc.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

Name

Example

Typical meaning

Short Service name

orders

Service in the client's namespace

Namespace-qualified

orders.production

Service named orders in production

Fully qualified

orders.production.svc.cluster.local

Explicit Service DNS name


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:

Object

Namespace

Client Pod

frontend

api Service

backend


This query looks for `api` in the `frontend` namespace:

nslookup api


To resolve the Service in `backend`, specify its namespace:

nslookup api.backend


Or use:

nslookup api.backend.svc.cluster.local


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:

apiVersion: v1
kind: Service
metadata:
  name: orders
  namespace: production
spec:
  selector:
    app: orders
  ports:
    - name: http
      port: 8080
      targetPort: 8080


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`.

apiVersion: v1
kind: Service
metadata:
  name: database
  namespace: production
spec:
  clusterIP: None
  selector:
    app: database
  ports:
    - name: db
      port: 5432
      targetPort: 5432


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.

<pod-hostname>.<service-name>.<namespace>.svc.<cluster-domain>


For example, a StatefulSet Pod might have a DNS identity following the pattern:

db-0.database.production.svc.cluster.local


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.

ports:
  - name: http
    port: 8080
    targetPort: 8080


The SRV record follows the pattern:

_<port-name>._<port-protocol>.<service>.<namespace>.svc.<cluster-domain>


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.

kubectl describe clusterrole system:coredns -n kube-system


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`.

kubectl get configmap coredns -n kube-system -o yaml


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.

curl https://www.google.com


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?

kubectl exec -it dnsutils -- nslookup orders.production.svc.cluster.local


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.

Observation

Likely layer to investigate

DNS name cannot resolve

Pod DNS configuration / CoreDNS / Service DNS

DNS resolves but no endpoints

Service selector / EndpointSlice / Pod readiness

Service has endpoints but request fails

Application / Service dataplane / NetworkPolicy / network path

Pod IP works but Service IP fails

Service configuration or Service dataplane

Internal names work but external names fail

CoreDNS forwarding / upstream DNS / node resolver


20. Troubleshooting Kubernetes DNS

Use a temporary diagnostic Pod or an existing Pod with DNS tools.

kubectl run dnsutils --rm -it   --restart=Never   --image=registry.k8s.io/e2e-test-images/agnhost:2.39   -- sh


Then test:

nslookup kubernetes.default
nslookup <service-name>
nslookup <service-name>.<namespace>
nslookup <service-name>.<namespace>.svc.cluster.local


The official Kubernetes DNS troubleshooting guide uses `nslookup kubernetes.default` as a basic cluster DNS test.

21. Check the Pod DNS Configuration

kubectl exec -it <pod-name> -- cat /etc/resolv.conf


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

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


If CoreDNS Pods are not running or are repeatedly restarting, investigate their status and logs.

kubectl logs -n kube-system -l k8s-app=kube-dns


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

kubectl get svc -n kube-system
kubectl get svc kube-dns -n kube-system


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

kubectl get endpointslice -n kube-system   -l kubernetes.io/service-name=kube-dns


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

kubectl describe clusterrole system:coredns -n kube-system


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.

kubectl -n kube-system edit configmap coredns


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

Symptom

Possible cause

First checks

`nslookup service` fails

Wrong namespace or DNS problem

Try namespace-qualified name and inspect `/etc/resolv.conf`.

Service DNS resolves but connection fails

Service/endpoints/application/network issue

Check Service, EndpointSlices, Pod readiness and application port.

All cluster DNS names fail

CoreDNS or cluster DNS path

Check CoreDNS Pods, Service and EndpointSlices.

Only external domains fail

Forwarding/upstream DNS issue

Inspect CoreDNS Corefile and upstream resolver.

Cross-namespace lookup fails

Namespace omitted

Use `service.namespace` or FQDN.

DNS intermittently fails

DNS capacity, networking or implementation issue

Check CoreDNS health, logs, resource usage and network path.


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:

Namespace

Service

Purpose

frontend

web

User-facing frontend

backend

api

Application API

data

postgres

Internal database endpoint


The frontend can call the API using:

http://api.backend:8080


The API can call the database Service using:

postgres.data:5432


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:

kubectl create deployment web --image=nginx:1.27 --replicas=3

kubectl expose deployment web   --name=web   --port=80   --target-port=80   --type=ClusterIP


Check the Service:

kubectl get svc web
kubectl get endpointslice   -l kubernetes.io/service-name=web


Create a DNS test Pod:

kubectl run dnsutils --rm -it   --restart=Never   --image=registry.k8s.io/e2e-test-images/agnhost:2.39   -- sh


From inside the Pod:

nslookup web
nslookup web.default
nslookup web.default.svc.cluster.local


Then test HTTP:

wget -qO- http://web:80


Now delete one backend Pod:

kubectl get pods -o wide
kubectl delete pod <one-web-pod>
kubectl get endpointslice   -l kubernetes.io/service-name=web


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/