Skip to content

About

mod_cluster is an intelligent native Apache httpd-based and pure-Java Undertow-based load-balancer

Topics

Resources

Code of conduct

Security policy

Stars

105 stars

Watchers

14 watching

Forks

Repository files navigation

mod_cluster CI Status Maven Fedora package

Project mod_cluster is an intelligent load balancer. It uses a communication channel to forward requests from a reverse proxy server to one of a set of application server nodes. Unlike mod_jk and mod_proxy, mod_cluster leverages an additional connection between the application server nodes and the reverse proxy to transmit server-side load balance factors and lifecycle events back to the proxy. This additional feedback channel allows mod_cluster to offer a level of intelligence and granularity not found in other load balancing solutions. There are currently two reverse proxy implementations: a native Apache HTTP Server implementation and a pure Java Undertow-based implementation.

Project mod_cluster boasts the following advantages over other httpd-based load balancers:

  • Dynamic configuration of httpd workers
  • Server-side load balance factor calculation
  • Fine-grained web-app lifecycle control
  • AJP is optional

https://www.modcluster.io

Installation Instructions

WildFly 8 and newer

These versions already ship with bundled mod_cluster. It is configured via mod_cluster subsystem.

Tomcat 9.0 and newer

Distribution archives (zip and tar.gz) are provided for each supported Tomcat version. They are published to Maven Central as the org.jboss.mod_cluster:mod_cluster-distribution artifact with a classifier matching the Tomcat version (tomcat-9.0, tomcat-10.1 or tomcat-11.0). Archives for all released versions can be browsed and downloaded from:

https://repo1.maven.org/maven2/org/jboss/mod_cluster/mod_cluster-distribution/

  1. Get the distribution archive corresponding to the intended Tomcat version by either downloading it from Maven Central (see above) or, if building from source, from the dist/target/ directory.

  2. Unzip or untar the distribution archive and navigate to the extracted directory.

  3. Copy the lib/ directory to the Tomcat installation directory adding jars to its lib/ directory. If upgrading from a different version, it is necessary to remove all jars copied previously.

  4. Modify server.xml within the conf directory and add the mod_cluster listener as documented here. The minimal listener configuration is as follows:

    <Listener className="org.jboss.modcluster.container.tomcat.ModClusterListener" connectorPort="8080" advertiseInterfaceName="lo0"/>

Project Structure

The Project is split up into multiple modules:

core (contains the implementation of container-independent core mod_cluster concepts)
container
  spi (SPI classes for container integrations, has no dependencies on a specific web container)
  tomcat-9.0 (Tomcat 9.0 container implementation)
  tomcat-10.1 (Tomcat 10.1 container implementation)
  tomcat-11.0 (Tomcat 11.0 container implementation)
load-spi (SPI classes for load metric computation)

Source Code

Source code for the mod_cluster project is located on GitHub:

https://github.com/modcluster/mod_cluster

Building

Servlet Container Modules

When building from source, first ensure that Maven version 3.2.5 or newer (run mvn -version) and JDK 17 or newer (run java -version) are installed. The following command builds modules for all containers:

mvn clean install

Distribution files for Tomcat will be built in the dist/target/ directory.

Code Coverage Report

This project currently supports JaCoCo to generate a code coverage report bound to verify goal:

mvn clean verify -P coverage

The resulting report can be viewed by opening code-coverage/target/site/jacoco-aggregate/index.html.

Reporting Issues

Project mod_cluster uses Red Hat Jira issue tracker under MODCLUSTER project:

https://issues.redhat.com/browse/MODCLUSTER

License

About

mod_cluster is an intelligent native Apache httpd-based and pure-Java Undertow-based load-balancer

Topics

Resources

Code of conduct

Security policy

Stars

105 stars

Watchers

14 watching

Forks

Releases

Packages

Used by

Contributors

Languages