DNS Extension

Warning

async-dns does not support:

Additionally, while search domains are supported through configuration, detection of the system configured Search domains is only supported on systems that provide this configuration through a /etc/resolv.conf file, i.e. it isn’t supported on Windows or OSX, and none of the environment variables that are usually supported on most *nix OSes are supported.

Note

The async-dns API is marked as ApiMayChange as more information is expected to be added to the protocol.

Warning

The ability to plugin in a custom DNS implementation is expected to be removed in future versions of Akka. Users should pick one of the built in extensions.

Akka DNS is a pluggable way to interact with DNS. Implementations much implement akka.io.DnsProvider and provide a configuration block that specifies the implementation via provider-object.

DNS via Akka Discovery

Akka Discovery can be backed by the Akka DNS implementation and provides a more general API for service lookups which is not limited to domain name lookup.

To select which DnsProvider to use set akka.io.dns.resolver to the location of the configuration.

There are currently two implementations:

  • inet-address - Based on the JDK’s InetAddress. Using this will be subject to both the JVM’s DNS cache and its built in one.
  • async-dns - A native implemention of the DNS protocol that does not use any JDK classes or caches.

inet-address is the default implementation as it pre-dates async-dns, async-dns will likely become the default in the next major release.

DNS lookups can be done via the DNS extension:

Scala
val initial: Option[Dns.Resolved] = Dns(system).cache.resolve("google.com")(system, actorRef)
val cached: Option[Dns.Resolved] = Dns(system).cache.cached("google.com")
Java
Option<Dns.Resolved> initial = Dns.get(system).cache().resolve("google.com", system, actorRef);
Option<Dns.Resolved> cached = Dns.get(system).cache().cached("google.com");

Alternatively the IO(Dns) actor can be interacted with directly. However this exposes the different protocols of the DNS provider. inet-adddress uses Dns.Resolve and Dns.Resolved where as the async-dns uses DnsProtocol.Resolve and DnsProtocol.Resolved. The reason for the difference is inet-address predates async-dns and async-dns exposes additional information such as SRV records and it wasn’t possible to evolve the original API in a backward compatible way.

Inet-Address API:

Scala
val resolved: Future[Dns.Resolved] = (IO(Dns) ? Dns.Resolve("google.com")).mapTo[Dns.Resolved]
Java
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved = ask(dnsManager, new Dns.Resolve("google.com"), timeout);

Async-DNS API:

Scala
val resolved: Future[DnsProtocol.Resolved] =
  (IO(Dns) ? DnsProtocol.Resolve("google.com")).mapTo[DnsProtocol.Resolved]
Java
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved =
    ask(dnsManager, DnsProtocol.resolve("google.com"), timeout);

The Async DNS provider has the following advantages:

  • No JVM DNS caching. It is expected that future versions will expose more caching related information.
  • No blocking. InetAddress resolving is a blocking operation.
  • Exposes SRV, A and AAAA records.

SRV Records

To get DNS SRV records akka.io.dns.resolver must be set to async-dns and DnsProtocol.Resolve’s requestType must be set to DnsProtocol.Srv

Scala
val resolved: Future[DnsProtocol.Resolved] =
  (IO(Dns) ? DnsProtocol.Resolve("your-service", Srv)).mapTo[DnsProtocol.Resolved]
Java
final ActorRef dnsManager = Dns.get(system).manager();
CompletionStage<Object> resolved =
    ask(dnsManager, DnsProtocol.resolve("google.com", DnsProtocol.srvRequestType()), timeout);

The DnsProtocol.Resolved will contain akka.io.dns.SRVRecords.

Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.