docs review #72

documentation/asciidoc/stories/assembly_connecting_clusters.adoc

@@ -9,6 +9,7 @@ After you configure and deploy {brandname} clusters you can establish remote con
 include::{topics}/proc_connecting_console.adoc[leveloffset=+1]
 include::{topics}/proc_connecting_cli.adoc[leveloffset=+1]
 include::{topics}/proc_connecting_clients_internal.adoc[leveloffset=+1]
+include::{topics}/proc_obtaining_IP_address.adoc[leveloffset=+2]
 include::{topics}/proc_connecting_clients_external.adoc[leveloffset=+1]
 include::{topics}/proc_connecting_rest.adoc[leveloffset=+1]
 

documentation/asciidoc/topics/proc_connecting_clients_internal.adoc

@@ -36,21 +36,6 @@ include::java/ConfigurationBuilderInternal.java[]
 include::properties/hotrod-internal.properties[]
 ----
 
-.Getting IP addresses of all the pods
-The above procedure is the preferred way of connecting to {brandname}: the service guarantees
-the initial connection to one of the available pods.
-Two alternative ways are however possible if an application needs to obtain all the IP addresses
-for a running {brandname}.
-
-. via k8s API.
-+
-Get the `endpoints` k8s resource associated to the `<helm-release-name>` service (`${APISERVER}/api/v1/namespaces/<chart-namespace>/endpoints/<helm-release-name>`). See https://kubernetes.io/docs/tasks/run-application/access-api-from-pod/[k8s API from pod] on how to use API from a pod running in cluster.
-+
-. via k8s DNS service.
-+
-Query the DNS service for the name `<helm-release-name>-ping`. See https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/[DNS for Services and Pods]
-+
-
 [role="_additional-resources"]
 .Additional resources
 * link:{hotrod_docs}[Hot Rod Java Client Guide]

documentation/asciidoc/topics/proc_obtaining_IP_address.adoc

@@ -0,0 +1,24 @@
+[id='obtaining_IP_addresses_{context}']
+= Obtaining IP addresses for all {brandname} pods
+
+[role="_abstract"]
+You can retrieve a list of all IP addresses for running {brandname} pods.
+
+[IMPORTANT]
+====
+link:{helm_docs}#connecting-clients-internal_connecting-clusters[Connecting Hot Rod clients running on {k8s}] is the recommended approach as it ensures the initial connection to one of the available pods.
+====
+
+.Procedure
+Obtain all the IP addresses for a running {brandname} pods in the following ways:
+
+* Using the {k8s} API:
+** Access `${APISERVER}/api/v1/namespaces/<chart-namespace>/endpoints/<helm-release-name>` to retrieve the `endpoints` {k8s} resource associated with the `<helm-release-name>` service.
+
+* Using the {k8s} DNS service:
+** Query the DNS service for the name `<helm-release-name>-ping` to obtain IPs for all the nodes in a cluster.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://kubernetes.io/docs/tasks/run-application/access-api-from-pod/[Accessing the Kubernetes API from a Pod]
+* link:https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/[DNS for Services and Pods]