2c418b9fd5
* Fix spelling in coredns.1 and corefile.7 md files * Run make -f Makefile.doc Signed-off-by: Miek Gieben <miek@miek.nl>
122 lines
2.5 KiB
Groff
122 lines
2.5 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.nl
|
|
.TH "COREDNS-HEALTH" 7 "April 2019" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIhealth\fP - enables a health check endpoint.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
Enabled process wide health endpoint. When CoreDNS is up and running this returns a 200 OK http
|
|
status code. The health is exported, by default, on port 8080/health .
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
health [ADDRESS]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Optionally takes an address; the default is \fB\fC:8080\fR. The health path is fixed to \fB\fC/health\fR. The
|
|
health endpoint returns a 200 response code and the word "OK" when this server is healthy.
|
|
|
|
.PP
|
|
An extra option can be set with this extended syntax:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
health [ADDRESS] {
|
|
lameduck DURATION
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
Where \fB\fClameduck\fR will make the process unhealthy then \fIwait\fP for \fBDURATION\fP before the process
|
|
shuts down.
|
|
|
|
|
|
.PP
|
|
If you have multiple Server Blocks, \fIhealth\fP can only be enabled in one of them (as it is process
|
|
wide). If you really need multiple endpoints, you must run health endpoints on different ports:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
com {
|
|
whoami
|
|
health :8080
|
|
}
|
|
|
|
net {
|
|
erratic
|
|
health :8081
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Doing this is supported but both endponts ":8080" and ":8081" will export the exact same health.
|
|
|
|
.SH "METRICS"
|
|
.PP
|
|
If monitoring is enabled (via the \fIprometheus\fP directive) then the following metric is exported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_health_request_duration_seconds{}\fR - duration to process a HTTP query to the local
|
|
\fB\fC/health\fR endpoint. As this a local operation it should be fast. A (large) increase in this
|
|
duration indicates the CoreDNS process is having trouble keeping up with its query load.
|
|
|
|
|
|
.PP
|
|
Note that this metric \fIdoes not\fP have a \fB\fCserver\fR label, because being overloaded is a symptom of
|
|
the running process, \fInot\fP a specific server.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
Run another health endpoint on http://localhost:8091
|
|
\[la]http://localhost:8091\[ra].
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
health localhost:8091
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Set a lameduck duration of 1 second:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
\&. {
|
|
health localhost:8092 {
|
|
lameduck 1s
|
|
}
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "BUGS"
|
|
.PP
|
|
When reloading, the health handler is stopped before the new server instance is started. If that
|
|
new server fails to start, then the initial server instance is still available and DNS queries still
|
|
served, but health handler stays down. Health will not reply HTTP request until a successful reload
|
|
or a complete restart of CoreDNS.
|
|
|