What Are Pod DNS Policies in Kubernetes?

Detailed Answer

Every Pod in Kubernetes needs to resolve DNS names — both for cluster-internal service discovery (e.g., my-service.default.svc.cluster.local) and external names (e.g., api.example.com). The dnsPolicy field on a Pod controls which DNS servers are used and how /etc/resolv.conf is populated.

The Four DNS Policies

1. ClusterFirst (Default)

apiVersion: v1
kind: Pod
metadata:
  name: app
spec:
  dnsPolicy: ClusterFirst
  containers:
    - name: app
      image: myapp:1.0
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"

The Pod's /etc/resolv.conf points to the CoreDNS service (typically 10.96.0.10). DNS queries for cluster domains go to CoreDNS; everything else is forwarded to upstream resolvers configured in CoreDNS.

2. Default

dnsPolicy: Default

The Pod inherits the DNS configuration from the node it runs on. It uses the node's /etc/resolv.conf directly. Cluster-internal names (like my-svc.my-ns.svc.cluster.local) will not resolve because CoreDNS is bypassed.

3. ClusterFirstWithHostNet

spec:
  hostNetwork: true
  dnsPolicy: ClusterFirstWithHostNet

When a Pod uses hostNetwork: true, the default behavior would be to inherit the node's DNS (like Default). Setting ClusterFirstWithHostNet forces the Pod to still use CoreDNS despite sharing the host network namespace.

4. None

spec:
  dnsPolicy: None
  dnsConfig:
    nameservers:
      - 10.0.0.53
      - 10.0.0.54
    searches:
      - my-domain.local
      - default.svc.cluster.local
    options:
      - name: ndots
        value: "2"
      - name: timeout
        value: "3"

Complete manual control. The Pod's /etc/resolv.conf is built entirely from the dnsConfig block. This is useful for:

• Multi-cluster DNS setups
• Integration with external DNS providers
• Split-horizon DNS configurations

Understanding the Generated resolv.conf

For a Pod with dnsPolicy: ClusterFirst in the production namespace, the generated /etc/resolv.conf looks like:

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

The ndots:5 setting means any name with fewer than 5 dots is treated as a relative name and appended with each search domain before trying it as-is.

The ndots Performance Problem

With the default ndots:5, resolving api.example.com (which has 2 dots, fewer than 5) triggers these queries in order:

1. api.example.com.production.svc.cluster.local — miss
2. api.example.com.svc.cluster.local — miss
3. api.example.com.cluster.local — miss
4. api.example.com — hit

That is 4 DNS queries instead of 1. For high-throughput services making many external API calls, this creates significant overhead.

Tuning DNS with dnsConfig

You can overlay dnsConfig on any DNS policy (not just None):

apiVersion: v1
kind: Pod
metadata:
  name: optimized-app
spec:
  dnsPolicy: ClusterFirst
  dnsConfig:
    options:
      - name: ndots
        value: "2"
      - name: single-request-reopen
  containers:
    - name: app
      image: myapp:1.0
      resources:
        requests:
          cpu: "100m"
          memory: "128Mi"

Setting ndots: 2 means names with 2+ dots are treated as absolute immediately. single-request-reopen avoids a known issue with conntrack and simultaneous A/AAAA queries.

Debugging DNS Issues

# Check what resolv.conf looks like inside the Pod
kubectl exec app -- cat /etc/resolv.conf

# Test DNS resolution
kubectl exec app -- nslookup kubernetes.default.svc.cluster.local

# Run a debug Pod with DNS tools
kubectl run dns-debug --image=nicolaka/netshoot --rm -it -- bash
# Inside: dig my-service.default.svc.cluster.local

Common DNS Pitfalls

1. hostNetwork Pods lose cluster DNS: Always set dnsPolicy: ClusterFirstWithHostNet for host-network Pods that need cluster service discovery.
2. High DNS latency: Check ndots value and consider lowering it. Also ensure CoreDNS has enough replicas and CPU.
3. Stale DNS cache: CoreDNS caches responses. If a Service is recreated, Pods may resolve stale IPs until the TTL expires.
4. Missing search domains with dnsPolicy: None: You must explicitly add cluster search domains if you want in-cluster resolution.