COREDNS-RELOAD(7)

💅 COREDNS-RELOAD(7)

okay so this is the reload plugin page from the CoreDNS Plugins manual (section 7 of the manual, bestie, we're in the big-kid pages) — and honestly? it's a little banger. let's get into it 🫶

✨ NAME ✨

reload — allows automatic reload of a changed Corefile. that's it. that's the whole vibe. 🎀

🌸 DESCRIPTION 🌸

so this plugin gives you automatic reload of a changed Corefile. literally it just watches and goes "hm. new Corefile? slay, let's go."

important little side note bestie: if what you actually want is automatic reloading of zone file changes, that's a different plugin — use the auto plugin for that. reload is for the Corefile itself. don't mix them up 💀

here's the mechanic, and it's honestly so clean: this plugin periodically checks if the Corefile has changed by reading it and calculating its SHA512 checksum. if the file has changed, it reloads CoreDNS with the new Corefile. that eliminates the need to send a SIGHUP or SIGUSR1 after changing the Corefile. no more manual poking, no cap. ✨

the reloads are graceful — you should not see any loss of service when the reload happens. even if the new Corefile has an error, CoreDNS will continue to run the old config and an error message will be printed to the log. iconic behaviour honestly. but ⚠️ see the Bugs section for the failure modes, because there is a corner case and it's not cute.

now. in some environments (for example, Kubernetes), there may be many CoreDNS instances that started very near the same time and all share a common Corefile. and like… you do not want all of them reloading at the exact same moment, that's giving stampede energy 🙈. so to prevent these all from reloading at the same time, some jitter is added to the reload check interval. this is jitter from the perspective of multiple CoreDNS instances; each instance still checks on a regular interval, but all of these instances will have their reloads spread out across the jitter duration. this isn't strictly necessary given that the reloads are graceful, and can be disabled by setting the jitter to 0s. 🦋

jitter is re-calculated whenever the Corefile is reloaded.

🚨 real talk: this plugin can only be used once per Server Block. one and done, bestie.

🧚 SYNTAX 🧚

reload [INTERVAL] [JITTER]

the plugin will check for changes every INTERVAL, subject to +/- the JITTER duration.

• INTERVAL and JITTER are Golang durations (⟨https://golang.org/pkg/time/#ParseDuration⟩). the default INTERVAL is 30s, default JITTER is 15s, the minimal value for INTERVAL is 2s, and for JITTER it is 1s. and if JITTER is more than half of INTERVAL, it will be set to half of INTERVAL. the math is mathing 💅

🔥 EXAMPLES 🔥

check with the default intervals — look at her go, no arguments needed, she just works:

. {
    reload
    erratic
}

check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case) — see, the halving rule in action, we love a self-enforcing rule:

. {
    reload 10s
    erratic
}

💀 BUGS 💀

okay so the reload happens without data loss (i.e. DNS queries keep flowing), but there is a corner case where the reload fails, and you lose functionality. and we have to talk about it. consider the following Corefile:

. {
    health :8080
    whoami
}

CoreDNS starts and serves health from :8080. now you change :8080 to :443 not knowing a process is already listening on that port. 😭 the process reloads and performs the following steps:

1. close the listener on 8080
2. reload and parse the config again
3. fail to start a new listener on 443
4. fail loading the new Corefile, abort and keep using the old process

after the aborted attempt to reload we are left with the old processes running, but the listener is closed in step 1; so the health endpoint is broken. the same can happen in the prometheus plugin. not to be dramatic but this is the plot twist nobody asked for 🙈

in general be careful with assigning new port and expecting reload to work fully.

also, history lesson bestie 📚: in CoreDNS v1.6.0 and earlier any import statements are not discovered by this plugin. this means if any of these imported files changes, the reload plugin is ignorant of that fact. CoreDNS v1.7.0 and later does parse the Corefile and supports detecting changes in imported files. so like… upgrade, babe. 💜

📊 METRICS 📊

if monitoring is enabled (via the prometheus plugin) then the following metric is exported:

• coredns_reload_failed_total{} — counts the number of failed reload attempts.
• coredns_reload_version_info{hash, value} — record the hash value during reload.

currently the type of hash is sha512, the value is the returned hash value. 💖

👑 SEE ALSO 👑

see coredns-import(7) and corefile(5). go read them, they're friends of the family at this point 🌈

---

that's the page, bestie! 🦋 this whole thing is from CoreDNS, dated March 2026, and it lives in the COREDNS-RELOAD(7) manual slot — go forth and reload gracefully, and remember: jitter 0s if you're feeling chaotic. mwah 💅💖