mirror of
https://github.com/coredns/coredns.git
synced 2025-10-30 17:53:21 -04:00
96 lines
3.0 KiB
Groff
96 lines
3.0 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-AUTOPATH" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIautopath\fP - allows for server-side search path completion.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
If the \fIautopath\fP plugin sees a query that matches the first element of the configured search path, it 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 the "Bugs" 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 by \fIautopath\fP.
|
|
|
|
.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 "BUGS"
|
|
.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.
|
|
|