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

* 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>

1 files changed, 31 insertions, 16 deletions

diff --git a/plugin/etcd/README.md b/plugin/etcd/README.md
index 2c4afbc1b..a7f44d539 100644
--- a/plugin/etcd/README.md
+++ b/plugin/etcd/README.md
@@ -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,17 +57,20 @@ 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`.
-
-This causes two lookups from CoreDNS to etcdv3 in certain cases.
 
-## Migration to `etcdv3` API
+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 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.
+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`.
 
-Refer this [blog by CoreOS team](https://coreos.com/blog/migrating-applications-etcd-v3.html) to migrate to etcdv3 API.
+This causes two lookups from CoreDNS to etcdv3 in certain cases.
 
 ## Examples
 
@@ -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}'