CoreDNS architecture and role — the cluster's DNS resolver

Two Pods in kube-system answer every name lookup the cluster makes. When they stop answering, nothing reports a DNS failure: applications report connection timeouts to Services that are perfectly healthy, and one outage surfaces in a dozen unrelated places at once. This lesson maps the resolution path from a Pod’s resolv.conf to the CoreDNS process, and shows which plugin in the Corefile owns which kind of answer.

CoreDNS architecture

CoreDNS is a Deployment in the kube-system namespace. The Deployment runs a configurable number of replicas (typically 2 for HA). The Pods serve DNS queries on port 53 (UDP and TCP). The Service kube-dns exposes the Pods.

flowchart LR
    A[Pod] --> B[resolv.conf]
    B --> C[kube-dns Service]
    C --> D[CoreDNS Pod]
    D --> E[etcd / API server]

The path is: Pod → kube-dns Service → CoreDNS Pod → API server / etcd.

The ConfigMap

The CoreDNS ConfigMap (coredns in kube-system) defines the plugins:

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
  namespace: kube-system
data:
  Corefile: |
    .:53 {
        errors
        health
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
          pods insecure
          fallthrough in-addr.arpa ip6.arpa
        }
        forward . /etc/resolv.conf
        cache 30
        loop
        reload
        loadbalance
    }

The plugins are the core of CoreDNS:

• errors — log errors.
• health — expose liveness.
• ready — expose readiness.
• kubernetes — answer queries for cluster-local names.
• forward — forward external queries to upstream DNS.
• cache — cache responses.
• loop — detect forwarding loops.
• reload — auto-reload on ConfigMap changes.
• loadbalance — round-robin between Pods.

The diagnostic

The canonical diagnostic:

# Substitute your own value before running - any Pod you can exec into:
SOURCE_POD=frontend-5f9c7d8b6c-2xk9p

# 1. Check the CoreDNS Pods
kubectl get pods -n kube-system -l k8s-app=kube-dns -o wide

# 2. Check the CoreDNS Service
kubectl get svc kube-dns -n kube-system

# 3. Check the CoreDNS ConfigMap
kubectl get configmap coredns -n kube-system -o yaml

# 4. Check the CoreDNS logs
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=200

# 5. Test the DNS from inside a Pod
kubectl exec -it "$SOURCE_POD" -- nslookup kubernetes.default

The diagnostic is the Pod, the Service, the ConfigMap, and the logs.

Common CoreDNS failures

• CoreDNS Pods in CrashLoopBackOff. The CoreDNS image is broken, the ConfigMap is invalid, or the etcd is failing.
• CoreDNS Pods Running but not Ready. The ready plugin is failing because the API server is unreachable.
• CoreDNS Service has no endpoints. The CoreDNS Pods are not Ready.
• CoreDNS ConfigMap is invalid. The Corefile has a syntax error; the CoreDNS Pods fail to start.

flowchart TD
    A[DNS failure] --> B{CoreDNS Pods Ready?}
    B -->|No| C[Pod failing]
    B -->|Yes| D{ConfigMap valid?}
    D -->|No| E[Fix ConfigMap]
    D -->|Yes| F{API server reachable?}
    F -->|No| G[Fix API server]
    F---|Yes| H[Pod-level issue]

The remediation

The remediation depends on the cause:

# Substitute your own value before running - any Pod you can exec into:
SOURCE_POD=frontend-5f9c7d8b6c-2xk9p

# Option 1: Restart the CoreDNS
kubectl rollout restart deployment/coredns -n kube-system

# Option 2: Fix the ConfigMap
kubectl edit configmap coredns -n kube-system

# Option 3: Scale the CoreDNS
kubectl scale deployment/coredns -n kube-system --replicas=4

# Option 4: Check the cluster's DNS policy
kubectl exec -it "$SOURCE_POD" -- cat /etc/resolv.conf

The remediation is the DNS recovery.

Production discipline

CoreDNS is the cluster’s DNS hypothesis. The discipline is to walk the canonical flow, identify the DNS layer failure, apply the remediation. The DNS is the cluster’s name resolution; the remediation is the DNS recovery.

• Check the CoreDNS Pods. The Pods are the cluster’s DNS.
• Check the ConfigMap. The ConfigMap is the CoreDNS’s configuration.
• Check the logs. The logs are the CoreDNS’s view.

Quiz