Lua library containing a dns client, several utilities, and a load-balancer.
The module is currently OpenResty only, and builds on top of the
- resolves A, AAAA, CNAME and SRV records, including port
- caches dns query results in memory
- synchronizes requests (a single request for many requestors, eg. when cached ttl expires under heavy load)
toipapplies a local (weighted) round-robin scheme on the query results
- ring-balancer for:
- (weighted) round-robin, and
- consistent-hashing balancing
- least-connections balancer
Copyright and license
Copyright: (c) 2016-2018 Kong, Inc.
Author: Thijs Schreijer
License: Apache 2.0
Tests are executed using
busted, but because they run inside the
resty cli tool, you must
Versioning is strictly based on Semantic Versioning
3.0.0 (7-Nov-2018) Refactor & least-connections balancer
- Refactor: split the balancer in a base class (handling DNS resolution) and the ring-balancer, implementing the algorithm.
- Added: new least-connections balancer
- Fix: since addresses could occasionally hold names instead of IP addresses,
it could happen that a call to
setPeerStatuswas unsuccessful, because the IP address would not match the name in the
addressobject. Now a
handleis returned by
getPeersignature (and return values) changed, making this a breaking change.
2.2.0 (28-Aug-2018) Fixes and a new option
- Added: a new option
validTtlthat, if set, will forcefully override the
ttlvalue of any valid answer received. Issue 48.
- Fix: remove multiline log entries, now encoded as single-line json. Issue 52.
- Fix: always inject a
localhostvalue, even if not in
/etc/hosts. Issue 54.
- Fix: added a workaround for Amazon Route 53 nameservers replying with a
ttl=0whilst the record has a non-0 ttl. Issue 56.
2.1.0 (21-May-2018) Fixes
- Fix: the round robin scheme for the balanceer starts at a randomized position to prevent all workers from starting with the same peer.
- Fix: the balancer no longer returns
port = 0for SRV records without a port, the default port is now returned.
- Fix: ipv6 nameservers with a scope in their address are not supported. This fix will simply skip them instead of throwing errors upon resolving. Fixes issue 43.
- Minor: improved logging in the balancer
- Minor: relax requery default interval for failed dns queries from 1 to 30 seconds.
2.0.0 (22-Feb-2018) Major performance improvement (balancer) and bugfixes
- BREAKING: improved performance and memory footprint for large balancers.
80-85% less memory will be used, while creation time dropped by 85-90%. Since
host:getPeer()function signature changed, this is a breaking change.
- Change: BREAKING the errors for cache-only lookup failures and empty records have been changed.
- Fix: do not fail initialization without nameservers.
- Fix: properly recognize IPv6 in square brackets from the /etc/hosts file.
- Fix: do not set success-type to types we're not looking for. Fixes Kong issue #3210.
- Fix: store records from the additional section in cache
- Fix: do not overwrite stale data in the client cache with empty records
1.0.0 (14-Dec-2017) Fixes and IPv6
- Change: BREAKING all IPv6 addresses are now returned with square brackets
- Fix: properly recognize IPv6 addresses in square brackets
0.6.3 (27-Nov-2017) Fixes and flagging unhealthy peers
- Added: flag to mark an address as failed/unhealthy, see
- Added: callback to receive balancer updates; addresses added-to/removed-from the balancer (after DNS updates for example).
- fix: SRV record entries with a weight 0 are now supported
- fix: failure of the last hostname to resolve (balancer)
0.6.2 (04-Sep-2017) Fixes and refactor
- Fix: balancer not returning hostname for named SRV entries. See issue #17
- Fix: fix an occasionally failing test
- Refactor: remove metadata from the records, instead store it in its own cache
0.6.1 (28-Jul-2017) Randomization adjusted
- Change: use a different randomizer for the ring-balancer to predictably
recreate the balancer in the exact same state (adds the
lrandomlibrary as a new dependency)
0.6.0 (14-Jun-2017) Rewritten resolver core to resolve async
- Added: resolution will be done async whenever possible. For this to work a new
setting has been introduced
staleTtlwhich determines for how long stale records will returned while a query is in progress in the background.
- Change: BREAKING! several functions that previously returned and took a resolver object no longer do so.
- Fix: no longer lookup ip adresses as names if the query type is not A or AAAA
- Fix: normalize names to lowercase after query
- Fix: set last-success types for hosts-file entries and ip-addresses
0.5.0 (25-Apr-2017) implement SEARCH and NDOTS
- Removed: BREAKING! stdError function removed.
- Added: implemented the
resolveno longer returns empty results or dns errors as a table but as lua errors (
nil + error).
resolve()have an extra result; history. A table with the list of tried names/types/results.
- Fix: timeout and retrans options from
resolv.confwere ignored by the
- Fix: nameservers with an ipv6 address would not be used properly. Also
added a flag
false) to enable the usage of ipv6 nameservers.
0.4.1 (21-Apr-2017) Bugfix
- Fix: cname record caching causing excessive dns queries, see Kong issue #2303.
0.4.0 (30-Mar-2017) Bugfixes
- Change: BREAKING! modified hash treatment, must now be an integer > 0
- Added: BREAKING! a retry counter to fall-through on hashed-retries (changes
- Fix: the MAXNS (3) was not honoured, so more than 3 nameservers would be parsed
resolv.conffile. Fixes Kong issue #2290.
- Added: two convenience hash functions
- Performance: some improvements (pre-allocated tables for the slot lists)
0.3.2 (6-Mar-2017) Bugfixes
- Fix: Cleanup disabled addresses but did not delete them, causing errors when they were repeatedly added/removed
- Fix: potential racecondition when re-querying dns records
- Fix: potential memoryleak when a balancer object was released with a running timer
0.3.1 (22-Feb-2017) Bugfixes
- Kubernetes dns returns an SRV record for individual nodes, where the target is the same name again (hence causing a recursive loop). Now those entries will be removed, and if nothing is left, it will fail the SRV lookup, causing a fall-through to the next record type.
- Kubernetes tends to return a port of 0 if none is provided/set, hence the
toip()function now ignores a
port=0and falls back on the port passed in.
0.3.0 (8-Nov-2016) Major breaking update
- breaking: renamed a lot of things; method names, module names, etc. pretty much breaks everything... also releasing under a new name
- feature: udp function
- fix: do not synchronize dns queries for ttl=0 requests (client)
- fix: full test coverage and accompanying fixes (ring-balancer)
- feature: auto-retry for failed dns queries (ring-balancer)
- feature: updating weights is now supported without removing/re-adding (ring-balancer)
- change: auto-retry interval configurable for failed dns queries (ring-balancer)
- change: max life-time interval configurable for ttl=0 dns records (ring-balancer)
0.2.1 (24-Oct-2016) Bugfix
toip()failed on SRV records with only 1 entry
0.2 (18-Oct-2016) Added the balancer
- fix: was creating resolver objects even if serving from cache
- change: change resolver order (SRV is now first by default) for dns servers that create both SRV and A records for each entry
- feature: make resolver order configurable
- feature: ring-balancer (experimental, no full test coverage yet)
- other: more test coverage for the dns client