reference.conf comments

Author: leviramsey

Diff for: discovery-kubernetes-api/src/main/resources/reference.conf

@@ -3,9 +3,29 @@
 ######################################################
 
 akka.discovery {
+  # There are two variants of this discovery mechanism:
+  #
+  # * 'kubernetes-api' is designed for bootstrapping a cluster and does not take readiness
+  #   into account.  It may not be suitable for discovering services outside of the cluster.
+  #
+  # * 'kubernetes-api-for-client' is designed for discovering services outside of the cluster
+  #   and takes readiness into account (thus facilitating client side load-balancing) without
+  #   the need to depend on how a k8s cluster's DNS is configured (e.g. caching).
+  #
+  #   'kubernetes-api-for-client' IS NOT SUITABLE FOR BOOTSTRAPPING A CLUSTER.
+  #
   # Set the following in your application.conf if you want to use this discovery mechanism:
   # method = kubernetes-api
+  #
+  # If deploying a service to Kubernetes and using this discovery mechanism, set in your application.conf:
+  #
+  # akka.management.cluster.bootstrap.contact-point-discovery.discovery-method = kubernetes-api
+  # akka.discovery.method = kubernetes-api-for-client
+  #
+  # This would use the liveness-only variant for bootstrap and the readiness-aware variant for discovering
+  # the pods in other services (e.g. for gRPC).
 
+  # liveness-only
   kubernetes-api {
     class = akka.discovery.kubernetes.KubernetesApiServiceDiscovery
 
@@ -42,8 +62,9 @@ akka.discovery {
     container-name = ""
   }
 
+  # readiness-aware
   # All configuration for this discovery method, apart from the class, is shared with kubernetes-api
-  kubernetes-api-external = {
+  kubernetes-api-for-client = {
     class = akka.discovery.kubernetes.ExternalKubernetesApiServiceDiscovery
   }
 }