From b9a6dba2cb11889fc4a8b58ba03d9c53cfd87557 Mon Sep 17 00:00:00 2001 From: Miek Gieben Date: Mon, 10 Aug 2020 15:20:01 +0200 Subject: [PATCH] plugin/etcd: update documention (#4049) * plugin/etcd: update documention Make clear(er) how this plugin find records. Fixes: #4048 Signed-off-by: Miek Gieben * Update plugin/etcd/README.md Co-authored-by: Chris O'Haver * Update plugin/etcd/README.md Co-authored-by: Chris O'Haver Co-authored-by: Chris O'Haver --- plugin/etcd/README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/plugin/etcd/README.md b/plugin/etcd/README.md index 9b7f75f29..b1450641c 100644 --- a/plugin/etcd/README.md +++ b/plugin/etcd/README.md @@ -8,14 +8,15 @@ The *etcd* plugin implements the (older) SkyDNS service discovery service. It is *not* 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. +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. The data in the etcd instance has to be encoded as a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26) like [SkyDNS](https://github.com/skynetservices/skydns). It works just like SkyDNS. -The etcd plugin makes extensive use of the *forward* plugin to forward and query other servers in the -network. +The *etcd* plugin makes extensive use of the *forward* plugin to forward and query other servers in the +network - if that plugin has been enabled as well. ## Syntax @@ -28,7 +29,6 @@ etcd [ZONES...] The path will default to `/skydns` the local etcd3 proxy (http://localhost:2379). If no zones are specified the block's zone will be used as the zone. -If you want to `round robin` A and AAAA responses look at the `loadbalance` plugin. ~~~ etcd [ZONES...] { @@ -61,16 +61,18 @@ etcd [ZONES...] { The *etcd* plugin leverages directory structure to look for related entries. For example an entry `/skydns/test/skydns/mx` would have entries like `/skydns/test/skydns/mx/a`, `/skydns/test/skydns/mx/b` and so on. Similarly a directory `/skydns/test/skydns/mx1` will have all -`mx1` entries. +`mx1` entries. Note this plugin will search through the entire (sub)tree for records. In case of the +first example, a query for `mx.skydns.text` will return both the contents of the `a` and `b` records. +If the directory extends deeper those records are returned as well. With etcd3, support for [hierarchical keys are dropped](https://coreos.com/etcd/docs/latest/learning/api.html). This means there are no directories -but only flat keys with prefixes in etcd3. To accommodate lookups, etcdv3 plugin now does a lookup +but only flat keys with prefixes in etcd3. To accommodate lookups, the *etcd* plugin now does a lookup on prefix `/skydns/test/skydns/mx/` to search for entries like `/skydns/test/skydns/mx/a` etc, and if there is nothing found on `/skydns/test/skydns/mx/`, it looks for `/skydns/test/skydns/mx` to find entries like `/skydns/test/skydns/mx1`. -This causes two lookups from CoreDNS to etcdv3 in certain cases. +This causes two lookups from CoreDNS to etcd in certain cases. ## Examples @@ -226,3 +228,7 @@ If you query the zone name for `TXT` now, you will get the following response: % dig +short skydns.local TXT @localhost "this is a random text message." ~~~ + +## Also See + +If you want to `round robin` A and AAAA responses look at the *loadbalance* plugin.