Deployment

CoreDNS is built and shipped as a static Go binary. The deployment story splits into "as a system service" and "as a Kubernetes cluster DNS." The repository contains the build pipeline; runtime manifests for Kubernetes live in the sister repository coredns/deployment.

What this repository ships

Artifact	Source	Used for
coredns binary	Makefile, Makefile.release	Linux/macOS/Windows hosts
Container images (coredns/coredns:<tag>)	Dockerfile, Makefile.docker, .github/workflows/docker.yml	Pushed to Docker Hub on release
Release archives (tar.gz, zip)	Makefile.release, .github/workflows/release.yml	Attached to GitHub release
Man pages (man/)	Generated from plugin READMEs via Makefile.doc	Distros that package CoreDNS

Building releases

Local build

make

Produces ./coredns. See Getting started.

Cross-compile

GOOS=linux GOARCH=arm64 make

CGO_ENABLED=0 by default, so cross-compilation works without any C toolchain.

Release pipeline

Makefile.release is the recipe used by .github/workflows/release.yml:

1. Read the tag (e.g. v1.14.3).
2. Cross-compile binaries for linux/{amd64,arm64,arm,ppc64le,s390x,mips64le}, darwin/{amd64,arm64}, freebsd/amd64, and windows/amd64.
3. Sign and archive each.
4. Upload to the GitHub release.
5. Trigger docker.yml to build and push images.

The workflow is gated on a manual tag push; only steering committee members have permission.

Container images

The top-level Dockerfile is a minimal scratch-based image:

FROM scratch
COPY coredns /coredns
EXPOSE 53 53/udp
ENTRYPOINT ["/coredns"]

Makefile.docker builds multi-arch manifests via docker buildx. Tags follow the upstream version (v1.14.3, latest).

Running on a host

The simplest deployment is a systemd unit pointing at a Corefile. Example (not in this repo; see coredns/deployment):

[Unit]
Description=CoreDNS DNS server

[Service]
ExecStart=/usr/local/bin/coredns -conf /etc/coredns/Corefile
AmbientCapabilities=CAP_NET_BIND_SERVICE
User=coredns
Group=coredns
Restart=on-failure

[Install]
WantedBy=multi-user.target

Notes:

• The binary needs CAP_NET_BIND_SERVICE if it listens on :53.
• A pidfile can be configured via -pidfile.
• Reload by sending SIGUSR1. Caddy converts that into a graceful in-place restart, handing sockets to the new instance via SO_REUSEPORT.

Kubernetes

CoreDNS is the default cluster DNS for Kubernetes since 1.13. Standard deployment is via the coredns/deployment repo; that repo ships Helm charts and raw manifests, plus the deploy.sh script that the upstream Kubernetes installer uses.

Operationally:

• The kubernetes plugin contacts the API server in-cluster using the pod's service account.
• The Corefile is a ConfigMap; reload happens via the reload plugin (default 30s SHA-256 check) when the volume mount updates.
• Probes:
  • livenessProbe: HTTP /health on :8080 (the health plugin).
  • readinessProbe: HTTP /ready on :8181 (the ready plugin). Combine with lameduck on health so a rolling restart drains gracefully.
• Metrics: :9153/metrics scraped by Prometheus.

Reload semantics

Caddy.Restart hands sockets between processes via SO_REUSEPORT (Linux). On a SIGUSR1 (or when the reload plugin notices the Corefile changed):

1. The current process spawns a child with the new config.
2. The child takes over the listeners.
3. The parent enters the lameduck state (configurable via health).
4. Once the lameduck timer expires, the parent shuts down.

On macOS/BSD, SO_REUSEPORT is not available with the same semantics, so reload involves a brief socket reopen. CoreDNS in production is overwhelmingly Linux, so this is not a major operational concern.

Versioning and deprecation

From the project README:

Release x.y.z: Announce that in the next release we will make backward incompatible changes. Release x.y+1.0: Increase the minor version and set the patch version to 0. Make the changes, but allow the old configuration to be parsed. Release x.y+1.1: Increase the patch version to 1. Remove the lenient parsing.

Translated: any breaking change is announced one minor release ahead, ships with a backward-compatible parser in the next minor, and only the next patch release removes the legacy form. So a deprecation always spans at least two minor releases.

Operating CoreDNS in production

This wiki covers the codebase, not the operations runbook. For day-2 concerns see How to monitor. The community-maintained operations docs live at https://coredns.io.