Eureka DNS server

eureka-dns-server is RFC1035/2782 compatible DNS server interface to Netflix eureka service registry which can be ran as a standalone daemon or embedded in any java application including eureka server itself.

Services registered in eureka registry are being exposed as DNS names without need to contact eureka registry via it's REST interface, which can be a cumbersome task in languages without native eureka-client support (javascript, ruby, python). Accessing your service can be as easy as:

curl http://my-service.service.eureka/

IPv6 support

Server supports automatic discovery of available IP addresses and will bind all of them by default, including IPv6 ones. AAAA records are being returned for service instances that are registered to eureka service registry with IPv6 address.

DNS interface

DNS interface is minimal and all queries should be in the following form:

<name>.service.<domain> for queries in default eureka region, where name is registered service name and domain is eureka dns server top level domain name
<name>.service.<region>.<domain> where region is some configured eureka region and where default is an alias for default eureka client configured region.

A/AAAA lookups

$ dig @localhost -p 8553  myapp.service.eureka 

;; QUESTION SECTION:
;myapp.service.eureka.       IN      A

;; ANSWER SECTION:
myapp.service.eureka. 5      IN      A       10.11.3.142

IPv6 records are being returned as well if there are services registered to eureka using IPv6 address:

$ dig @localhost -p 8553  myapp.service.eureka AAAA

;; QUESTION SECTION:
;myapp.service.eureka.       IN      AAAA

;; ANSWER SECTION:
myapp.service.eureka. 5      IN      A       ::1

TXT lookups

Asking for service TXT record returns list of active urls for given service:

$ dig @localhost -p 8553  myapp.service.eureka TXT

;; QUESTION SECTION:
;myapp.service.eureka.       IN      TXT

;; ANSWER SECTION:
myapp.service.eureka. 5      IN      TXT     "http://10.11.3.142:32769/"

SRV lookups

normal SRV lookup

$ dig @localhost -p 8553  other-app.service.eureka SRV

;; QUESTION SECTION:
;other-app.service.eureka.      IN      SRV

;; ANSWER SECTION:
other-app.service.eureka. 5     IN      SRV     1 10 8080 ip-10-11-4-219.us-west-2.compute.internal.
other-app.service.eureka. 5     IN      SRV     1 10 8080 v6-host.us-west-2.compute.internal.

;; ADDITIONAL SECTION:
ip-10-11-4-219.us-west-2.compute.internal. 5 IN A 10.11.4.219
v6-host.us-west-2.compute.internal.        5 IN A ::1

RFC2782 SRV lookup

RFC2782 are supported as well:

$ dig @localhost -p 8553 _other-app._tcp.service.eureka SRV

;; QUESTION SECTION:
;_other-app._tcp.service.eureka.      IN      SRV

;; ANSWER SECTION:
_other-app._tcp.service.eureka. 5     IN      SRV     1 10 8080 ip-10-11-4-219.us-west-2.compute.internal.
_other-app._tcp.service.eureka. 5     IN      SRV     1 10 8080 v6-host.us-west-2.compute.internal.

;; ADDITIONAL SECTION:
ip-10-11-4-219.us-west-2.compute.internal. 5 IN A 10.11.4.219
v6-host.us-west-2.compute.internal.        5 IN A ::1

Limitations

Eureka dns server doesn't allow DNS lookups over TCP, therefore clients can easily hit infamous DNS 512 byte payload size limit or may receive truncated response without being aware of it. This should not be a problem if eureka-dns-server is just a delegate resolver for a single domain for an existing DNS server (bind, unbound, dnsmasq), because these services speak EDNS0 and are commonly able to process UDP packets with payload size up to 4096 bytes.

Usage

To use eureka-dns-server, you need at least java 8 runtime, java 11 works as well.

maven

release

<dependency>
    <groupId>com.github.bfg.eureka</groupId>
    <artifactId>eureka-dns-server</artifactId>
    <version>x.y.z</version>
</dependency>

snapshot

<repositories>
  <repository>
    <id>snapshots-repo</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases><enabled>false</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.github.bfg.eureka</groupId>
    <artifactId>eureka-dns-server</artifactId>
    <version>x.y.z-SNAPSHOT</version>
  </dependency>
</dependencies>

gradle

release

dependencies {
  implementation  "com.github.bfg.eureka:eureka-dns-server:x.y.z"
}

snapshot

repositories {
  mavenLocal()
  mavenCentral()
  maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
}

dependencies {
  implementation  "com.github.bfg.eureka:eureka-dns-server:x.y.z-SNAPSHOT"
}

Running

This project is designed to be easy to run and embed to existing apps. It can be ran as a standalone daemon, as a docker container or embedded as a completely standalone component in any java based application including eureka server itself.

Embedded in eureka server

Eureka dns server can run embedded in any spring-cloud-netflix enabled application by annotating application starter class with @EnableEurekaDnsServer. You can customize it's settings in application.yml file:

eureka:
  dns:
    server:
      # dns server is disabled by default
      enabled: true

      # server listening port, default: 8553
      port: 8553

      # comma separated list of listening addresses, by default all bound listening addresses are used
      # addresses: 127.0.0.1
      
      # top-level domain to use, default: eureka
      domain: eureka

      # DNS record TTL in seconds, default: 5
      ttl: 5
      
      # maximum number of A/AAAA/SRV/TXT records to return in response to a DNS query, default: 5
      max-responses: 5
      
      # maximum number of worker threads to use, default: 1
      # set to 0 to automatically size eventloop according to number of available cpu cores.
      max-threads: 1
      
      # prefer to use native (epoll/kqueue) backed netty event loop to achieve maximum performance, default: true
      prefer-native-transport: false
            
      # log dns queries?
      log-queries: true

