d933f635af
Run through the motions; create manual pages. Run go generate for good measure. Fix typo in Makefile.release while at it. Signed-off-by: Miek Gieben <miek@miek.nl>
148 lines
3.8 KiB
Groff
148 lines
3.8 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.nl
|
|
.TH "COREDNS-RELOAD" 7 "July 2019" "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
|
|
|
|
.IP \(bu 4
|
|
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)[https://golang.org/pkg/time/#ParseDuration
|
|
\[la]https://golang.org/pkg/time/#ParseDuration\[ra]]
|
|
.IP \(bu 4
|
|
Default \fBINTERVAL\fP is 30s, default \fBJITTER\fP is 15s
|
|
.IP \(bu 4
|
|
Minimal value for \fBINTERVAL\fP is 2s, and for \fBJITTER\fP is 1s
|
|
.IP \(bu 4
|
|
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 hopen in the prometheus metrics plugin.
|
|
|
|
.PP
|
|
In general be careful with assigning new port and expecting reload to work fully.
|
|
|
|
.PP
|
|
Also any \fB\fCimport\fR statement is not discovered by this plugin. This means if any of these imported files
|
|
changes the \fIreload\fP plugin is ignorant of that fact.
|
|
|
|
.SH "METRICS"
|
|
.PP
|
|
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_reload_failed_count_total{}\fR - counts the number of failed reload attempts.
|
|
|
|
|
|
.SH "ALSO SEE"
|
|
.PP
|
|
See coredns-import(7) and corefile(5).
|
|
|