> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# dnsPolicy Trap
> Explains Kubernetes pod DNS failures caused by dnsPolicy and /etc/resolv.conf misconfiguration, causing external names to resolve but cluster service names like kubernetes.default to fail.
If you run `nslookup` from inside a pod and `kubernetes.default` fails while `google.com` still resolves, the pod can reach some DNS server but not the cluster DNS. This typically happens because of one file and one setting: `/etc/resolv.conf` inside the pod and the pod's `dnsPolicy`.
Example failure:
```bash theme={null}
$ nslookup kubernetes.default
** server can't find kubernetes.default: NXDOMAIN
$ nslookup google.com
Name: google.com
Address: 142.250.4.100
```
Summary: external names resolve (node DNS works), but internal cluster names fail (cluster DNS not being used).
## Why this happens
Every pod has its own `/etc/resolv.conf`. Kubernetes (kubelet) writes that file for the pod based on the pod's `dnsPolicy` and whether the pod uses the host network. A typical pod's `/etc/resolv.conf` contains three important parts:
* `nameserver` — usually the cluster DNS (kube-dns/CoreDNS) service IP.
* `search` — includes the pod's namespace, `svc`, and `cluster.local` so short service names expand correctly.
* `options` — e.g., `ndots` value.
Example `/etc/resolv.conf` inside a normal pod:
```text theme={null}
# /etc/resolv.conf inside pod
nameserver 10.96.0.10 # kube-dns Service IP (example)
search my-namespace.svc.cluster.local svc.cluster.local cluster.local
options ndots:5
```
If `nameserver` points to the node's DNS (the node's `/etc/resolv.conf`) rather than the cluster DNS, the pod will resolve internet names but not Kubernetes service names. That happens when the pod will inherit the node resolver instead of using cluster DNS.
## The culprit: dnsPolicy
Kubernetes exposes `dnsPolicy` on pods to control how DNS is configured. Common values:
* `ClusterFirst` (default for most pods): kubelet configures `/etc/resolv.conf` to use the cluster DNS so pods can resolve internal service names such as `kubernetes.default`.
* `Default`: the pod inherits the node's DNS configuration (the node's `/etc/resolv.conf`). This allows internet name resolution via the node, but internal Kubernetes service names will not be resolved by that DNS.
* `ClusterFirstWithHostNet`: special policy for host-networked pods that still directs DNS to the cluster DNS.
Example pod spec using ClusterFirst (default):
```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
name: my-app
spec:
containers:
- name: app
image: app:1.0
dnsPolicy: ClusterFirst
```
Example pod spec that will use the node DNS (and thus likely fail to resolve cluster service names):
```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
name: my-app
spec:
containers:
- name: app
image: app:1.0
dnsPolicy: Default
```
The `Default` dnsPolicy is misleading: it does not mean “use the Kubernetes default behavior.” It means “use the node’s resolver.” If you need cluster DNS resolution, do not use `dnsPolicy: Default`.
## Host networking adds a wrinkle
When `hostNetwork: true` is set, the pod uses the node's network namespace. By default kubelet adjusts the dnsPolicy to `ClusterFirstWithHostNet` for these pods so they still use cluster DNS. Problems arise when `dnsPolicy` is explicitly set to `Default` on a host-networked pod — such pods will use the node resolver and lose ability to resolve cluster service names.
Host-networked pod that will run into the DNS problem:
```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
name: my-hostnet-app
spec:
hostNetwork: true
containers:
- name: app
image: app:1.0
dnsPolicy: Default # Uses node DNS — problematic for cluster service name resolution
```
Fix by using `ClusterFirstWithHostNet`:
```yaml theme={null}
apiVersion: v1
kind: Pod
metadata:
name: my-hostnet-app
spec:
hostNetwork: true
containers:
- name: app
image: app:1.0
dnsPolicy: ClusterFirstWithHostNet # ← the fix
```
## How to debug this issue
1. Check `/etc/resolv.conf` inside the pod:
```bash theme={null}
kubectl exec -it -- cat /etc/resolv.conf
```
Look for:
* `nameserver` — is it the cluster DNS IP (e.g., `10.96.0.10`) or the node IP?
* `search` — does it include `.svc.cluster.local` and `cluster.local`?
* `options ndots` — ensure it’s reasonable (commonly `ndots:5`).
2. Inspect the pod spec:
```bash theme={null}
kubectl get pod -o yaml
```
Check `spec.dnsPolicy` and `spec.hostNetwork`.
3. If the pod uses host networking, ensure `dnsPolicy` is `ClusterFirstWithHostNet` (unless you intentionally want node DNS).
## Quick checklist
| Step | What to check | Example/What it means |
| ---- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 1 | Inspect `/etc/resolv.conf` inside the pod | `nameserver` should point to cluster DNS; `search` should include `svc.cluster.local` |
| 2 | Check `spec.dnsPolicy` | `ClusterFirst` (normal pods) or `ClusterFirstWithHostNet` (hostNetwork pods). Avoid `Default` if you need cluster DNS. |
| 3 | For host-networked pods, confirm `dnsPolicy` | Use `ClusterFirstWithHostNet` when `hostNetwork: true` and cluster service resolution is required |
| 4 | Validate CoreDNS/kube-dns | Ensure CoreDNS pods and Service are healthy: `kubectl get pods -n kube-system` and `kubectl get svc -n kube-system kube-dns` |
## References
* [Kubernetes DNS for Services and Pods](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/)
* [CoreDNS — DNS server](https://coredns.io/)
Use the checklist above to quickly identify whether a pod is pointed at the node resolver by mistake, and update `dnsPolicy` or the pod spec accordingly to restore cluster DNS resolution.