coredns/man/coredns-reload.7

.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-RELOAD" 7 "September 2020" "CoreDNS" "CoreDNS Plugins"

.SH "NAME"
.PP
\fIreload\fP - allows automatic reload of a changed Corefile.

.SH "DESCRIPTION"
.PP
This plugin allows automatic reload of a changed \fICorefile\fP.
To enable automatic reloading of \fIzone file\fP changes, use the \fB\fCauto\fR plugin.

.PP
This plugin periodically checks if the Corefile has changed by reading
it and calculating its MD5 checksum. If the file has changed, it reloads
CoreDNS with the new Corefile. This eliminates the need to send a SIGHUP
or SIGUSR1 after changing the Corefile.

.PP
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. But see
the Bugs section for failure modes.

.PP
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. 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 \fB\fC0s\fR.

.PP
Jitter is re-calculated whenever the Corefile is reloaded.

.PP
This plugin can only be used once per Server Block.

.SH "SYNTAX"
.PP
.RS

.nf
reload [INTERVAL] [JITTER]

.fi
.RE

.PP
The plugin will check for changes every \fBINTERVAL\fP, subject to +/- the \fBJITTER\fP duration.

.IP \(bu 4
\fBINTERVAL\fP and \fBJITTER\fP are Golang durations
\[la]https://golang.org/pkg/time/#ParseDuration\[ra].
The default \fBINTERVAL\fP is 30s, default \fBJITTER\fP is 15s, the minimal value for \fBINTERVAL\fP
is 2s, and for \fBJITTER\fP it is 1s. If \fBJITTER\fP is more than half of \fBINTERVAL\fP, it will be
set to half of \fBINTERVAL\fP


.SH "EXAMPLES"
.PP
Check with the default intervals:

.PP
.RS

.nf
\&. {
    reload
    erratic
}

.fi
.RE

.PP
Check every 10 seconds (jitter is automatically set to 10 / 2 = 5 in this case):

.PP
.RS

.nf
\&. {
    reload 10s
    erratic
}

.fi
.RE

.SH "BUGS"
.PP
The reload happens without data loss (i.e. DNS queries keep flowing), but there is a corner case
where the reload fails, and you loose functionality. Consider the following Corefile:

.PP
.RS

.nf
\&. {
    health :8080
    whoami
}

.fi
.RE

.PP
CoreDNS starts and serves health from :8080. Now you change \fB\fC:8080\fR to \fB\fC:443\fR not knowing a process
is already listening on that port. The process reloads and performs the following steps:

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


.PP
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.

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

.PP
In CoreDNS v1.6.0 and earlier any \fB\fCimport\fR statements are not discovered by this plugin.
This means if any of these imported files changes the \fIreload\fP plugin is ignorant of that fact.
CoreDNS v1.7.0 and later does parse the Corefile and supports detecting changes in imported files.

.SH "METRICS"
.PP
If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metric is exported:

.IP \(bu 4
\fB\fCcoredns_reload_failed_total{}\fR - counts the number of failed reload attempts.
.IP \(bu 4
\fB\fCcoredns_reload_version_info{hash, value}\fR - record the hash value during reload.


.PP
Currently the type of \fB\fChash\fR is "md5", the \fB\fCvalue\fR is the returned hash value.

.SH "ALSO SEE"
.PP
See coredns-import(7) and corefile(5).