Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-10-31 10:13:14 -04:00
Code Issues Packages Projects Releases Wiki Activity

plugin/etcd: clarify it's not a generic backend (#3220)

Browse Source 
* plugin/etcd: clarify it's not a generic backend

Clarify the docs that this is not a generic backend.

Wrap it on 80 columns as well.

Signed-off-by: Miek Gieben <miek@miek.nl>

* Update plugin/etcd/README.md

Co-Authored-By: Chris O'Haver <cohaver@infoblox.com>

* Update plugin/etcd/README.md

Co-Authored-By: Chris O'Haver <cohaver@infoblox.com>
This commit is contained in:
Miek Gieben
2019-08-28 14:59:00 +01:00
committed by GitHub
parent 6fdf130b67
commit 2cb017928c
1 changed files with 31 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
plugin/etcd/README.md
View File

@@ -2,15 +2,19 @@
## Name
*etcd* - enables reading zone data from an etcd version 3 instance.
*etcd* - enable SkyDNS service discovery from etcd.
## Description
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.
The data in 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 should also work just like SkyDNS.
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
The etcd plugin makes extensive use of the *forward* plugin to forward and query other servers in the
network.
## Syntax
@@ -19,7 +23,7 @@ network.
etcd [ZONES...]
~~~
* **ZONES** zones etcd should be authoritative for.
* **ZONES** zones *etcd* should be authoritative for.
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.
@@ -53,18 +57,21 @@ etcd [ZONES...] {
is needed.
## Special Behaviour
CoreDNS 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.
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 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`.
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.
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
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.
## Migration to `etcdv3` API
With CoreDNS release `1.2.0`, you'll need to migrate existing CoreDNS related data (if any) on your etcd server to etcdv3 API. This is because with `etcdv3` support, CoreDNS can't see the data stored to an etcd server using `etcdv2` API.
Refer this [blog by CoreOS team](https://coreos.com/blog/migrating-applications-etcd-v3.html) to migrate to etcdv3 API.
## Examples
This is the default SkyDNS setup, with everything specified in full:
@@ -102,10 +109,16 @@ etcd skydns.local {
endpoint http://localhost:2379 http://localhost:4001
...
~~~
Before getting started with these examples, please setup `etcdctl` (with `etcdv3` API) as explained
[here](https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html). This will help you to put
sample keys in your etcd server.
Before getting started with these examples, please setup `etcdctl` (with `etcdv3` API) as explained [here](https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html). This will help you to put sample keys in your etcd server.
If you prefer, you can use `curl` to populate the `etcd` server, but with `curl` the endpoint URL depends on the version of `etcd`. For instance, `etcd v3.2` or before uses only [CLIENT-URL]/v3alpha/* while `etcd v3.5` or later uses [CLIENT-URL]/v3/* . Also, Key and Value must be base64 encoded in the JSON payload. With `etcdctl` these details are automatically taken care off. You can check [this document](https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes) for details.
If you prefer, you can use `curl` to populate the `etcd` server, but with `curl` the
endpoint URL depends on the version of `etcd`. For instance, `etcd v3.2` or before uses only
[CLIENT-URL]/v3alpha/* while `etcd v3.5` or later uses [CLIENT-URL]/v3/* . Also, Key and Value must
be base64 encoded in the JSON payload. With `etcdctl` these details are automatically taken care
of. You can check [this document](https://github.com/coreos/etcd/blob/master/Documentation/dev-guide/api_grpc_gateway.md#notes)
for details.
### Reverse zones
@@ -134,7 +147,9 @@ reverse.skydns.local.
### Zone name as A record
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 `skydns.local` for example, you can create an `A` record for this zone as follows:
The zone name itself can be used as an `A` record. This behavior can be achieved by writing special
entries to the ETCD path of your zone. If your zone is named `skydns.local` for example, you can
create an `A` record for this zone as follows:
~~~
% etcdctl put /skydns/local/skydns/ '{"host":"1.1.1.1","ttl":60}'