release: up version to 1.2.1 (#2057)

up the version and add the man-pages.

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

man/coredns-etcd.7

@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "COREDNS\-ETCD" "7" "July 2018" "CoreDNS" "CoreDNS plugins"
+.TH "COREDNS\-ETCD" "7" "August 2018" "CoreDNS" "CoreDNS plugins"
 .
 .SH "NAME"
 \fIetcd\fR \- enables reading zone data from an etcd version 3 instance\.
@@ -87,13 +87,19 @@ three arguments \- path to cert PEM file, path to client private key PEM file, p
 CoreDNS etcd plugin leverages directory structure to look for related entries\. For example an entry \fB/skydns/test/skydns/mx\fR would have entries like \fB/skydns/test/skydns/mx/a\fR, \fB/skydns/test/skydns/mx/b\fR and so on\. Similarly a directory \fB/skydns/test/skydns/mx1\fR will have all \fBmx1\fR entries\.
 .
 .P
-With etcd3, support for hierarchial keys are dropped \fIhttps://coreos\.com/etcd/docs/latest/learning/api\.html\fR\. This means there are no directories but only flat keys with prefixes in etcd3\. To accomodate lookups, etcdv3 plugin now does a lookup on prefix \fB/skydns/test/skydns/mx/\fR to search for entries like \fB/skydns/test/skydns/mx/a\fR etc, and if there is nothing found on \fB/skydns/test/skydns/mx/\fR, it looks for \fB/skydns/test/skydns/mx\fR to find entries like \fB/skydns/test/skydns/mx1\fR\.
+With etcd3, support for hierarchial keys are dropped \fIhttps://coreos\.com/etcd/docs/latest/learning/api\.html\fR\. 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/skydns/test/skydns/mx/\fR to search for entries like \fB/skydns/test/skydns/mx/a\fR etc, and if there is nothing found on \fB/skydns/test/skydns/mx/\fR, it looks for \fB/skydns/test/skydns/mx\fR to find entries like \fB/skydns/test/skydns/mx1\fR\.
 .
 .P
 This causes two lookups from CoreDNS to etcdv3 in certain cases\.
 .
+.SH "MIGRATION TO <code>ETCDV3</code> API"
+With CoreDNS release \fB1\.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 \fBetcdv3\fR support, CoreDNS can\'t see the data stored to an etcd server using \fBetcdv2\fR API\.
+.
+.P
+Refer this blog by CoreOS team \fIhttps://coreos\.com/blog/migrating\-applications\-etcd\-v3\.html\fR to migrate to etcdv3 API\.
+.
 .SH "EXAMPLES"
-This is the default SkyDNS setup, with everying specified in full:
+This is the default SkyDNS setup, with everything specified in full:
 .
 .IP "" 4
 .
@@ -151,6 +157,12 @@ etcd skydns\.local {
 .
 .IP "" 0
 .
+.P
+Before getting started with these examples, please setup \fBetcdctl\fR (with \fBetcdv3\fR API) as explained here \fIhttps://coreos\.com/etcd/docs/latest/dev\-guide/interacting_v3\.html\fR\. This will help you to put sample keys in your etcd server\.
+.
+.P
+If you prefer, you can use \fBcurl\fR to populate the \fBetcd\fR server, but with \fBcurl\fR the endpoint URL depends on the version of \fBetcd\fR\. For instance, \fBetcd v3\.2\fR or before uses only [CLIENT\-URL]/v3alpha/\fIwhile \fBetcd v3\.5\fR or later uses [CLIENT\-URL]/v3/\fR \. Also, Key and Value must be base64 encoded in the JSON payload\. With, \fBetcdctl\fR these details are automatically taken care off\. You can check this document \fIhttps://github\.com/coreos/etcd/blob/master/Documentation/dev\-guide/api_grpc_gateway\.md#notes\fR for details\.
+.
 .SS "REVERSE ZONES"
 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 \fB0\.0\.10\.in\-addr\.arpa\fR to the list of zones\. Showing a snippet of a Corefile:
 .
@@ -173,8 +185,7 @@ Next you\'ll need to populate the zone with reverse records, here we add a rever
 .
 .nf
 
-% curl \-XPUT http://127\.0\.0\.1:4001/v2/keys/skydns/arpa/in\-addr/10/0/0/127 \e
-    \-d value=\'{"host":"reverse\.skydns\.local\."}\'
+% etcdctl put /skydns/arpa/in\-addr/10/0/0/127 \'{"host":"reverse\.skydns\.local\."}\'
 .
 .fi
 .
@@ -201,7 +212,7 @@ The zone name itself can be used A record\. This behavior can be achieved by wri
 .
 .nf
 
-% curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex \-d value=\'{"host":"1\.1\.1\.1","ttl":"60"}\'
+% etcdctl put /skydns/local/skydns/ \'{"host":"1\.1\.1\.1","ttl":60}\'
 .
 .fi
 .
@@ -222,7 +233,7 @@ If you query the zone name itself, you will receive the created \fBA\fR record:
 .IP "" 0
 .
 .P
-If you would like to use DNS RR for the zone name, you can set the following: ~~~ % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x1 \-d value=\'{"host":"1\.1\.1\.1","ttl":"60"}\' % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x2 \-d value=\'{"host":"1\.1\.1\.2","ttl":"60"}\' ~~~
+If you would like to use DNS RR for the zone name, you can set the following: ~~~ % 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"}\' ~~~
 .
 .P
 If you query the zone name now, you will get the following response:
@@ -231,7 +242,7 @@ If you query the zone name now, you will get the following response:
 .
 .nf
 
-dig +short skydns\.local @localhost
+% dig +short skydns\.local @localhost
 1\.1\.1\.1
 1\.1\.1\.2
 .
@@ -239,8 +250,31 @@ dig +short skydns\.local @localhost
 .
 .IP "" 0
 .
-.P
-If you would like to use \fBAAAA\fR records for the zone name too, you can set the following: ~~~ % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x3 \-d value=\'{"host":"2003::8:1","ttl":"60"}\' % curl \-XPUT http://127\.0\.0\.1:2379/v2/keys/skydns/local/skydns/dns/apex/x4 \-d value=\'{"host":"2003::8:2","ttl":"60"}\' ~~~
+.SS "ZONE NAME AS AAAA RECORD"
+If you would like to use \fBAAAA\fR records for the zone name too, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x3 \'{"host":"2003::8:1","ttl":"60"}\' % etcdctl put /skydns/local/skydns/x4 \'{"host":"2003::8:2","ttl":"60"}\' ~~~
 .
 .P
-If you query the zone name now for \fBAAAA\fR now, you will get the following response: ~~~ sh dig +short skydns\.local AAAA @localhost 2003::8:1 2003::8:2 ~~~
+If you query the zone name for \fBAAAA\fR now, you will get the following response: ~~~ sh % dig +short skydns\.local AAAA @localhost 2003::8:1 2003::8:2 ~~~
+.
+.SS "SRV RECORD"
+If you would like to use \fBSRV\fR records, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x5 \'{"host":"skydns\-local\.server","ttl":60,"priority":10,"port":8080}\' ~~~ Please notice that the key \fBhost\fR is the \fBtarget\fR in \fBSRV\fR, so it should be a domain name\.
+.
+.P
+If you query the zone name for \fBSRV\fR now, you will get the following response:
+.
+.IP "" 4
+.
+.nf
+
+% dig +short skydns\.local SRV @localhost
+10 100 8080 skydns\-local\.server\.
+.
+.fi
+.
+.IP "" 0
+.
+.SS "TXT RECORD"
+If you would like to use \fBTXT\fR records, you can set the following: ~~~ % etcdctl put /skydns/local/skydns/x6 \'{"ttl":60,"text":"this is a random text message\."}\' ~~~
+.
+.P
+If you query the zone name for \fBTXT\fR now, you will get the following response: ~~~ sh % dig +short skydns\.local TXT @localhost "this is a random text message\." ~~~