COREDNS-LOADBALANCE(7)

💅 COREDNS-LOADBALANCE 💅

okay so bestie, gather round, because this little plugin called loadbalance is genuinely iconic. it lives in CoreDNS (the plugin collection, iykyk) and its whole job is: randomizes the order of A, AAAA and MX records and optionally prefers specific subnets. that's the vibe. periodt.

---

✨ DESCRIPTION ✨

so loadbalance is basically a round-robin DNS load balancer, and the way it slays is by randomizing the order of A, AAAA, and MX records in the answer. like, it shuffles them. that's the whole trick. 🎀

there's a Wikipedia page about round-robin DNS that talks about the pros and cons of this setup — it's over at https://en.wikipedia.org/wiki/Round-robin_DNS if you wanna go read it, no pressure.

and here's the detail that people sleep on: it will take care to sort any CNAMEs before any address records, because some stub resolver implementations (like glibc) are particular about that. like, they will genuinely throw a fit if you get it backwards. so the plugin handles it for you. 🫶

---

🦋 SYNTAX 🦋

loadbalance [round_robin | weighted WEIGHTFILE] {
            reload DURATION
            prefer CIDR [CIDR...]
}

• round_robin policy randomizes the order of A, AAAA, and MX records applying a uniform probability distribution. this is the default load balancing policy — so if you don't pick anything, this is what you get. no cap. ✨
• weighted policy assigns weight values to IPs to control the relative likelihood of particular IPs to be returned as the first (top) A/AAAA record in the answer. big important caveat though: it does not shuffle all the records in the answer, it is only concerned about the first A/AAAA record returned in the answer. so don't come for it expecting a full reshuffle, that's not the assignment. 💅

additionally, the plugin supports subnet-based ordering using the prefer directive, which reorders A/AAAA records so that IPs from preferred subnets appear first. 🌸

• WEIGHTFILE is the file containing the weight values assigned to IPs for various domain names. if the path is relative, the path from the root plugin will be prepended to it. the format is explained below in the Weightfile section (yes, the next one, keep scrolling bestie). 🍓
• DURATION interval to reload WEIGHTFILE and update weight assignments if there are changes in the file. the default value is 30s. a value of 0s means to not scan for changes and reload. like, at all. hands off. 🙈

---

👑 WEIGHTFILE 👑

the generic weight file syntax goes like this:

domain-name1
ip11 weight11
ip12 weight12
ip13 weight13

domain-name2
ip21 weight21
ip22 weight22

where ipXY is an IP address for domain-nameX and weightXY is the weight value associated with that IP. the weight values are in the range of [1,255]. that's the range, don't try to be cute and go outside it. 🔥

okay so what does the weighted policy actually do with all this? it selects one of the address record in the result list and moves it to the top (first) position in the list. the random selection takes into account the weight values assigned to the addresses in the weight file. and — super important — if an address in the result list is associated with no weight value in the weight file then the default weight value "1" is assumed for it when the selection is performed. so no weight value doesn't mean "excluded", it means "you get a 1, congrats". 💜

---

🌈 EXAMPLES 🌈

load balance replies coming back from Google Public DNS:

. {
    loadbalance round_robin
    forward . 8.8.8.8 8.8.4.4
}

use the weighted strategy to load balance replies supplied by the file plugin. we assign weight vales 3, 1 and 2 to the IPs 100.64.1.1, 100.64.1.2 and 100.64.1.3, respectively. these IPs are addresses in A records for the domain name www.example.com defined in the ./db.example.com zone file. the ratio between the number of answers in which 100.64.1.1, 100.64.1.2 or 100.64.1.3 is in the top (first) A record should converge to 3 : 1 : 2. (e.g. there should be twice as many answers with 100.64.1.3 in the top A record than with 100.64.1.2). the math is mathing. ⭐

Corefile:

example.com {
        file ./db.example.com {
                reload 10s
        }
        loadbalance weighted ./db.example.com.weights {
                    reload 10s
        }
}

weight file ./db.example.com.weights:

www.example.com
100.64.1.1 3
100.64.1.2 1
100.64.1.3 2

💖 SUBNET PRIORITIZATION 💖

prioritize IPs from 10.9.20.0/24 and 192.168.1.0/24:

. {
    loadbalance round_robin {
        prefer 10.9.20.0/24 192.168.1.0/24
    }
    forward . 1.1.1.1
}

if the DNS response includes multiple A/AAAA records, the plugin will reorder them to place the ones matching preferred subnets first. your faves get front-row seats. 🧚

---

ngl bestie, the whole thing is basically "shuffle the records but keep the CNAMEs up front and optionally promote your favorite subnets" and honestly? ate. 🔥

---

mwah, that's the whole page 💋 — brought to you by CoreDNS, dated March 2026, and yeah the manual name is COREDNS-LOADBALANCE for anyone keeping score. now go configure something iconic. 🦋✨