COREDNS-ETCD(7)

📦

version 1.15.0 · 3 versions

1.15.0 · opensuse-leap 16.0 (latest)
1.11.3 · opensuse-leap 16.0
1.14.7 · nixpkgs unstable

🦋 COREDNS-ETCD(7) 🦋

okay bestie so you're looking at the CoreDNS Plugins corner of the manual, and this one? this is COREDNS-ETCD(7). it's giving "vintage DNS energy" and honestly we're obsessed. sit down, grab a strawberry, let's get into it 💅

✨ NAME ✨

etcd — enables SkyDNS service discovery from etcd. that's the whole vibe, that's the assignment 🫶

🌸 DESCRIPTION 🌸

okay so the etcd plugin implements the (older) SkyDNS service discovery service. older. we said it. it's retro, it's iconic, but it is not suitable as a generic DNS zone data plugin — like, do not try to make it fetch your whole fancy zone for you, it will simply not slay that way 😭

only a subset of DNS record types are implemented, and subdomains and delegations are not handled at all. periodt. also, the plugin will recursively descend the tree and return all records found — see "Special Behavior" below for the details, because that part matters fr fr.

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⟩ does. it works just like SkyDNS. no cap, same energy 💜

the etcd plugin makes extensive use of the forward plugin to forward and query other servers in the network — but only if that plugin has been enabled as well. iykyk 🔥

🎀 SYNTAX 🎀

here's the bare-bones look:

etcd [ZONES...]

ZONES — zones etcd should be authoritative for. your territory, your rules 👑

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. easy peasy 🍓

and here's the full block situation:

etcd [ZONES...] {
    fallthrough [ZONES...]
    path PATH
    endpoint ENDPOINT...
    credentials USERNAME PASSWORD
    tls CERT KEY CACERT
    no_apex_fallback
}

fallthrough — if the zone matches but no record can be generated, pass the request to the next plugin. if [ZONES...] is omitted, then fallthrough happens for all zones for which the plugin is authoritative. if specific zones are listed (for example in-addr.arpa and ip6.arpa), then only queries for those zones will be subject to fallthrough. be specific or be everything, your call ✨
PATH — the path inside etcd. defaults to "/skydns". main character location 💅
ENDPOINT — the etcd endpoints. defaults to "http://localhost:2379". that's your local hangout spot 🌈
credentials — used to set the USERNAME and PASSWORD for accessing the etcd cluster. secret handshake energy 🙈
tls — followed by one of these four situations, bestie, listen up:
- no arguments, if the server certificate is signed by a system-installed CA and no client cert is needed
- a single argument that is the CA PEM file, if the server cert is not signed by a system CA and no client cert is needed
- two arguments — path to cert PEM file, the path to private key PEM file — if the server certificate is signed by a system-installed CA and a client certificate is needed
- three arguments — path to cert PEM file, path to client private key PEM file, path to CA PEM file — if the server certificate is not signed by a system-installed CA and client certificate is needed
no_apex_fallback — disables the legacy zone-root lookup used by address queries and apex-existence checks at a configured zone apex. when apex.dns.ZONE does not exist, the lookup returns a name error instead of issuing a prefix range over the complete zone subtree. ⚠️ migrate zone-apex address records to the dns/apex layout before enabling this option. like, for real, do the migration first 💀

CoreDNS sets the minimum TLS version to TLS 1.2. the maximum TLS version, TLS 1.2 cipher suites, and key exchange mechanisms use the Go crypto/tls defaults. that's just how it is, no notes 👑

min-lease-ttl — the minimum TTL for DNS records based on etcd lease duration. accepts flexible time formats like '30', '30s', '5m', '1h', '2h30m'. default: 30 seconds. ⭐
max-lease-ttl — the maximum TTL for DNS records based on etcd lease duration. accepts flexible time formats like '30', '30s', '5m', '1h', '2h30m'. default: 24 hours. ⭐

🧚 SPECIAL BEHAVIOUR 🧚

okay so 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. the way this plugin just browses 🦋

note this plugin will search through the entire (sub)tree for records. in case of the first example, a query for mx.skydns.test will return both the contents of the a and b records. and if the directory extends deeper, those records are returned as well. it's thorough. it's committed. it's not doing a half-effort look 👑

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, 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. adaptive. resourceful. we stan 💖

this causes two lookups from CoreDNS to etcd in certain cases. yeah, two. that's the trade-off and we accept it 😌

💜 BACKEND LOAD 💜

the etcd plugin does not watch or poll etcd when data changes. record lookups are driven by incoming DNS queries. an uncached lookup may issue multiple etcd requests when an exact-key fallback or an internal CNAME lookup is needed. so like, it's reactive, not proactive. very demure 💅

non-exact lookups use an etcd prefix range and return the complete subtree by design. querying a name high in the hierarchy can therefore read many keys. in particular, an A or AAAA query for a configured zone name first looks below apex.dns.ZONE. if that entry does not exist, CoreDNS falls back to the zone's root prefix for compatibility with older SkyDNS layouts. on a large zone, that fallback scans the entire zone subtree. 😭 yeah. the whole thing. it's a lot.

