This is an automated email from the ASF dual-hosted git repository.
markt-asf pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new ed2a0fac8e Document Tribes membership services (#1153)
ed2a0fac8e is described below
commit ed2a0fac8e180f071b38e1ad17b6ecd9317b4c53
Author: sainadh777 <[email protected]>
AuthorDate: Wed Nov 18 03:22:13 2026 -0800
Document Tribes membership services (#1153)
* Document Tribes membership services
* Document combined static and dynamic membership
---
TODO.md | 9 +-
webapps/docs/changelog.xml | 5 +
webapps/docs/tribes/membership.xml | 233 ++++++++++++++++++++++++++++++++++++-
3 files changed, 241 insertions(+), 6 deletions(-)
diff --git a/TODO.md b/TODO.md
index 6f2b19d344..afab29f651 100644
--- a/TODO.md
+++ b/TODO.md
@@ -811,12 +811,11 @@ These are bugs, correctness issues, or missing
functionality that may affect pro
| # | File:Line | Description | Fix Idea | Effort | Difficulty |
|---|-----------|-------------|----------|--------|------------|
| 75.3 | `docs/tribes/setup.xml:33` | Empty TODO placeholder | Write cluster
setup guide: single-point vs multi-point, load balancer config, session
replication. | 3-5 days | Medium |
-| 75.4 | `docs/tribes/membership.xml:33` | Empty TODO placeholder | Document
membership service: multicast, static members, dynamic discovery. | 1-2 days |
Medium |
| 75.5 | `docs/tribes/interceptors.xml:33` | Empty TODO placeholder | Document
all cluster interceptors: fault tolerance, flow control, message dispatch, etc.
| 2-3 days | Medium |
| 75.6 | `docs/tribes/faq.xml:33` | Empty TODO placeholder | Compile common
clustering questions and answers from mailing lists and JIRA. | 2-3 days |
Medium |
| 75.7 | `docs/tribes/developers.xml:33` | Empty TODO placeholder | Developer
guide for extending Tribes: custom channels, interceptors, senders. | 2-3 days
| Medium |
-**Total estimated effort: 10-16 days, Medium difficulty**
+**Total estimated effort: 9-14 days, Medium difficulty**
---
@@ -1036,15 +1035,15 @@ These are IDE-generated stub methods with `// TODO
Auto-generated method stub` c
| High-Priority TODOs | ~25 | ~50-80 | Medium-High |
| Medium-Priority TODOs | ~20 | ~25-40 | Medium |
| Low-Priority / Cosmetic | ~15 | ~25-45 | Low-Medium |
-| Documentation | 10 | ~15-24 | Medium |
+| Documentation | 9 | ~14-22 | Medium |
| Test Code | ~20 | ~15-25 | Low-Medium |
| Auto-Generated Stubs | ~90 | ~5-8 | Low |
-| **Total** | **~195** | **~190-272** | **Mixed** |
+| **Total** | **~194** | **~189-270** | **Mixed** |
### Priority Recommendations
1. **Immediate**: Fix DeltaManager session replication (items 1.1-1.7) - these
affect cluster correctness
2. **Short-term**: Fix DBCP double-close (6.1-6.2), BaseModelMBean
notification removal (7.1), PersistentManagerBase LRU (5.1)
3. **Medium-term**: SSL rewrite variables (2.1-2.8), HTTP/2 HPACK optimization
(23.1-23.3), ThreadPoolExecutor AQS (13.1)
-4. **Long-term**: WebXml i18n support (30.1), CGIServlet overhaul (63.1),
Tribes documentation (75.3-75.7)
+4. **Long-term**: WebXml i18n support (30.1), CGIServlet overhaul (63.1),
Tribes documentation (75.3, 75.5-75.7)
5. **Backlog**: Auto-generated stubs, cosmetic items, test improvements
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 757d815987..2f1fcc50bc 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -456,6 +456,11 @@
<subsection name="Tribes">
<changelog>
<!-- Entries for backport and removal before 12.0.0-M1 below this line
-->
+ <docs>
+ Add documentation for multicast, static and cloud membership in Apache
+ Tribes, including failure detection, security and troubleshooting
+ guidance. (sainadh777)
+ </docs>
</changelog>
</subsection>
<subsection name="jdbc-pool">
diff --git a/webapps/docs/tribes/membership.xml
b/webapps/docs/tribes/membership.xml
index f8305812df..0156bd3253 100644
--- a/webapps/docs/tribes/membership.xml
+++ b/webapps/docs/tribes/membership.xml
@@ -28,9 +28,240 @@
<body>
+<section name="Table of Contents">
+ <toc/>
+</section>
<section name="Membership">
- <p>TODO</p>
+ <p>The membership service maintains the set of remote nodes known to a
+ Tribes channel. It advertises the local receiver's address and ports,
+ discovers or monitors remote members, and reports additions and removals
+ to the channel's <code>MembershipListener</code>s. Applications use this
+ view through methods such as <code>Channel.getMembers()</code> and then
+ choose the members to which a message is sent.</p>
+
+ <p>Membership does not carry application messages. It supplies the
+ destination information used by the
+ <a href="transport.html">message transport</a>. A member record includes
+ the host, TCP port, secure port, UDP port, unique identifier, domain,
+ payload, and the time for which the member has been alive.</p>
+</section>
+
+<section name="Choosing a membership service">
+ <p>Tribes provides three membership services. Select the service that fits
+ the environment in which all of the nodes run.</p>
+
+ <table class="defaultTable">
+ <tr>
+ <th>Service</th>
+ <th>Discovery source</th>
+ <th>Typical use</th>
+ </tr>
+ <tr>
+ <td><code>McastService</code></td>
+ <td>UDP multicast heartbeats</td>
+ <td>Networks where multicast is available and permitted</td>
+ </tr>
+ <tr>
+ <td><code>StaticMembershipService</code></td>
+ <td>Members listed in the configuration</td>
+ <td>Fixed topologies or networks without multicast</td>
+ </tr>
+ <tr>
+ <td><code>CloudMembershipService</code></td>
+ <td>Kubernetes API or DNS</td>
+ <td>Orchestrated environments with changing node addresses</td>
+ </tr>
+ </table>
+
+ <p>The service is configured as the <code>Membership</code> component of a
+ <code>Channel</code>. The local member's message endpoints are taken from
+ the channel receiver, so the receiver must advertise an address that the
+ other nodes can reach. Complete property descriptions are in the
+ <a href="../config/cluster-membership.html">membership configuration
+ reference</a>.</p>
+</section>
+
+<section name="Multicast membership">
+ <p><code>McastService</code> periodically sends a heartbeat to a multicast
+ address and port. Nodes using the same multicast group discover each
+ other without an explicit list. A node is removed when no heartbeat is
+ received for <code>dropTime</code> milliseconds. The default
+ <code>frequency</code> is 500 ms and the default <code>dropTime</code> is
+ 3000 ms.</p>
+
+ <source><![CDATA[<Membership
className="org.apache.catalina.tribes.membership.McastService"
+ address="228.0.0.4"
+ port="45564"
+ frequency="500"
+ dropTime="3000"/>]]></source>
+
+ <p>The multicast address and port identify the group. Use different values
+ to keep unrelated clusters apart. On a host with multiple network
+ interfaces, set <code>bind</code> to the interface used for membership
+ traffic. The <code>ttl</code> controls how far multicast packets may
+ travel; network switches and routers must also be configured to pass the
+ traffic.</p>
+
+ <p>A busy JVM or network can delay heartbeats long enough to cause a false
+ removal. Increase <code>dropTime</code> when necessary, while remembering
+ that it also increases the time needed to detect a real failure. The
+ <a
href="../config/cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes">
+ <code>TcpFailureDetector</code></a> may be added to confirm a suspected
+ failure with a TCP connection before the event is passed up the
channel.</p>
+</section>
+
+<section name="Static membership">
+ <p><code>StaticMembershipService</code> avoids multicast. Each node is given
+ the same list of members and the service exchanges point-to-point ping
+ messages to announce membership and track liveness. This is useful when
+ the topology changes infrequently or multicast cannot cross the network
+ boundary between nodes.</p>
+
+ <source><![CDATA[<Membership
className="org.apache.catalina.tribes.membership.StaticMembershipService">
+ <Member className="org.apache.catalina.tribes.membership.StaticMember"
+ host="tomcat-a.example.net"
+ port="4000"
+ uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
+ <Member className="org.apache.catalina.tribes.membership.StaticMember"
+ host="tomcat-b.example.net"
+ port="4000"
+ uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,0}"/>
+</Membership>]]></source>
+
+ <p>The member host and ports must match the addresses advertised by the
+ corresponding receivers. Every <code>uniqueId</code> must contain 16
+ bytes and must be unique and stable across restarts. The local member is
+ normally identified from the receiver settings; a
+ <code>LocalMember</code> may be configured explicitly when required.</p>
+
+ <p>The default <code>expirationTime</code> is 5000 ms. Pings may be sent by
+ the channel heartbeat or by a dedicated membership thread when
+ <code>useThread</code> is enabled. Static membership requires the
+ <code>Cluster</code> element's <code>channelStartOptions</code> to retain
+ its default value of <code>15</code>, so both membership receive and send
+ processing are started.</p>
+</section>
+
+<section name="Combining dynamic and static membership">
+ <p><code>StaticMembershipInterceptor</code> provides a second way to add
+ static members. Unlike <code>StaticMembershipService</code>, it does not
+ replace the configured membership service. It adds its configured members
+ to the members discovered by <code>McastService</code>,
+ <code>CloudMembershipService</code>, or another membership service. This
+ is useful when most nodes can be discovered dynamically but some nodes
+ must be configured explicitly.</p>
+
+ <source><![CDATA[<Membership
className="org.apache.catalina.tribes.membership.McastService"
+ address="228.0.0.4"
+ port="45564"
+ frequency="500"
+ dropTime="3000"/>
+
+<Interceptor
className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
+<Interceptor
className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor">
+ <Member className="org.apache.catalina.tribes.membership.StaticMember"
+ host="tomcat-remote.example.net"
+ port="4000"
+ uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
+</Interceptor>]]></source>
+
+ <p>Place the <code>StaticMembershipInterceptor</code> after the
+ <code>TcpFailureDetector</code> in the channel configuration so the
+ detector verifies the configured nodes and reports their availability in
+ the same way as dynamically discovered nodes. If dynamic discovery later
+ reports the same host and enabled ports, the dynamically discovered
+ member replaces the configured entry to prevent messages being sent to
+ the node twice. The static entry is restored if that dynamic member
+ disappears. See the
+ <a href="../config/cluster-interceptor.html#Static_Membership">cluster
+ interceptor configuration reference</a> for the complete member
+ attributes and local-member configuration.</p>
+</section>
+
+<section name="Cloud membership">
+ <p><code>CloudMembershipService</code> discovers nodes through a pluggable
+ cloud provider. Its default provider queries the Kubernetes API and can
+ restrict the returned pods with a label selector. The alternative
+ <code>dns</code> provider resolves a DNS service name. The channel
+ heartbeat refreshes the view, and members that are no longer returned are
+ removed after <code>expirationTime</code>.</p>
+
+ <source><![CDATA[<Membership
+
className="org.apache.catalina.tribes.membership.cloud.CloudMembershipService"
+ membershipProviderClassName="kubernetes"/>]]></source>
+
+ <p>The Kubernetes provider reads its API endpoint, namespace, credentials,
+ and optional label selector from the pod environment. The DNS provider
+ uses the service named by <code>DNS_MEMBERSHIP_SERVICE_NAME</code> and is
+ selected with <code>membershipProviderClassName="dns"</code>. See the
+ <doc
path="/api/org/apache/catalina/tribes/membership/cloud/CloudMembershipService.html">
+ cloud membership JavaDoc</doc> for the provider-specific environment
+ variables and examples.</p>
+
+ <p>DNS is used to seed the membership view. To tolerate stale DNS caches,
+ the DNS provider also accepts a message from a previously unknown node
+ and adds that sender to the view. Use TLS for the cluster transport when
+ participation must be limited to nodes that possess the configured
+ credentials.</p>
+</section>
+
+<section name="Member events and failure detection">
+ <p>A membership provider reports a member only after it has enough
+ information to address that node's receiver. A newly discovered member
+ produces a <code>memberAdded()</code> event. An expired or explicitly
+ stopped member produces a <code>memberDisappeared()</code> event. These
+ events update the channel view and are then forwarded to registered
+ membership listeners.</p>
+
+ <p>Discovery and message delivery are separate observations. A member may
+ disappear from the membership view before a send notices a broken
+ connection, or a send may fail before the membership timeout expires.
+ Callers must therefore handle both membership events and
+ <code>ChannelException</code>s from sends.</p>
+
+ <p>The <code>domain</code> value is included in member records and can be
+ used by components such as <code>DomainFilterInterceptor</code> to filter
+ events and messages. It does not create a security boundary; use separate
+ discovery groups and protected transport where isolation is required.</p>
+</section>
+
+<section name="Security">
+ <p>Multicast membership traffic is not authenticated or encrypted and always
+ requires a trusted network. Static configuration removes multicast
+ discovery but does not, by itself, protect the point-to-point cluster
+ traffic. Cloud discovery is also a source of addresses rather than an
+ authorization mechanism.</p>
+
+ <p>Restrict membership and receiver traffic at the network layer. If a
+ trusted network is not available, configure the channel to use TLS with a
+ pre-shared key and configure the secure port for the receiver and every
+ statically configured member. TLS protects the point-to-point cluster
+ traffic, not multicast discovery. See the
+ <a href="../cluster-howto.html#Security">cluster security
+ configuration</a> and the
+ <a href="https://tomcat.apache.org/security-model.html">Tomcat security
+ model</a> before exposing any Tribes endpoint outside a trusted
+ network.</p>
+</section>
+
+<section name="Operations and troubleshooting">
+ <ul>
+ <li>Verify that every receiver advertises an address and port reachable by
+ all other members. NAT and container addresses frequently require
+ explicit receiver configuration.</li>
+ <li>For multicast, verify routing, interface binding, group address, port,
+ and TTL from every node. A node that can send but not receive
+ multicast will have an inconsistent membership view.</li>
+ <li>For static membership, keep the member list, ports, and identifiers
+ consistent on every node.</li>
+ <li>For cloud membership, verify that the API or DNS response contains the
+ intended running nodes and that the configured refresh and expiration
+ times match the environment.</li>
+ <li>Inspect the <code>component=Membership</code> MBean to compare the
+ member view on each node. The <a href="status.html">Tribes status
+ guide</a> describes the available JMX information.</li>
+ </ul>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]