Improve docs for public-address configuration [CTT-866]

docs/modules/clients/pages/client-overview.adoc

@@ -90,3 +90,5 @@ For help getting started with the Hazelcast clients, see the client tutorials in
 For details about using Memcache to communicate directly with a Hazelcast cluster, see xref:memcache.adoc[Memcache].
 
 For information about using the REST API for simple operations, see: xref:rest.adoc[REST].
+
+For networking information, see xref:clusters:network-configuration.adoc[].

docs/modules/clients/pages/java.adoc

@@ -1917,9 +1917,14 @@ See xref:extending-hazelcast:discovery-spi.adoc[Discovery SPI] for more informat
 |Enables the discovery joiner to use public IPs from `DiscoveredNode`.
 See xref:extending-hazelcast:discovery-spi.adoc[Discovery SPI] for more information.
 When set to `true`, the client assumes that it needs to use public IP addresses reported by the members.
-When set to `false`, the client always uses private addresses reported by the members. If it is `null`,
-the client will try to infer how the discovery mechanism should be based on the reachability of the members.
-This inference is not 100% reliable and may result in false-negatives.
+When set to `false`, the client always uses private addresses reported by the members.
+If not set, the client attempts to infer which address type to use by testing member reachability.
+The inference checks only a small sample of members (3 by default) with fixed timeouts, so it is
+not 100% reliable and may produce incorrect results in environments with variable network latency
+or partial connectivity. Additionally, inference is skipped when SSL/TLS is enabled, defaulting to
+private addresses.
+When members are configured with xref:clusters:network-configuration.adoc#public-address[public addresses],
+ and you want the clients to use public IP addresses, we recommend explicitly setting this property to `true` rather than relying on inference.
 
 |`hazelcast.client.event.queue.capacity`
 |1000000

docs/modules/clusters/pages/network-configuration.adoc

@@ -10,13 +10,22 @@ available configurations that you can perform under the `network` element.
 == Public Address
 
 `public-address` overrides the public address of a member. By default, a member
-selects its socket address as its public address. But behind a network address translation (NAT),
-two endpoints (members) may not be able to see/access each other.
-If both members set their public addresses to their defined addresses on NAT,
-then that way they can communicate with each other. In this case, their public addresses
-are not an address of a local network interface but a virtual address defined by NAT.
-It is optional to set and useful when you have a private cloud.
-Note that, the value for this element should be given in the format *`host IP address:port number`*.
+selects its socket address as its public address.
+
+`public-address`
+can be set to any reachable address or hostname that clients should use to connect to the member.
+Common use cases include:
+
+* **NAT environments**: When members are behind NAT, set the public address to the
+  externally visible address so that other members and clients can reach them.
+* **Private cloud deployments**: When the member's socket address is not directly
+  accessible from outside the private network.
+
+The value can be specified as either:
+
+* An IP address with port: `11.22.33.44:5555`
+* A hostname with port: `member1.example.com:5555`
+
 See the following examples.
 
 [tabs] 
@@ -55,6 +64,63 @@ config.getNetworkConfig()
 ----
 ====
 
+=== How Public Address Affects Hazelcast Features
+
+The `public-address` setting is primarily used for client connections. It does not change
+how members communicate with each other internally. Understanding this distinction is
+important when configuring your cluster:
+
+[cols="1,3"]
+|===
+|Feature |Behavior with Public Address
+
+|**Member-to-member communication**
+|Always uses the primary member address (bind address), not the public address.
+Members within the cluster communicate directly using their internal addresses.
+
+|**Client connections**
+|Clients can use the public address to connect to members. This requires either
+explicitly enabling `hazelcast.discovery.public.ip.enabled` on the client, or
+relying on automatic inference (see <<client-public-address-discovery>>).
+
+|**CP Subsystem**
+|Uses the primary member address for CP member identity. Changing a member's
+address (for example, from IP to hostname) changes its identity in the CP subsystem,
+which can cause instability. See <<cp-address-changes>>.
+
+|**WAN Replication**
+|Uses defined member addresses. Configure target cluster endpoints explicitly
+in WAN replication configuration.
+|===
+
+[[client-public-address-discovery]]
+=== Client Public Address Discovery
+
+For clients to use members' public addresses, configure the
+`hazelcast.discovery.public.ip.enabled` property on the client:
+
+* `true`: The client always uses public addresses reported by members. If the member does not declare
+a public IP, the client will fallback to using the private IPs as reported by the member list.
+* `false`: The client always uses private (internal) addresses reported by members.
+* Not set (default): The client attempts to infer which address type to use based on
+  reachability. See xref:clients:java.adoc#client-system-properties[Client System Properties]
+  for details on inference behavior and its limitations.
+
+NOTE: We recommend explicitly setting `hazelcast.discovery.public.ip.enabled` to `true`
+on clients when members are configured with public addresses, rather than relying on
+automatic inference.
+
+[[cp-address-changes]]
+=== Changing Member Addresses and CP Subsystem
+
+The CP Subsystem identifies members by their primary address. If you change a member's
+address configuration (for example, changing from an IP address to a hostname, or vice versa),
+the CP Subsystem treats this as a different member.
+
+WARNING: Changing the TCP-IP member configuration from an IP address to a hostname
+(or changing the hostname) while the CP Subsystem is in active use can cause CP group instability.
+To recover, you may need to delete the CP persistence directories and restart the
+CP Subsystem, which resets all CP data structures.
 
 [[port]]
 == Port

docs/modules/cp-subsystem/pages/best-practices.adoc

@@ -3,6 +3,10 @@
 
 {description}
 
+* Avoid changing the TCP-IP configuration on CP members, including changing from IP addresses to hostnames. The CP Subsystem identifies members by their primary address and will treat updates as new members.
++
+Changing an address while the CP Subsystem is active can cause CP group instability. To recover, you may need to delete the CP persistence directories and restart the CP Subsystem, which resets all CP data structures.
+
 * Try to reuse already created or existing xref:cp-subsystem:cp-subsystem.adoc#cp-data-structures[CP objects] (AtomicReference, FencedLock, etc.) and try to avoid creating new ones because they will not be garbage collected.
 
 * Because each CP data structure is bounded by a single xref:cp-subsystem:cp-subsystem.adoc#cp-groups[CP group], a client will create a separate session on each CP group that holds the session-based data structure that the client interacts with. When idle, clients send separate heartbeat messages to each CP group to keep the sessions alive. For instance, if five clients try to acquire four locks, where each lock is placed into a different CP group, then there will be 5 x 4 = 20 heartbeat operations committed in total. However, if all locks are put into the same CP group, there will be only five heartbeats in each period. We strongly recommend that you store all session-based CP data structures (locks and semaphores) in a single CP group to avoid that cost.