etcd

README

etcd

etcd enables reading zone data from an etcd instance. The data in etcd has to be encoded as a message like SkyDNS. It should also work just like SkyDNS.

The etcd middleware makes extensive use of the proxy middleware to forward and query other servers in the network.

Syntax

etcd [zones...]

• zones zones etcd should be authoritative for.

The path will default to /skydns the local etcd 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 middleware.

etcd [zones...] {
    stubzones
    path /skydns
    endpoint endpoint...
    upstream address...
    tls cert key cacert
    debug
}

• stubzones enables the stub zones feature. The stubzone is only done in the etcd tree located under the first zone specified.
• path the path inside etcd. Defaults to "/skydns".
• endpoint the etcd endpoints. Defaults to "http://localhost:2397".
• upstream upstream resolvers to be used resolve external names found in etcd (think CNAMEs) pointing to external names. If you want CoreDNS to act as a proxy for clients, you'll need to add the proxy middleware.
• tls followed the cert, key and the CA's cert filenames.
• debug allow debug queries. Prefix the name with o-o.debug. to retrieve extra information in the additional section of the reply in the form of TXT records.

Examples

This is the default SkyDNS setup, with everying specified in full:

.:53 {
    etcd skydns.local {
        stubzones
        path /skydns
        endpoint http://localhost:2379
        upstream 8.8.8.8:53 8.8.4.4:53
    }
    prometheus
    cache 160 skydns.local
    loadbalance
    proxy . 8.8.8.8:53 8.8.4.4:53
}

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 0.0.10.in-addr.arpa to the list of zones. (The fun starts with IPv6 reverse zones in the ip6.arpa domain.) Showing a snippet of a Corefile:

    etcd skydns.local 0.0.10.in-addr.arpa {
        stubzones
    ...

Next you'll need to populate the zone with reverse records, here we add a reverse for 10.0.0.127 pointing to reverse.skydns.local.

% curl -XPUT http://127.0.0.1:4001/v2/keys/skydns/arpa/in-addr/10/0/0/127 \
    -d value='{"host":"reverse.skydns.local."}'

Querying with dig:

% dig @localhost -x 10.0.0.127 +short
reverse.atoom.net.

Or with debug queries enabled:

% dig @localhost -p 1053 o-o.debug.127.0.0.10.in-addr.arpa. PTR

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;o-o.debug.127.0.0.10.in-addr.arpa. IN  PTR

;; ANSWER SECTION:
127.0.0.10.in-addr.arpa. 300    IN      PTR     reverse.atoom.net.

;; ADDITIONAL SECTION:
127.0.0.10.in-addr.arpa. 300    CH      TXT     "reverse.atoom.net.:0(10,0,,false)[0,]"

Debug queries

When debug queries are enabled CoreDNS will return errors and etcd records encountered during the resolution process in the response. The general form looks like this:

skydns.test.skydns.dom.a.	300	CH	TXT	"127.0.0.1:0(10,0,,false)[0,]"

This shows the complete key as the owername, the rdata of the TXT record has: host:port(priority,weight,txt content,mail)[targetstrip,group].

Errors when communicating with an upstream will be returned as: host:0(0,0,error message,false)[0,].

An example:

www.example.org.	0	CH	TXT	"www.example.org.:0(0,0, IN A: unreachable backend,false)[0,]"

Signalling that an A record for www.example.org. was sought, but it failed with that error.

Any errors seen doing parsing will show up like this:

. 0 CH TXT "/skydns/local/skydns/r/a: invalid character '.' after object key:value pair"

which shows a.r.skydns.local. has a json encoding problem.

Documentation

Overview

Package etcd provides the etcd backend middleware.

Index

• type Etcd
  • func (e Etcd) A(zone string, state request.Request, previousRecords []dns.RR, opt Options) (records []dns.RR, debug []msg.Service, err error)
  • func (e Etcd) AAAA(zone string, state request.Request, previousRecords []dns.RR, opt Options) (records []dns.RR, debug []msg.Service, err error)
  • func (e Etcd) CNAME(zone string, state request.Request, opt Options) (records []dns.RR, debug []msg.Service, err error)
  • func (e *Etcd) Err(zone string, rcode int, state request.Request, debug []msg.Service, err error, ...) (int, error)
  • func (e *Etcd) Get(path string, recursive bool) (*etcdc.Response, error)
  • func (e Etcd) MX(zone string, state request.Request, opt Options) (records, extra []dns.RR, debug []msg.Service, err error)
  • func (e Etcd) NS(zone string, state request.Request, opt Options) (records, extra []dns.RR, debug []msg.Service, err error)
  • func (e Etcd) PTR(zone string, state request.Request, opt Options) (records []dns.RR, debug []msg.Service, err error)
  • func (e *Etcd) Records(name string, exact bool) ([]msg.Service, error)
  • func (e Etcd) SOA(zone string, state request.Request, opt Options) ([]dns.RR, []msg.Service, error)
  • func (e Etcd) SRV(zone string, state request.Request, opt Options) (records, extra []dns.RR, debug []msg.Service, err error)
  • func (e *Etcd) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)
  • func (e *Etcd) TTL(node *etcdc.Node, serv *msg.Service) uint32
  • func (e Etcd) TXT(zone string, state request.Request, opt Options) (records []dns.RR, debug []msg.Service, err error)
  • func (e *Etcd) UpdateStubZones()
