CoreDNS fundamentals — the cluster DNS architecture

CoreDNS is the cluster DNS service. It serves DNS records for Services and Pods, forwards queries to upstream resolvers, and uses a plugin-based architecture. This lesson walks the architecture, the deployment model, and the operational discipline.

What CoreDNS is

CoreDNS is a DNS server written in Go. It is the default Kubernetes DNS service since Kubernetes 1.13. CoreDNS replaced kube-dns, which was a Go-based DNS server with a different architecture.

flowchart LR
    A[Pod] -->|DNS query| B[CoreDNS]
    B -->|cluster.local| C[Kubernetes API]
    B -->|other| D[Upstream DNS]
    C -->|Service/Pod records| B
    D -->|answer| B
    B -->|answer| A

CoreDNS serves DNS records for cluster-local names (Services, Pods) and forwards other queries to the upstream resolvers.

The CoreDNS architecture

CoreDNS is a single binary that loads plugins. The plugins are organised as a chain of responsibility: each plugin can process the query, modify the response, or pass the query to the next plugin.

// Pseudocode
coremain.Run()

func coremain.Run() {
    // Read the Corefile
    // Build the plugin chain
    // Start the DNS server
    // Start the plugin chain
}

The plugin chain is configured in the Corefile:

.:53 {
    errors
    health
    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 Corefile is the cluster’s DNS configuration. The plugins are evaluated in order for each query.

The deployment model

CoreDNS is deployed as a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: coredns
  namespace: kube-system
spec:
  replicas: 2
  selector:
    matchLabels:
      k8s-app: kube-dns
  template:
    metadata:
      labels:
        k8s-app: kube-dns
    spec:
      containers:
        - name: coredns
          image: registry.k8s.io/coredns/coredns:v1.11.4
          args:
            - "-conf"
            - "/etc/coredns/Corefile"
          volumeMounts:
            - name: config-volume
              mountPath: /etc/coredns
      volumes:
        - name: config-volume
          configMap:
            name: coredns
            items:
              - key: Corefile
                path: Corefile

The Deployment is autoscaled based on CPU and memory. The cluster operator can configure the autoscaling parameters.

The Service

CoreDNS is exposed via a Service:

apiVersion: v1
kind: Service
metadata:
  name: kube-dns
  namespace: kube-system
spec:
  selector:
    k8s-app: kube-dns
  clusterIP: 10.96.0.10
  ports:
    - name: dns
      port: 53
      protocol: UDP
    - name: dns-tcp
      port: 53
      protocol: TCP

The Service’s ClusterIP is the cluster’s DNS resolver address. The Pod’s resolv.conf points to this IP.

The plugins

CoreDNS has a plugin architecture. The standard plugins for Kubernetes:

The plugin chain is configured in the Corefile. The cluster operator can add or remove plugins.

The metrics

CoreDNS exposes Prometheus metrics:

# CoreDNS Pod IP, from:
#   kubectl get pods -n kube-system -l k8s-app=kube-dns -o wide
COREDNS_IP=10.244.0.7

curl "http://$COREDNS_IP:9153/metrics"

coredns_dns_requests_total{server="dns://:53",zone="."} 1000
coredns_dns_responses_total{server="dns://:53",zone=".",rcode="NOERROR"} 950
coredns_cache_hits_total{server="dns://:53",zone="."} 500
coredns_cache_misses_total{server="dns://:53",zone="."} 100

The metrics show the request count, the response count, the cache hit ratio, and the upstream latency. The cluster operator monitors these metrics.

The failure modes

CoreDNS’s failure modes:

• CoreDNS down: the DNS service is unavailable. The fix is to restart the Pods.
• Corefile misconfigured: the Corefile has a syntax error. The fix is to verify the Corefile.
• Plugin misconfigured: a plugin’s configuration is wrong. The fix is to verify the plugin’s configuration.
• Upstream DNS down: the upstream resolvers are unavailable. The fix is to verify the upstream.
• Cache corruption: the cache returns wrong responses. The fix is to restart the Pods.

The operational discipline

CoreDNS’s operational discipline:

• Document the Corefile. The Corefile is the cluster’s DNS configuration.
• Monitor the metrics. The metrics are the leading indicator.
• Test the DNS in staging. The DNS must work for the workload.
• Plan the DNS’s evolution. The DNS service must scale with the cluster.
• Document the architecture. The CoreDNS architecture is the cluster’s DNS reference.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• CoreDNS is the cluster’s DNS service. The cluster operator must treat it as critical infrastructure.
• Document the Corefile. The Corefile is the cluster’s DNS configuration.
• Monitor the metrics. The metrics are the leading indicator.
• Test the DNS in staging. The DNS must work for the workload.
• Plan the DNS’s evolution. The DNS service must scale with the cluster.
• Document the architecture. The CoreDNS architecture is the cluster’s DNS reference.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Train the operations team on the CoreDNS diagnostics. The diagnostics are the team’s tools.
• Plan the DNS’s evolution. The DNS service is the cluster’s discovery primitive; the operator must plan for the cluster’s growth.