94 lines
3 KiB
Groff
94 lines
3 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-AUTOPATH" 7 "October 2020" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIautopath\fP - allows for server-side search path completion.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
If it sees a query that matches the first element of the configured search path, \fIautopath\fP will
|
|
follow the chain of search path elements and return the first reply that is not NXDOMAIN. On any
|
|
failures, the original reply is returned. Because \fIautopath\fP returns a reply for a name that wasn't
|
|
the original question it will add a CNAME that points from the original name (with the search path
|
|
element in it) to the name of this answer.
|
|
|
|
.PP
|
|
\fBNote\fP: There are several known issues. See section below.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
autopath [ZONE...] RESOLV\-CONF
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBZONES\fP zones \fIautopath\fP should be authoritative for.
|
|
.IP \(bu 4
|
|
\fBRESOLV-CONF\fP points to a \fB\fCresolv.conf\fR like file or uses a special syntax to point to another
|
|
plugin. For instance \fB\fC@kubernetes\fR, will call out to the kubernetes plugin (for each
|
|
query) to retrieve the search list it should use.
|
|
|
|
|
|
.PP
|
|
If a plugin implements the \fB\fCAutoPather\fR interface then it can be used.
|
|
|
|
.SH "METRICS"
|
|
.PP
|
|
If monitoring is enabled (via the \fIprometheus\fP plugin) then the following metric is exported:
|
|
|
|
.IP \(bu 4
|
|
\fB\fCcoredns_autopath_success_total{server}\fR - counter of successfully autopath-ed queries.
|
|
|
|
|
|
.PP
|
|
The \fB\fCserver\fR label is explained in the \fImetrics\fP plugin documentation.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
autopath my\-resolv.conf
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Use \fB\fCmy-resolv.conf\fR as the file to get the search path from. This file only needs to have one line:
|
|
\fB\fCsearch domain1 domain2 ...\fR
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
autopath @kubernetes
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Use the search path dynamically retrieved from the \fIkubernetes\fP plugin.
|
|
|
|
.SH "KNOWN ISSUES"
|
|
.PP
|
|
In Kubernetes, \fIautopath\fP can derive the wrong namespace of a client Pod (and therefore wrong search path)
|
|
in the following case. To properly build the search path of a client \fIautopath\fP needs to
|
|
know the namespace of the a Pod making a DNS request. To do this, it relies on the
|
|
\fIkubernetes\fP plugin's Pod cache to resolve the client's IP address to a Pod. The Pod cache is maintained by
|
|
an API watch on Pods. When Pod IP assignments change, the Kubernetes API notifies CoreDNS via the API watch.
|
|
However, that notification is not instantaneous. In the case that a Pod is deleted, and it's IP is
|
|
immediately provisioned to a Pod in another namespace, and that new Pod make a DNS lookup \fIbefore\fP the API watch
|
|
can notify CoreDNS of the change, \fIautopath\fP will resolve the IP to the previous Pod's namespace.
|
|
|
|
.PP
|
|
In Kubernetes, \fIautopath\fP is not compatible with Pods running from Windows nodes.
|
|
|
|
.PP
|
|
If the server side search ultimately results in a negative answer (e.g. \fB\fCNXDOMAIN\fR), then the client will
|
|
fruitlessly search all paths manually, thus negating the \fIautopath\fP optimization.
|
|
|