(tomcat) branch 9.0.x updated: Expand the Javadoc for DNSMembershipProvider

This is an automated email from the ASF dual-hosted git repository.

markt-asf pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/9.0.x by this push:
     new 963711cb64 Expand the Javadoc for DNSMembershipProvider
963711cb64 is described below

commit 963711cb64e720bd38f55e64566cb940f3516fa0
Author: Mark Thomas <[email protected]>
AuthorDate: Wed Jul 8 11:46:27 2026 +0100

    Expand the Javadoc for DNSMembershipProvider
---
 .../membership/cloud/CloudMembershipService.java       |  5 +++--
 .../tribes/membership/cloud/DNSMembershipProvider.java | 18 ++++++++++++++++--
 webapps/docs/changelog.xml                             |  5 +++++
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/java/org/apache/catalina/tribes/membership/cloud/CloudMembershipService.java b/java/org/apache/catalina/tribes/membership/cloud/CloudMembershipService.java
index 1b1d96be92..737503dd50 100644
--- a/java/org/apache/catalina/tribes/membership/cloud/CloudMembershipService.java
+++ b/java/org/apache/catalina/tribes/membership/cloud/CloudMembershipService.java
@@ -33,8 +33,9 @@ import org.apache.juli.logging.LogFactory;
  * A {@link org.apache.catalina.tribes.MembershipService} that uses Kubernetes API(default) or DNS to retrieve the
  * members of a cluster.<br>
  * <p>
- * The default implementation of the MembershipProvider component is the {@link KubernetesMembershipProvider}. The
- * MembershipProvider can be configured by the <code>membershipProviderClassName</code> property. Possible shortcuts are
+ * The default (and recommended) implementation of the MembershipProvider component is the
+ * {@link KubernetesMembershipProvider}. The MembershipProvider can be configured by the
+ * <code>membershipProviderClassName</code> property. Possible shortcuts are
  * {@code kubernetes} and {@code dns}. For dns look at the {@link DNSMembershipProvider}.
  * </p>
  * <p>
diff --git a/java/org/apache/catalina/tribes/membership/cloud/DNSMembershipProvider.java b/java/org/apache/catalina/tribes/membership/cloud/DNSMembershipProvider.java
index c3731aceb0..d9be130e9f 100644
--- a/java/org/apache/catalina/tribes/membership/cloud/DNSMembershipProvider.java
+++ b/java/org/apache/catalina/tribes/membership/cloud/DNSMembershipProvider.java
@@ -32,7 +32,21 @@ import org.apache.juli.logging.Log;
 import org.apache.juli.logging.LogFactory;
 
 /**
- * A {@link org.apache.catalina.tribes.MembershipProvider} that uses DNS to retrieve the members of a cluster.<br>
+ * A {@link org.apache.catalina.tribes.MembershipProvider} that uses DNS to retrieve the members of a cluster.
+ * <p>
+ * Relying solely on DNS to determine cluster membership requires that all DNS caching between the cluster nodes and the
+ * authoritative name server must honour the TTL set by the authoritative name server. Experience has shown that that is
+ * often not the case. Therefore, to ensure that new cluster members are not excluded from the cluster due to a stale
+ * DNS cache, this membership service accepts messages from any node regardless of whether it or not is listed as a
+ * cluster member in DNS and adds that node to the cluster. The DNS entry is, effectively, used by new nodes to identify
+ * the other nodes in the cluster to which cluster messages should be sent.
+ * <p>
+ * If more control is required over cluster membership, users are strongly encouraged to use
+ * {@link KubernetesMembershipProvider} instead. Alternatively, the
+ * {@link org.apache.catalina.tribes.group.interceptors.EncryptInterceptor} may be used to ensure that only nodes with
+ * knowledge of the shared key are able to participate in the cluster.
+ * <p>
+ * TODO: Make the "accept messages from any node and add that node to the cluster" behaviour optional.
  * <p>
  * <strong>Configuration example for Kubernetes</strong>
  * </p>
@@ -202,7 +216,7 @@ public class DNSMembershipProvider extends CloudMembershipProvider {
             byte[] host = sender.getHost();
             int i = 0;
             StringBuilder buf = new StringBuilder();
-            if (host.length > 0 ) {
+            if (host.length > 0) {
                 buf.append(host[i++] & 0xff);
                 for (; i < host.length; i++) {
                     buf.append('.').append(host[i] & 0xff);
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index fe9a8b548a..1a684483b6 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -137,6 +137,11 @@
         algorithms. Also explicitly state that the replay protection is only
         effective for non-malleable algorithms. (markt)
       </add>
+      <add>
+        Expand the Javadoc for the <code>DNSMembershipProvider</code> in
+        particular explaining its behaviour and providing configuration advice
+        if control more over cluster membership is required. (markt)
+      </add>
     </changelog>
   </subsection>
 </section>