Standalone daemon

eureka-dns-server-standalone subproject contains eureka-dns-server packaged as runnable uberjar with simple command line interface.

Usage: <main class> [-hlV] [-c=<eurekaPropertiesFile>] [-p=<port>]
                    [-t=<threads>] [-e=<eurekaUrls>]...
  -c, --config=<eurekaPropertiesFile>
                            Path to eureka properties file.
  -e, --eureka-url=<eurekaUrls>
                            Comma separated list of eureka server URLs.
  -p, --port=<port>         DNS server listening port.
  -t, --threads=<threads>   Number of working threads, set only if native transport
                              is available; setting this number to 0 sets number of
                              workers to number of available CPU cores.
  -l, --log-queries         Log received queries.
  -h, --help                Show this help message and exit.
  -V, --version             Print version information and exit.

Running as docker image

eureka-dns-server is standalone module packaged as docker container; it's usage is exactly the same as standalone daemon, just don't forget to expose listening port:

docker run -m 384m -it --rm -p 8553:8553/udp gracnar/eureka-dns-server -e http://eureka.example.com/eureka

Embedding in your application

Embedding this project in your application is straightforward:

val server = EurekaDnsServer.builder()
  .setPort(9553)
  .setEurekaClient(eurekaClient)
  .build();

server.start();

If you want to achieve maximum performance you should include netty native transport dependencies to classpath.

DNS zone forwarding

Eureka DNS server is meant to be just a delegated resolver for a single domain; this means that you need to set up your current DNS server in your network to delegate DNS queries for .eureka domain to eureka dns server. Please read excellent consul DNS zone forwarding guide how to configure different DNS servers.

Building

To build this project you need at least JDK 11 installed, but code is compiled to JDK8 bytecode. You also need dig installed because it's being used by integration tests.

./gradlew clean build

Performance

Eureka DNS server is built on top of netty and is able to utilize epoll/kqueue based transports if they are available on classpath; eureka dns server standalone submodule and docker image already include epoll dependencies by default which enable SO_REUSEPORT functionality leading to almost linear scaling across cpu cores.

Project contains scripts/performance-test.sh script, which allows you to test actual performance of eureka dns server on your setup (requires dnsperf installed).

Server was started as docker container with host networking to reduce NAT overhead. Script was invoked like this:

./scripts/performance-test.sh {existing-a,existing-b,non-existing}.service.eureka

Here are figures on my laptop with i7-8550u CPU on linux:

1 worker thread: docker run -it --rm -m384m --network host gracnar/eureka-dns-server -e http://eureka.example.com/eureka

[Status] Command line: dnsperf -s 127.0.0.1 -p 8553 -l 20 -c 100
[Status] Sending queries (to 127.0.0.1)
[Status] Started at: Mon Feb 25 02:14:23 2019
[Status] Stopping after 20.000000 seconds
[Status] Testing complete (time limit)

Statistics:

  Queries sent:         1484420u
  Queries completed:    1484420u (100.00%)
  Queries lost:         0u (0.00%)

  Response codes:       NOERROR 990513u (66.73%), NXDOMAIN 493907u (33.27%)
  Average packet size:  request 42, response 69
  Run time (s):         20.001198
  Queries per second:   74216.554428

  Average Latency (s):  0.001285 (min 0.000030, max 0.017320)
  Latency StdDev (s):   0.000369

all available worker threads: docker run -it --rm -m384m --network host gracnar/eureka-dns-server -e http://eureka.example.com/eureka -t 0

[Status] Command line: dnsperf -s 127.0.0.1 -p 8553 -l 20 -c 100
[Status] Sending queries (to 127.0.0.1)
[Status] Started at: Wed Feb 27 00:52:33 2019
[Status] Stopping after 20.000000 seconds
[Status] Testing complete (time limit)

Statistics:

  Queries sent:         3578467u
  Queries completed:    3578467u (100.00%)
  Queries lost:         0u (0.00%)

  Response codes:       NOERROR 2147785u (60.02%), NXDOMAIN 1430682u (39.98%)
  Average packet size:  request 41, response 65
  Run time (s):         20.000170
  Queries per second:   178921.829164

  Average Latency (s):  0.000157 (min 0.000013, max 0.068128)
  Latency StdDev (s):   0.000571

Releasing

Publishing releases to maven central is a bit tricky; project needs to align with maven central requirements. Docker image is published to docker hub automatically by CI.

Create and publish PGP key

gpg --full-gen-key

publish created public key to public key registry

gpg --send-key --keyserver pool.sks-keyservers.net <keyid>

setup ~/.gradle/gradle.properties

#
# gradle.properties
#

# requires useGpgCmd() signing {} block
signing.gnupg.keyName=<keyid>

# vim:syntax=jproperties
# EOF

Create release

git checkout master
./gradlew release

Publish release to maven central staging repository

checkout correct tag

git checkout x.y.z

build the project

./gradlew clean build

publish release to Sonatype central staging

./gradlew publish

follow Sonatype OSSRH instructions to release the publication

linking12/eureka-dns-server