Clarify the process used by AkkaDiscoveryServiceLocator

[TimMoore]

Some suggestions for https://www.lagomframework.com/documentation/current/java/AkkaDiscoveryIntegration.html from @michael-read:

• Specify the default conventions that you can use in your Kubernetes resource definitions to allow things to "just work" with the default configuration, and how to know when you need to override configuration.
• Describe in more detail how the default port name and protocol are used, and how they relate to the service configuration YAML.
• Clarify how the lookup mappings are used (i.e., they are passed to the underlying Akka Discovery method, so the valid values depend on the configured method).
• It's good to keep the DNS examples for Kubernetes, since that will be the most common use case, but these could be explained more clearly:
  • Omit the leading * so that people don't mistakenly think that's part of the syntax.
  • Describe how to choose between simple and SRV names.
  • Clarify that the port name and service name need to be taken from the Kubernetes Service YAML configuration (and the service name defined there might be different than the one in the service descriptor)
  • Show a template for the names such as _<port-name>._tcp.<service-name> and _<port-name>._tcp.<service-name>.<namespace> to make it more clear that _http is not a magic string, but needs to match configuration.
  • Maybe link directly to https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#services

Michael, let me know if I missed anything.

One more from me:

• Describe how to override the default method if needed (can mostly refer to Akka docs, but good to clarify that there's no significant difference).

Because this behavior will change when #2299 is fixed, it's probably better to do that first, and then update the docs to match.

[michael-read]

Looks good to me! Thanks Tim, I this will be very helpful for our clients going forward.

[octonato]

I added it to Milestone 1.6.0. If we get to fix #2299, we can then consider having it all together.

Assign to the milestone is not a full commit. We can still move it to 1.6.1, if we are short in time. This is just to make sure we don't forget it when going through the milestone open issues.

[octonato]

We have a fix for #2299 in #2603, but I didn't include the improvements for Kubernetes as requested here. I think we should do it on another PR as this will require more time and some extra research.