The Apache Tomcat Connector - Generic HowTo

LoadBalancer HowTo

print-friendly
version

Introduction

A Load balancer is a virtual worker that does not really communicate with Tomcat workers. Instead it is responsible for the management of several "real" workers. The worker is supposed to be a load balancer if its worker type is lb. See workers type directive. For a complete reference of all load balancer configuration items, please consult the worker reference. The comprehensive status management features of the load balancer together with the status worker, makes its use an interesting option, even if only combined with a single "real" worker.
The workers that are member of load balancer do not need to appear in the worker.list directive.
lb Worker properties
The load-balancing worker does not really communicate with Tomcat workers. Instead it is responsible for the management of several "real" workers. This management includes:

Instantiating the workers in the web server.

Using the worker's load-balancing factor, perform weighed-round-robin load balancing where high lbfactor means stronger machine (that is going to handle more requests)

Keeping requests belonging to the same session executing on the same Tomcat worker.

Identifying failed Tomcat workers, suspending requests to them and instead falling-back on other workers managed by the lb worker.

The overall result is that workers managed by the same lb worker are load-balanced (based on their lbfactor and current user session) and also fall-backed so a single Tomcat process death will not "kill" the entire site.

If you want to use session stickyness, you must set different jvmRoute attributes in the Engine element in Tomcat's server.xml. Furthermore the names of the workers which are managed by the balancer have to be equal to the jvmRoute of the Tomcat instance they connect with.

The following table specifies some properties that the lb worker can accept:

balance_workers is a comma separated list of workers that the load balancer need to manage. These workers do not need to appear in the worker.list property. This directive can be used multiple times for the same load balancer.

sticky_session specifies whether requests with SESSION ID's should be routed back to the same Tomcat worker. You can set sticky_session to False when Tomcat is using a Session Manager which can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.
  # The worker balance1 while use "real" workers worker1 and worker2
  worker.balance1.balance_workers=worker1, worker2
Advanced lb Worker properties
With JK 1.2.x, new load-balancing and fault-tolerant support has been added via 2 new properties, redirect and activation.

Let's take an example environment:

A cluster with two nodes (worker1+worker2), running a webserver + tomcat tandem on each node and a loadbalancer in front of the nodes.
  # The advanced router LB worker
  worker.list=router

  # Define a worker using ajp13
  worker.worker1.port=8009
  worker.worker1.host=node1.domain.org
  worker.worker1.type=ajp13
  worker.worker1.lbfactor=1
  # Define prefered failover node for worker1
  worker.worker1.redirect=worker2

  # Define another worker using ajp13
  worker.worker2.port=8009
  worker.worker2.host=node2.domain.org
  worker.worker2.type=ajp13
  worker.worker2.lbfactor=1
  # Disable worker2 for all requests except failover
  worker.worker2.activation=disabled
  
  # Define the LB worker
  worker.router.type=lb
  worker.router.balance_workers=worker1,worker2
The redirect flag on worker1 tells the lb_worker to redirect the requests to worker2 only if worker1 is in error state. In other cases worker2 will not receive any requests, thus acting like a hot standby.
Status Worker properties
The status worker does not communicate with Tomcat. Instead it is responsible for the load balancer management.
  # Add the status worker to the worker list
  worker.list=jkstatus
  # Define a 'jkstatus' worker using status
  worker.jkstatus.type=status
Next thing is to mount the requests to the jkstatus worker. For Apache web servers use the:
  # Add the jkstatus mount point
  JkMount /jkmanager/* jkstatus 
To obtain a higher level of security use the:
  # Enable the JK manager access from localhost only
 <Location /jkmanager/>
    JkMount jkstatus
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
 </Location>