372 lines
8.7 KiB
Groff
372 lines
8.7 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-ETCD" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIetcd\fP - enables SkyDNS service discovery from etcd.
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
The \fIetcd\fP plugin implements the (older) SkyDNS service discovery service. It is \fInot\fP suitable as
|
|
a generic DNS zone data plugin. Only a subset of DNS record types are implemented, and subdomains
|
|
and delegations are not handled at all. The plugin will also recursively descend the tree and return
|
|
all records found, see "Special Behavior" below for details.
|
|
|
|
.PP
|
|
The data in the etcd instance has to be encoded as
|
|
a message
|
|
\[la]https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26\[ra]
|
|
like SkyDNS
|
|
\[la]https://github.com/skynetservices/skydns\[ra]. It works just like SkyDNS.
|
|
|
|
.PP
|
|
The \fIetcd\fP plugin makes extensive use of the \fIforward\fP plugin to forward and query other servers in the
|
|
network - if that plugin has been enabled as well.
|
|
|
|
.SH "SYNTAX"
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
etcd [ZONES...]
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fBZONES\fP zones \fIetcd\fP should be authoritative for.
|
|
|
|
|
|
.PP
|
|
The path will default to \fB\fC/skydns\fR the local etcd3 proxy (http://localhost:2379
|
|
\[la]http://localhost:2379\[ra]). If no zones are
|
|
specified the block's zone will be used as the zone.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
etcd [ZONES...] {
|
|
fallthrough [ZONES...]
|
|
path PATH
|
|
endpoint ENDPOINT...
|
|
credentials USERNAME PASSWORD
|
|
tls CERT KEY CACERT
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.IP \(bu 4
|
|
\fB\fCfallthrough\fR If zone matches but no record can be generated, pass request to the next plugin.
|
|
If \fB[ZONES...]\fP is omitted, then fallthrough happens for all zones for which the plugin
|
|
is authoritative. If specific zones are listed (for example \fB\fCin-addr.arpa\fR and \fB\fCip6.arpa\fR), then only
|
|
queries for those zones will be subject to fallthrough.
|
|
.IP \(bu 4
|
|
\fBPATH\fP the path inside etcd. Defaults to "/skydns".
|
|
.IP \(bu 4
|
|
\fBENDPOINT\fP the etcd endpoints. Defaults to "http://localhost:2379"
|
|
\[la]http://localhost:2379"\[ra].
|
|
.IP \(bu 4
|
|
\fB\fCcredentials\fR is used to set the \fBUSERNAME\fP and \fBPASSWORD\fP for accessing the etcd cluster.
|
|
.IP \(bu 4
|
|
\fB\fCtls\fR followed by:
|
|
|
|
.RS
|
|
.IP \(en 4
|
|
no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
|
|
.IP \(en 4
|
|
a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
|
|
.IP \(en 4
|
|
two arguments - path to cert PEM file, the path to private key PEM file - if the server certificate is signed by a system-installed CA and a client certificate is needed
|
|
.IP \(en 4
|
|
three arguments - path to cert PEM file, path to client private key PEM file, path to CA PEM
|
|
file - if the server certificate is not signed by a system-installed CA and client certificate
|
|
is needed.
|
|
|
|
.RE
|
|
|
|
|
|
.SH "SPECIAL BEHAVIOUR"
|
|
.PP
|
|
The \fIetcd\fP plugin leverages directory structure to look for related entries. For example
|
|
an entry \fB\fC/skydns/test/skydns/mx\fR would have entries like \fB\fC/skydns/test/skydns/mx/a\fR,
|
|
\fB\fC/skydns/test/skydns/mx/b\fR and so on. Similarly a directory \fB\fC/skydns/test/skydns/mx1\fR will have all
|
|
\fB\fCmx1\fR entries. Note this plugin will search through the entire (sub)tree for records. In case of the
|
|
first example, a query for \fB\fCmx.skydns.text\fR will return both the contents of the \fB\fCa\fR and \fB\fCb\fR records.
|
|
If the directory extends deeper those records are returned as well.
|
|
|
|
.PP
|
|
With etcd3, support for hierarchical keys are
|
|
dropped
|
|
\[la]https://coreos.com/etcd/docs/latest/learning/api.html\[ra]. This means there are no directories
|
|
but only flat keys with prefixes in etcd3. To accommodate lookups, the \fIetcd\fP plugin now does a lookup
|
|
on prefix \fB\fC/skydns/test/skydns/mx/\fR to search for entries like \fB\fC/skydns/test/skydns/mx/a\fR etc, and
|
|
if there is nothing found on \fB\fC/skydns/test/skydns/mx/\fR, it looks for \fB\fC/skydns/test/skydns/mx\fR to
|
|
find entries like \fB\fC/skydns/test/skydns/mx1\fR.
|
|
|
|
.PP
|
|
This causes two lookups from CoreDNS to etcd in certain cases.
|
|
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
This is the default SkyDNS setup, with everything specified in full:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
skydns.local {
|
|
etcd {
|
|
path /skydns
|
|
endpoint http://localhost:2379
|
|
}
|
|
prometheus
|
|
cache
|
|
loadbalance
|
|
}
|
|
|
|
\&. {
|
|
forward . 8.8.8.8:53 8.8.4.4:53
|
|
cache
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Or a setup where we use \fB\fC/etc/resolv.conf\fR as the basis for the proxy and the upstream
|
|
when resolving external pointing CNAMEs.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
skydns.local {
|
|
etcd {
|
|
path /skydns
|
|
}
|
|
cache
|
|
}
|
|
|
|
\&. {
|
|
forward . /etc/resolv.conf
|
|
cache
|
|
}
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Multiple endpoints are supported as well.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
etcd skydns.local {
|
|
endpoint http://localhost:2379 http://localhost:4001
|
|
\&...
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Before getting started with these examples, please setup \fB\fCetcdctl\fR (with \fB\fCetcdv3\fR API) as explained
|
|
here
|
|
\[la]https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html\[ra]. This will help you to put
|
|
sample keys in your etcd server.
|
|
|
|
.PP
|
|
If you prefer, you can use \fB\fCcurl\fR to populate the \fB\fCetcd\fR server, but with \fB\fCcurl\fR the
|
|
endpoint URL depends on the version of \fB\fCetcd\fR. For instance, \fB\fCetcd v3.2\fR or before uses only
|
|
[CLIENT-URL]/v3alpha/* while \fB\fCetcd v3.5\fR or later uses [CLIENT-URL]/v3/* . Also, Key and Value must
|
|
be base64 encoded in the JSON payload. With \fB\fCetcdctl\fR these details are automatically taken care
|
|
of. You can check this document
|
|
\[la]https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes\[ra]
|
|
for details.
|
|
|
|
.SS "REVERSE ZONES"
|
|
.PP
|
|
Reverse zones are supported. You need to make CoreDNS aware of the fact that you are also
|
|
authoritative for the reverse. For instance if you want to add the reverse for 10.0.0.0/24, you'll
|
|
need to add the zone \fB\fC0.0.10.in-addr.arpa\fR to the list of zones. Showing a snippet of a Corefile:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
etcd skydns.local 10.0.0.0/24 {
|
|
\&...
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Next you'll need to populate the zone with reverse records, here we add a reverse for
|
|
10.0.0.127 pointing to reverse.skydns.local.
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% etcdctl put /skydns/arpa/in\-addr/10/0/0/127 '{"host":"reverse.skydns.local."}'
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Querying with dig:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% dig @localhost \-x 10.0.0.127 +short
|
|
reverse.skydns.local.
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SS "ZONE NAME AS A RECORD"
|
|
.PP
|
|
The zone name itself can be used as an \fB\fCA\fR record. This behavior can be achieved by writing special
|
|
entries to the ETCD path of your zone. If your zone is named \fB\fCskydns.local\fR for example, you can
|
|
create an \fB\fCA\fR record for this zone as follows:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% etcdctl put /skydns/local/skydns/ '{"host":"1.1.1.1","ttl":60}'
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
If you query the zone name itself, you will receive the created \fB\fCA\fR record:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% dig +short skydns.local @localhost
|
|
1.1.1.1
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
If you would like to use DNS RR for the zone name, you can set the following:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% etcdctl put /skydns/local/skydns/x1 '{"host":"1.1.1.1","ttl":60}'
|
|
% etcdctl put /skydns/local/skydns/x2 '{"host":"1.1.1.2","ttl":60}'
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
If you query the zone name now, you will get the following response:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% dig +short skydns.local @localhost
|
|
1.1.1.1
|
|
1.1.1.2
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SS "ZONE NAME AS AAAA RECORD"
|
|
.PP
|
|
If you would like to use \fB\fCAAAA\fR records for the zone name too, you can set the following:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% etcdctl put /skydns/local/skydns/x3 '{"host":"2003::8:1","ttl":60}'
|
|
% etcdctl put /skydns/local/skydns/x4 '{"host":"2003::8:2","ttl":60}'
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
If you query the zone name for \fB\fCAAAA\fR now, you will get the following response:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% dig +short skydns.local AAAA @localhost
|
|
2003::8:1
|
|
2003::8:2
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SS "SRV RECORD"
|
|
.PP
|
|
If you would like to use \fB\fCSRV\fR records, you can set the following:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% etcdctl put /skydns/local/skydns/x5 '{"host":"skydns\-local.server","ttl":60,"priority":10,"port":8080}'
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
Please notice that the key \fB\fChost\fR is the \fB\fCtarget\fR in \fB\fCSRV\fR, so it should be a domain name.
|
|
|
|
.PP
|
|
If you query the zone name for \fB\fCSRV\fR now, you will get the following response:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% dig +short skydns.local SRV @localhost
|
|
10 100 8080 skydns\-local.server.
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SS "TXT RECORD"
|
|
.PP
|
|
If you would like to use \fB\fCTXT\fR records, you can set the following:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% etcdctl put /skydns/local/skydns/x6 '{"ttl":60,"text":"this is a random text message."}'
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.PP
|
|
If you query the zone name for \fB\fCTXT\fR now, you will get the following response:
|
|
|
|
.PP
|
|
.RS
|
|
|
|
.nf
|
|
% dig +short skydns.local TXT @localhost
|
|
"this is a random text message."
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
If you want to \fB\fCround robin\fR A and AAAA responses look at the \fIloadbalance\fP plugin.
|
|
|