From 7e69b990b980067460d01c6a8da53f4176bca116 Mon Sep 17 00:00:00 2001 From: Enno <458526+ennru@users.noreply.github.com> Date: Tue, 9 Jun 2020 17:33:52 +0200 Subject: [PATCH] Docs: Discovery via DNS (#29153) --- .../akka/discovery/dns/DnsDiscoverySpec.scala | 4 -- akka-docs/src/main/paradox/discovery/index.md | 24 ++++----- akka-docs/src/main/paradox/io-dns.md | 6 +++ .../jdocs/discovery/DnsDiscoveryDocTest.java | 54 +++++++++++++++++++ .../docs/discovery/DnsDiscoveryDocSpec.scala | 43 +++++++++++++++ build.sbt | 1 + 6 files changed, 113 insertions(+), 19 deletions(-) create mode 100644 akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java create mode 100644 akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala diff --git a/akka-discovery/src/test/scala/akka/discovery/dns/DnsDiscoverySpec.scala b/akka-discovery/src/test/scala/akka/discovery/dns/DnsDiscoverySpec.scala index d497d42931..eb7b70e3b4 100644 --- a/akka-discovery/src/test/scala/akka/discovery/dns/DnsDiscoverySpec.scala +++ b/akka-discovery/src/test/scala/akka/discovery/dns/DnsDiscoverySpec.scala @@ -7,9 +7,7 @@ package akka.discovery.dns import java.net.InetAddress import scala.concurrent.duration._ - import com.typesafe.config.ConfigFactory - import akka.actor.ActorSystem import akka.discovery.{ Discovery, Lookup } import akka.discovery.ServiceDiscovery @@ -20,13 +18,11 @@ import akka.testkit.{ AkkaSpec, SocketUtil, TestKit } object DnsDiscoverySpec { val config = ConfigFactory.parseString(s""" - //#configure-dns akka { discovery { method = akka-dns } } - //#configure-dns akka { loglevel = DEBUG } diff --git a/akka-docs/src/main/paradox/discovery/index.md b/akka-docs/src/main/paradox/discovery/index.md index 51c13594f4..0903166389 100644 --- a/akka-docs/src/main/paradox/discovery/index.md +++ b/akka-docs/src/main/paradox/discovery/index.md @@ -73,6 +73,12 @@ Port can be used when a service opens multiple ports e.g. a HTTP port and an Akk ## Discovery Method: DNS +@@@ note { title="Async DNS" } + +Akka Discovery with DNS does always use the @ref[Akka-native "async-dns" implementation](../io-dns.md) (it is independent of the `akka.io.dns.resolver` setting). + +@@@ + DNS discovery maps `Lookup` queries as follows: * `serviceName`, `portName` and `protocol` set: SRV query in the form: `_port._protocol.name` Where the `_`s are added. @@ -86,27 +92,15 @@ The mapping between Akka service discovery terminology and SRV terminology: Configure `akka-dns` to be used as the discovery implementation in your `application.conf`: -@@snip[application.conf](/akka-discovery/src/test/scala/akka/discovery/dns/DnsDiscoverySpec.scala){ #configure-dns } +@@snip[application.conf](/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala){ #configure-dns } From there on, you can use the generic API that hides the fact which discovery method is being used by calling: Scala -: ```scala - import akka.discovery.ServiceDiscovery - val system = ActorSystem("Example") - // ... - val discovery = ServiceDiscovery(system).discovery - val result: Future[Resolved] = discovery.lookup("service-name", resolveTimeout = 500 milliseconds) - ``` +: @@snip[snip](/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala){ #lookup-dns } Java -: ```java - import akka.discovery.ServiceDiscovery; - ActorSystem system = ActorSystem.create("Example"); - // ... - SimpleServiceDiscovery discovery = ServiceDiscovery.get(system).discovery(); - Future result = discovery.lookup("service-name", Duration.create("500 millis")); - ``` +: @@snip[snip](/akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java){ #lookup-dns } ### DNS records used diff --git a/akka-docs/src/main/paradox/io-dns.md b/akka-docs/src/main/paradox/io-dns.md index dd1ff0db78..74a7dfa6b3 100644 --- a/akka-docs/src/main/paradox/io-dns.md +++ b/akka-docs/src/main/paradox/io-dns.md @@ -30,6 +30,12 @@ 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`. +@@@ note { title="DNS via Akka Discovery" } + +@ref[Akka Discovery](discovery/index.md) 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: diff --git a/akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java b/akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java new file mode 100644 index 0000000000..d2135faf3c --- /dev/null +++ b/akka-docs/src/test/java/jdocs/discovery/DnsDiscoveryDocTest.java @@ -0,0 +1,54 @@ +/* + * Copyright (C) 2020 Lightbend Inc. + */ + +package jdocs.discovery; + +import akka.actor.ActorSystem; +// #lookup-dns +import akka.discovery.Discovery; +import akka.discovery.ServiceDiscovery; +// #lookup-dns +import akka.testkit.javadsl.TestKit; +import docs.discovery.DnsDiscoveryDocSpec; +import org.junit.AfterClass; +import org.junit.BeforeClass; +import org.junit.Test; +import org.scalatestplus.junit.JUnitSuite; + +import java.time.Duration; +import java.util.concurrent.CompletionStage; +import java.util.concurrent.TimeUnit; + +import static org.junit.Assert.assertFalse; + +@SuppressWarnings("unused") +public class DnsDiscoveryDocTest extends JUnitSuite { + + private static ActorSystem system; + + @BeforeClass + public static void setup() { + system = ActorSystem.create("LeaseDocTest", DnsDiscoveryDocSpec.config()); + } + + @AfterClass + public static void teardown() { + TestKit.shutdownActorSystem(system); + system = null; + } + + @Test + public void dnsDiscoveryShouldResolveAkkaIo() throws Exception { + // #lookup-dns + + ServiceDiscovery discovery = Discovery.get(system).discovery(); + // ... + CompletionStage result = + discovery.lookup("akka.io", Duration.ofMillis(500)); + // #lookup-dns + ServiceDiscovery.Resolved resolved = + result.toCompletableFuture().get(500, TimeUnit.MILLISECONDS); + assertFalse(resolved.getAddresses().isEmpty()); + } +} diff --git a/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala b/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala new file mode 100644 index 0000000000..2a9220550c --- /dev/null +++ b/akka-docs/src/test/scala/docs/discovery/DnsDiscoveryDocSpec.scala @@ -0,0 +1,43 @@ +/* + * Copyright (C) 2020 Lightbend Inc. + */ + +package docs.discovery + +import akka.testkit.AkkaSpec +import com.typesafe.config.ConfigFactory + +import scala.concurrent.duration._ +import scala.concurrent.Future + +object DnsDiscoveryDocSpec { + val config = ConfigFactory.parseString(""" + // #configure-dns + akka { + discovery { + method = akka-dns + } + } + // #configure-dns + """) +} + +class DnsDiscoveryDocSpec extends AkkaSpec(DnsDiscoveryDocSpec.config) { + + "DNS Discovery" should { + "find akka.io" in { + // #lookup-dns + import akka.discovery.Discovery + import akka.discovery.ServiceDiscovery + + val discovery: ServiceDiscovery = Discovery(system).discovery + // ... + val result: Future[ServiceDiscovery.Resolved] = discovery.lookup("akka.io", resolveTimeout = 500.millis) + // #lookup-dns + val resolved = result.futureValue + resolved.serviceName shouldBe "akka.io" + resolved.addresses shouldNot be(Symbol("empty")) + } + } + +} diff --git a/build.sbt b/build.sbt index 638cb65e30..e9b547e2c0 100644 --- a/build.sbt +++ b/build.sbt @@ -202,6 +202,7 @@ lazy val docs = akkaModule("akka-docs") actorTyped, clusterTools % "compile->compile;test->test", clusterSharding % "compile->compile;test->test", + discovery % "compile->compile;test->test", testkit % "compile->compile;test->test", remote % "compile->compile;test->test", persistence % "compile->compile;test->test",