store zone-apex address records below the dns/apex path, as shown in the examples below, to avoid the zone-wide fallback. once all apex records use that layout, enable no_apex_fallback to prevent a missing or deleted apex entry from triggering a zone-root scan. the cache plugin reduces repeated backend reads for the same DNS question, but does not reduce the size of the first prefix response. 🫶

use the log plugin to identify the client and question name that trigger a lookup, and coredns_dns_requests_total from the prometheus plugin to measure query volume by zone and type. diagnostics, but make it cute 🌸

💅 EXAMPLES ✨

okok so first up — this is the classic default SkyDNS setup, with literally everything spelled out in full. it's giving "reference implementation" and honestly we love her for it:

skydns.local {
    etcd {
        path /skydns
        endpoint http://localhost:2379
        min-lease-ttl 60     # minimum 1 minute for lease-based records
        max-lease-ttl 1h     # maximum 1 hour for lease-based records
    }
    prometheus
    cache
    loadbalance
}

. {
    forward . 8.8.8.8:53 8.8.4.4:53
    cache
}

orrrr 🦋 here's a setup where we use /etc/resolv.conf as the basis for the proxy, and also for the upstream when we're resolving external pointing CNAMEs:

skydns.local {
    etcd {
        path /skydns
    }
    cache
}

. {
    forward . /etc/resolv.conf
    cache
}

and bestie, multiple endpoints? supported as well. no gatekeeping:

etcd skydns.local {
    endpoint http://localhost:2379 http://localhost:4001
...

before you dive into these examples pls pls pls set up etcdctl (with the etcdv3 API) as explained here: https://coreos.com/etcd/docs/latest/dev-guide/interacting_v3.html — it makes putting sample keys in your etcd server so much easier, iykyk 🫶

if you prefer, you can use curl to populate the etcd server, but heads up: 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 for details: https://github.com/etcd-io/website/blob/main/content/en/docs/v3.2/dev-guide/api_grpc_gateway.md

🔄 REVERSE ZONES

reverse zones are supported! 🔥 but you need to make CoreDNS aware of the fact that you're 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. here's a snippet of a Corefile:

etcd skydns.local 10.0.0.0/24 {
...

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:

% etcdctl put /skydns/arpa/in-addr/10/0/0/127 '{"host":"reverse.skydns.local."}'

querying with dig:

% dig @localhost -x 10.0.0.127 +short
reverse.skydns.local.

👑 ZONE NAME AS A RECORD

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/dns/apex/x1 '{"host":"1.1.1.1","ttl":60}'

if you query the zone name itself, you will receive the created A record:

% dig +short skydns.local @localhost
1.1.1.1

if you would like to use DNS RR for the zone name, you can set the following:

% etcdctl put /skydns/local/skydns/dns/apex/x1 '{"host":"1.1.1.1","ttl":60}'
% etcdctl put /skydns/local/skydns/dns/apex/x2 '{"host":"1.1.1.2","ttl":60}'

if you query the zone name now, you will get the following response:

% dig +short skydns.local @localhost
1.1.1.1
1.1.1.2

🌈 ZONE NAME AS AAAA RECORD

if you would like to use AAAA records for the zone name too, you can set the following:

% etcdctl put /skydns/local/skydns/dns/apex/x3 '{"host":"2003::8:1","ttl":60}'
% etcdctl put /skydns/local/skydns/dns/apex/x4 '{"host":"2003::8:2","ttl":60}'

if you query the zone name for AAAA now, you will get the following response:

% dig +short skydns.local AAAA @localhost
2003::8:1
2003::8:2

🌸 SRV RECORD

if you would like to use SRV records, you can set the following:

% etcdctl put /skydns/local/skydns/x5 '{"host":"skydns-local.server","ttl":60,"priority":10,"port":8080}'

pls notice that the key host is the target in SRV, so it should be a domain name 👀 (not me almost forgetting that one, it's lowkey important)

if you query the zone name for SRV now, you will get the following response:

% dig +short skydns.local SRV @localhost
10 100 8080 skydns-local.server.

🍓 TXT RECORD

if you would like to use TXT records, you can set the following:

% etcdctl put /skydns/local/skydns/x6 '{"ttl":60,"text":"this is a random text message."}'
% etcdctl put /skydns/local/skydns/x7 '{"ttl":60,"text":"this is a another random text message."}'

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."
"this is a another random text message."

👀 SEE ALSO 🌟

if you want to round robin A and AAAA responses, look at the loadbalance plugin 💖 she's the moment, fr fr.

aaaand that's the whole page bestie! 🎀 this was CoreDNS, dated October 2026, filed under COREDNS-ETCD(7) — go forth and put some keys in etcd, you're gonna slay 💅✨

📦 where this page comes from

opensuse-leap 16.0: coredns-extras 1.15.0-bp160.1.1 · Apache-2.0 AND MPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms