The Corefile — CoreDNS configuration and the plugin chain

The Corefile is the CoreDNS configuration. It defines the server blocks, the plugin chain, and the plugin-specific configuration. The Corefile is held in a ConfigMap; the cluster operator can update it via kubectl apply. This lesson walks the Corefile, the plugin chain, and the operational discipline.

The Corefile format

The Corefile is a CoreDNS-specific configuration:

.:53 {
    errors
    health {
        lameduck 5s
    }
    ready
    kubernetes cluster.local in-addr.arpa ip6.arpa {
        pods insecure
        fallthrough in-addr.arpa ip6.arpa
        ttl 30
    }
    prometheus :9153
    forward . /etc/resolv.conf {
        max_concurrent 1000
    }
    cache 30 {
        success 9984 30
        denial 9984 5
    }
    loop
    reload
    loadbalance
}

The format is:

• A server block starts with a zone and port (e.g., .:53).
• The block contains a list of plugins.
• Each plugin can have its own block with plugin-specific configuration.

The plugin chain

The plugin chain is evaluated in order for each query. The first plugin that handles the query returns the response; the next plugins are skipped.

flowchart LR
    A[Query] --> B[errors]
    B --> C[health]
    C --> D[ready]
    D --> E[kubernetes]
    E --> F[prometheus]
    F --> G[forward]
    G --> H[cache]
    H --> I[loop]
    I --> J[reload]
    J --> K[loadbalance]
    K --> L[Response]

The plugin chain is the heart of the CoreDNS configuration. The cluster operator must understand the order of the plugins.

The kubernetes plugin

The kubernetes plugin serves DNS records for Services and Pods based on the cluster.local zone:

kubernetes cluster.local in-addr.arpa ip6.arpa {
    pods insecure
    fallthrough in-addr.arpa ip6.arpa
    ttl 30
}

The options:

• pods insecure: serve Pod records via the <pod-ip>.<namespace>.pod.cluster.local format.
• fallthrough in-addr.arpa ip6.arpa: forward PTR queries to the upstream if not matched.
• ttl 30: the TTL for the records.

The forward plugin

The forward plugin forwards queries to the upstream resolvers:

forward . /etc/resolv.conf {
    max_concurrent 1000
}

The options:

• .: the zone to forward (the root zone).
• /etc/resolv.conf: the upstream resolvers from the node’s resolv.conf.
• max_concurrent 1000: the maximum number of concurrent upstream queries.

The cache plugin

The cache plugin caches responses to reduce latency:

cache 30 {
    success 9984 30
    denial 9984 5
}

The options:

• success 9984 30: cache successful responses for 9984 entries with a TTL of 30 seconds.
• denial 9984 5: cache denial responses for 9984 entries with a TTL of 5 seconds.

The reload plugin

The reload plugin watches the Corefile and reloads the configuration when the file changes:

reload 30s

The 30s is the reload interval. The cluster operator can change the interval.

The metrics

The CoreDNS Pods expose Prometheus metrics:

# The address comes from the CoreDNS Pod itself:
COREDNS_POD_IP=$(kubectl get pods -n kube-system -l k8s-app=kube-dns \
  -o jsonpath='{.items[0].status.podIP}')

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

coredns_dns_requests_total{server="dns://:53",zone="cluster.local"} 5000
coredns_dns_responses_total{server="dns://:53",zone="cluster.local",rcode="NOERROR"} 4800
coredns_cache_hits_total{server="dns://:53",zone="cluster.local"} 2400
coredns_cache_misses_total{server="dns://:53",zone="cluster.local"} 500

The metrics show the request count, the response count, the cache hit ratio, and the upstream latency.

The failure modes

The Corefile’s failure modes:

• Corefile syntax error: 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.
• Reload not working: the corefile is not reloaded automatically. The fix is to restart the Pods.
• ConfigMap not mounted: the Corefile is not mounted to the Pods. The fix is to verify the ConfigMap.
• Kubernetes plugin not updating: the plugin’s watch loop is broken. The fix is to restart the Pods.

The operational discipline

The Corefile’s operational discipline:

• Document the Corefile. The Corefile is the cluster’s DNS configuration.
• Audit the Corefile at every change. The Corefile is critical configuration.
• Test the Corefile in staging. The Corefile must work for the workload.
• Monitor the metrics. The metrics are the leading indicator.
• Plan the Corefile’s evolution. The Corefile is the cluster’s DNS configuration.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.

Quiz

Production discipline

• The Corefile is the cluster’s DNS configuration. The cluster operator must treat it as critical.
• Document the Corefile. The Corefile is the cluster’s DNS reference.
• Audit the Corefile at every change. The Corefile is critical configuration.
• Test the Corefile in staging. The Corefile must work for the workload.
• Monitor the metrics. The metrics are the leading indicator.
• Plan the Corefile’s evolution. The Corefile is the cluster’s DNS configuration.
• Document the troubleshooting. The troubleshooting is the cluster’s operational reference.
• Use a CI check for the Corefile. The CI check can catch the syntax error at every change.
• Train the operations team on the Corefile diagnostics. The diagnostics are the team’s tools.