§Using Akka Discovery

As of version 1.5.1, Lagom has built-in integration with Akka Discovery throught a ServiceLocator that wraps Akka Discovery. This ServiceLocator implementation is called AkkaDiscoveryServiceLocator. This is the recommended implementation for production specially for users targeting Kubernetes and DC/OS (Marathon).

§Dependency

To use this feature add the following in your project’s build:

In Maven:

<dependency>
    <groupId>com.lightbend.lagom</groupId>
    <artifactId>lagom-javadsl-akka-discovery-service-locator_${scala.binary.version}</artifactId>
    <version>${lagom.version}</version>
</dependency>

In sbt:

libraryDependencies += lagomJavadslAkkaDiscovery

§Configuration

The Guice module AkkaDiscoveryServiceLocatorModule will be added by default to your project, but will only wire in the AkkaDiscoveryServiceLocator when running in production mode.

In development, your Lagom application will keep using the Lagom’s dev-mode ServiceLocator.

By default, Lagom uses Aggregate multiple discovery methods. The first discovery method is set to Configuration and the second is set to DNS. So the static definition of service endpoints has a priority over DNS discovery.

To statically configure service endpoints in your application.conf file consult the Aggregate multiple discovery methods documentation.

§DNS SRV vs. DNS A/AAAA Lookups

AkkaDiscoveryServiceLocator supports DNS SRV as well as DNS A lookups. It defaults to SRV lookups since it’s the most common usage in environments like Kubernetes and DC/OS (Marathon).

Since Lagom’s ServiceLocator API does not support port-name and protocol fields as used in SRV lookups, AkkaDiscoveryServiceLocator will use default values as fallback. The default port-name is http (as defined by setting lagom.akka.discovery.defaults.port-name) and the default protocol is tcp (as defined by setting lagom.akka.discovery.defaults.port-protocol).

Those values are only used if a lookup is done for a string that does not comply with the SRV format. For instance, when looking for another Lagom service using a Lagom service client. In such a case, the lookup is done using the service name, as defined by its ServiceDescriptor, and the defaults for port-name and protocol.

If both lagom.akka.discovery.defaults.port-name and lagom.akka.discovery.defaults.port-protocol are set to null or a blank string, the lookups are done without those values which correspond to a simple DNS A lookup.

§Confinguring Service Mappings

It’s possible to override those values on a per service base using service-name-mappings.

You may map a service name to a SRV string as in:

lagom.akka.discovery {
  service-name-mappings {
    my-service-name {
      # lookup is done using 'my-service-name'
      # but translated to SRV string _http._tcp.default.svc.cluster.local
      lookup = _http._tcp.default.svc.cluster.local
    }
  }
}

You can also override the port name and protocol to force a DNS A lookup:

lagom.akka.discovery {
  service-name-mappings {
    # lookup is done using 'my-cassandra-server'
    # but translated to cassandra.default.svc.cluster.local
    # and without port name and protocol, ie: DNS A lookup
    my-cassandra-server {
      lookup = cassandra.default.svc.cluster.local
      port-name = null
      port-protocol = null
    }
  }
}

This per service override will allow a DNS A lookup the cassandra server while any other lookups will still use the defaults.

The default settings are in defined in the reference configuration as:

lagom.akka.discovery {

  # When the service lookup regex fails, the defaults are used for the port and protocol.
  defaults {

    # The default port name. Blank if no port name should be added by default.
    port-name = http

    # The default port protocol. Blank if no port protocol should be added by default.
    port-protocol = tcp

    # The default scheme to use in returned URIs if not defined in the port-name-scheme-mappings.
    scheme = http
  }

  # A mapping of service names to lookup information. Each mapping should define the following:
  #
  # - lookup - An alternative name for the service. This can be configured with a simple name or a SRV lookup, for example:
  #   * my-service (simple name)
  #   * my-service.default.svc.cluster.local (simple fully-qualified name)
  #   * _http._tcp.my-service (SRV)
  #   * _http._tcp.my-service.default.svc.cluster.local (fully-qualified SRV)
  # - port-name - The port name to use. If undefined, it will use the default lagom.akka.discovery.defaults.port-name.
  #               Setting to null or empty string will result to a lookup without port-name (eg: DNS A records)
  # - port-protocol - The protocol to use. If undefined, it will use the default lagom.akka.discovery.defaults.port-protocol.
  #               Setting to null or empty string will result to a lookup without protocol (eg: DNS A records)
  # - scheme - The scheme to return in the URI. If undefined, it will use the default scheme lagom.akka.discover.defaults.scheme.
  #
  # For example:
  # service-name-mappings {
  #   my-service-name {
  #     lookup = my-service.default.svc.cluster.local
  #     port-name = http
  #     port-protocol = tcp
  #     scheme = http
  #   }
  # }
  service-name-mappings {
  }


  # The timeout for a successful lookup.
  lookup-timeout = 5 seconds
}

Note: this component was previous published as an independent library. If you have it on your classpath it’s recommended to remove it and use the one being provided by Lagom directly.