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 049295ecf9 Document Tribes membership services (#1153)
049295ecf9 is described below
commit 049295ecf9ded7ea6b7e9df96368994df9e9c440
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
---
webapps/docs/changelog.xml | 9 ++
webapps/docs/tribes/membership.xml | 233 ++++++++++++++++++++++++++++++++++++-
2 files changed, 241 insertions(+), 1 deletion(-)
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index f376e87500..527a7bb02e 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -234,6 +234,15 @@
</docs>
</changelog>
</subsection>
+ <subsection name="Tribes">
+ <changelog>
+ <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="Other">
<changelog>
<fix>
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]