diff options
Diffstat (limited to 'man/coredns-etcd.7')
| -rw-r--r-- | man/coredns-etcd.7 | 58 |
1 files changed, 36 insertions, 22 deletions
diff --git a/man/coredns-etcd.7 b/man/coredns-etcd.7 index 11ffb385b..57d8a2e5c 100644 --- a/man/coredns-etcd.7 +++ b/man/coredns-etcd.7 @@ -1,20 +1,25 @@ -.\" Generated by Mmark Markdown Processer - mmark.nl -.TH "COREDNS-ETCD" 7 "July 2019" "CoreDNS" "CoreDNS Plugins" +.\" Generated by Mmark Markdown Processer - mmark.miek.nl +.TH "COREDNS-ETCD" 7 "August 2019" "CoreDNS" "CoreDNS Plugins" .SH "NAME" .PP -\fIetcd\fP - enables reading zone data from an etcd version 3 instance. +\fIetcd\fP - enable 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. + +.PP The data in 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 should also work just like SkyDNS. +\[la]https://github.com/skynetservices/skydns\[ra]. It works just like SkyDNS. .PP -The etcd plugin makes extensive use of the forward plugin to forward and query other servers in the +The etcd plugin makes extensive use of the \fIforward\fP plugin to forward and query other servers in the network. .SH "SYNTAX" @@ -28,7 +33,7 @@ etcd [ZONES...] .RE .IP \(bu 4 -\fBZONES\fP zones etcd should be authoritative for. +\fBZONES\fP zones \fIetcd\fP should be authoritative for. .PP @@ -86,23 +91,23 @@ is needed. .SH "SPECIAL BEHAVIOUR" .PP -CoreDNS etcd 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. +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. .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, etcdv3 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. +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, etcdv3 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 etcdv3 in certain cases. -.SH "MIGRATION TO "\fB\fCetcdv3\fR" API" -.PP -With CoreDNS release \fB\fC1.2.0\fR, you'll need to migrate existing CoreDNS related data (if any) on your etcd server to etcdv3 API. This is because with \fB\fCetcdv3\fR support, CoreDNS can't see the data stored to an etcd server using \fB\fCetcdv2\fR API. - -.PP -Refer this blog by CoreOS team -\[la]https://coreos.com/blog/migrating-applications-etcd-v3.html\[ra] to migrate to etcdv3 API. - .SH "EXAMPLES" .PP This is the default SkyDNS setup, with everything specified in full: @@ -159,12 +164,19 @@ etcd skydns.local { .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. +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 off. You can check this document -\[la]https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes\[ra] for details. +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 @@ -210,7 +222,9 @@ reverse.skydns.local. .SS "ZONE NAME AS A RECORD" .PP -The zone name itself can be used as A 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: +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 |