• type Options
• type Stub
  • func (s Stub) ServeDNS(ctx context.Context, w dns.ResponseWriter, req *dns.Msg) (int, error)

Types

type Etcd

type Etcd struct {
	Next       middleware.Handler
	Zones      []string
	PathPrefix string
	Proxy      proxy.Proxy // Proxy for looking up names during the resolution process
	Client     etcdc.KeysAPI
	Ctx        context.Context
	Inflight   *singleflight.Group
	Stubmap    *map[string]proxy.Proxy // list of proxies for stub resolving.
	Debug      bool                    // Do we allow debug queries.
}

Etcd is a middleware talks to an etcd cluster.

func (Etcd) A

func (e Etcd) A(zone string, state request.Request, previousRecords []dns.RR, opt Options) (records []dns.RR, debug []msg.Service, err error)

A returns A records from etcd or an error.

func (Etcd) AAAA

func (e Etcd) AAAA(zone string, state request.Request, previousRecords []dns.RR, opt Options) (records []dns.RR, debug []msg.Service, err error)

AAAA returns AAAA records from etcd or an error.

func (Etcd) CNAME

func (e Etcd) CNAME(zone string, state request.Request, opt Options) (records []dns.RR, debug []msg.Service, err error)

CNAME returns CNAME records from etcd or an error.

func (*Etcd) Err

func (e *Etcd) Err(zone string, rcode int, state request.Request, debug []msg.Service, err error, opt Options) (int, error)

Err write an error response to the client.

func (*Etcd) Get

func (e *Etcd) Get(path string, recursive bool) (*etcdc.Response, error)

Get is a wrapper for client.Get that uses SingleInflight to suppress multiple outstanding queries.

func (Etcd) MX

func (e Etcd) MX(zone string, state request.Request, opt Options) (records, extra []dns.RR, debug []msg.Service, err error)

MX returns MX records from etcd. If the Target is not a name but an IP address, a name is created on the fly.

func (Etcd) NS

func (e Etcd) NS(zone string, state request.Request, opt Options) (records, extra []dns.RR, debug []msg.Service, err error)

NS returns NS records from etcd or an error.

func (Etcd) PTR

func (e Etcd) PTR(zone string, state request.Request, opt Options) (records []dns.RR, debug []msg.Service, err error)

PTR returns the PTR records, only services that have a domain name as host are included.

func (*Etcd) Records

func (e *Etcd) Records(name string, exact bool) ([]msg.Service, error)

Records looks up records in etcd. If exact is true, it will lookup just this name. This is used when find matches when completing SRV lookups for instance.

func (Etcd) SOA

func (e Etcd) SOA(zone string, state request.Request, opt Options) ([]dns.RR, []msg.Service, error)

SOA returns a SOA record from etcd.

func (Etcd) SRV

func (e Etcd) SRV(zone string, state request.Request, opt Options) (records, extra []dns.RR, debug []msg.Service, err error)

SRV returns SRV records from etcd. If the Target is not a name but an IP address, a name is created on the fly.

func (*Etcd) ServeDNS

func (e *Etcd) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements the middleware.Handler interface.

func (*Etcd) TTL

func (e *Etcd) TTL(node *etcdc.Node, serv *msg.Service) uint32

TTL returns the smaller of the etcd TTL and the service's TTL. If neither of these are set (have a zero value), a default is used.

func (Etcd) TXT

func (e Etcd) TXT(zone string, state request.Request, opt Options) (records []dns.RR, debug []msg.Service, err error)

TXT returns TXT records from etcd or an error.

func (*Etcd) UpdateStubZones

func (e *Etcd) UpdateStubZones()

UpdateStubZones checks etcd for an update on the stubzones.

type Options

type Options struct {
	Debug string // This is a debug query. A query prefixed with debug.o-o
}

Options are extra options that can be specified for a lookup.

type Stub

type Stub struct {
	*Etcd
	Zone string // for what zone (and thus what nameservers are we called)
}

Stub wraps an Etcd. We have this type so that it can have a ServeDNS method.

func (Stub) ServeDNS

func (s Stub) ServeDNS(ctx context.Context, w dns.ResponseWriter, req *dns.Msg) (int, error)

ServeDNS implements the middleware.Handler interface.