Backends and zone serving

Active contributors: miekg, chrisohaver, johnbelamaric, yongtang, bradbeam, rajansandeep

Purpose

These plugins are where DNS data actually comes from. Some read it from disk (RFC 1035 zone files, /etc/hosts-style files), some pull it from a key/value store, and some watch a cluster API (Kubernetes, Nomad). They sit at the tail of the plugin chain — a backend either answers a query or NXDOMAINs (or fallthroughs to the next plugin).

Plugins in this group

Plugin	Source	One-liner
file	plugin/file/	Serve a zone from an RFC 1035 master file (DNSSEC-signed support, NSEC only)
auto	plugin/auto/	Watch a directory and load every matching zone file
secondary	plugin/secondary/	Pull a zone via AXFR from a primary server, refresh on SOA
hosts	plugin/hosts/	Serve /etc/hosts-style records
etcd	plugin/etcd/	Read SkyDNS-style records from etcd v3
kubernetes	plugin/kubernetes/	Cluster DNS for Kubernetes (services, endpoints, pods, headless)
k8s_external	plugin/k8s_external/	External-facing Kubernetes Service IP lookup
route53	plugin/route53/	Serve zones from AWS Route53
azure	plugin/azure/	Serve zones from Azure DNS
clouddns	plugin/clouddns/	Serve zones from Google Cloud DNS
nomad	plugin/nomad/	Serve service DNS from a HashiCorp Nomad cluster
transfer	plugin/transfer/	Allow outbound AXFR/IXFR for the zones served by file/auto/etcd/k8s

How a backend serves a query

graph TD
    Q[ServeDNS]
    Q --> M{name in zone?}
    M -->|no| N[plugin.NextOrFailure]
    M -->|yes| L[Lookup type, name]
    L -->|hit| R[response.NoError]
    L -->|empty| E[response.NoData / SOA in authority]
    L -->|missing| X[response.NameError NXDOMAIN]
    L -->|delegation| D[response.Delegation]
    R --> WRT[w.WriteMsg]
    E --> WRT
    X --> WRT
    D --> WRT

Most backends share three ingredients:

• A configured set of zones. plugin.Zones finds the longest-matching zone for a query.
• A typed key/value store. The shared plugin.ServiceBackend interface (plugin/backend.go) abstracts services across etcd, kubernetes, route53, azure, clouddns, nomad, k8s_external. plugin/backend_lookup.go implements lookup by qtype on top of Services / Reverse.
• A fallthrough knob, parsed via plugin/pkg/fall, so the plugin can hand non-matching names to the next plugin.

Notable plugins in detail

file

The classic authoritative serve. Loads an RFC 1035 master file from disk into a sorted radix tree (plugin/file/tree/). plugin/file/lookup.go walks the tree to answer queries, including DNSSEC NSEC denial-of-existence. reload DURATION rescans the file for SOA changes; the file plugin watches the SOA serial rather than mtime so a touch alone won't trigger a reload.

fallthrough [zones...] lets the plugin coexist with another zone backend. CNAME chasing recurses through the chain via plugin/pkg/upstream.

auto

A file-flavoured directory watcher. New files matching a glob are loaded as zones, removed files are unloaded. Useful for serving a directory of zone files maintained by an external process.

secondary

Implements RFC 1035 secondary semantics over AXFR. Refreshes on SOA serial changes; reads incoming NOTIFY messages from the configured primary.

hosts

Reads a file in /etc/hosts format and answers A/AAAA/PTR for the entries. Inline blocks of IP NAME lines are also supported in the Corefile.

etcd

Stores records under keys shaped like /skydns/com/example/www. The Caddyfile syntax accepts an etcd endpoint (endpoint, username, password, tls) and a list of zones. Backed by the shared ServiceBackend interface so the same lookup logic powers kubernetes and route53.

kubernetes

The single largest plugin (controller.go is ~25k lines including tests). It implements the Kubernetes DNS-Based Service Discovery spec.

graph LR
    K[client-go informers] --> S[Service / Endpoints / Pod / Namespace caches]
    S --> P[Plugin lookup]
    P -->|svc.cluster.local| Resolve[ServiceBackend.Services]
    P -->|reverse PTR| Reverse[ServiceBackend.Reverse]

Highlights:

• Configurable: endpoint, kubeconfig, namespaces, labels, pods mode (disabled, insecure, verified), noendpoints, multicluster, apiserver_qps, apiserver_burst, apiserver_max_inflight, startup_timeout.
• Ready and metrics integration: implements ready.Readiness and exports per-zone request counters (plugin/kubernetes/metrics.go).
• Headless service support, dual-stack via kind selectors, and external-name CNAME chasing.
• Multicluster support is layered on top via the mcs-api (sigs.k8s.io/mcs-api).

k8s_external

A lighter sibling that exposes Service LoadBalancer IPs and ExternalName redirects on a public-facing zone (zone IN A queries that resolve to cluster ingress addresses). Often run on a public CoreDNS in front of the cluster.

route53 / azure / clouddns

Periodically reads zones from the cloud provider's API into an in-memory copy, with watch-or-poll semantics depending on the provider. Authentication uses the standard SDK credential chain (env vars, IAM role, instance metadata, etc.). All three implement ServiceBackend.

nomad

Serves service DNS from a HashiCorp Nomad cluster, similar in spirit to kubernetes.

transfer

Not a data source — a modifier. When loaded with a backend that supports zone transfer (file, auto, etcd, kubernetes, secondary), the transfer to <peer> block allows that backend to respond to AXFR/IXFR. It also handles outbound NOTIFY when a zone changes.

Cross-plugin glue

• All file-based backends share plugin/pkg/upstream to chase CNAMEs through the rest of the chain.
• transfer, dnssec, sign and the file backends speak a common notion of zone transfer; dnssec cooperates with transfer so signed answers can be served from disk or generated on the fly.
• k8s_external and kubernetes can run in the same Corefile but on different listeners (an internal cluster zone and an external one).
• The cache plugin sits in front of any backend to speed up repeated queries.

Key source files

File	Purpose
plugin/backend.go, plugin/backend_lookup.go	Shared ServiceBackend interface and qtype-driven lookup
plugin/file/file.go, plugin/file/lookup.go, plugin/file/tree/	RFC 1035 zone file serving
plugin/auto/auto.go	Directory-driven file
plugin/secondary/secondary.go	AXFR-based secondary
plugin/hosts/hosts.go	/etc/hosts-style
plugin/etcd/etcd.go, plugin/etcd/handler.go	etcd v3 backend
plugin/kubernetes/kubernetes.go, plugin/kubernetes/controller.go, plugin/kubernetes/handler.go	Kubernetes backend
plugin/k8s_external/external.go	External Kubernetes service zone
plugin/route53/route53.go	AWS Route53 backend
plugin/azure/azure.go	Azure DNS backend
plugin/clouddns/gcp.go	Google Cloud DNS backend
plugin/nomad/nomad.go	Nomad backend
plugin/transfer/transfer.go	Zone transfer mediator

For configuration details consult each plugin's README.md and man/coredns-<name>.7.

Related pages

• Forwarding and caching — what to do when a backend doesn't have the answer.
• Security — DNSSEC, ACLs, TSIG.
• Plugin system — ServiceBackend and NextOrFailure.
• Shared packages — pkg/upstream, pkg/fall.