rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/loadbalancers.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE document [
   3   <!ENTITY project SYSTEM "project.xml">
   4 ]>
   5 <document url="loadbalancers.html">
   6
   7   &project;
   8 <copyright>
   9    Licensed to the Apache Software Foundation (ASF) under one or more
  10    contributor license agreements.  See the NOTICE file distributed with
  11    this work for additional information regarding copyright ownership.
  12    The ASF licenses this file to You under the Apache License, Version 2.0
  13    (the "License"); you may not use this file except in compliance with
  14    the License.  You may obtain a copy of the License at
  15
  16        http://www.apache.org/licenses/LICENSE-2.0
  17
  18    Unless required by applicable law or agreed to in writing, software
  19    distributed under the License is distributed on an "AS IS" BASIS,
  20    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21    See the License for the specific language governing permissions and
  22    limitations under the License.
  23 </copyright>
  24 <properties>
  25 <title>LoadBalancer HowTo</title>
  26 <author email="mturk@apache.org">Mladen Turk</author>
  27 <date>$Date: 2011-03-07 19:04:44 +0100 (Mon, 07 Mar 2011) $</date>
  28 </properties>
  29 <body>
  30 <section name="Introduction">
  31 <br/>
  32 <p>A load balancer is a worker that does not directly communicate with Tomcat.
  33 Instead it is responsible for the management of several "real" workers,
  34 called members or sub workers of the load balancer.</p>
  35 <p>
  36 This management includes:
  37 </p>
  38 <ul>
  39 <li>
  40 Instantiating the workers in the web server.
  41 </li>
  42 <li>
  43 Using the worker's load-balancing factor, perform weighted load balancing
  44 (distributing load according to defined strengths of the targets).
  45 </li>
  46 <li>
  47 Keeping requests belonging to the same session executing on the same Tomcat
  48 (session stickyness).
  49 </li>
  50 <li>
  51 Identifying failed Tomcat workers, suspending requests to them and instead
  52 falling-back on other workers managed by the load balancer.
  53 </li>
  54 <li>
  55 Providing status and load metrics for the load balancer itself and all
  56 members via the status worker interface.
  57 </li>
  58 <li>
  59 Allowing to dynamically reconfigure load-balancing via the status worker
  60 interface.
  61 </li>
  62 </ul>
  63 <p>
  64 Workers managed by the same load balancer worker are load-balanced
  65 (based on their configured balancing factors and current request or session load)
  66 and also secured against failure by providing failover to other members of the same
  67 load balancer. So a single Tomcat process death will not "kill" the entire site.
  68 </p>
  69 <p>Some of the features provided by a load balancer are even interesting, when
  70 only working with a single member worker (where load balancing is not possible).</p>
  71
  72 <subsection name="Basic Load Balancer Properties">
  73 <p>A worker is configured as a load balancer by setting its worker <code>type</code>
  74 to <b>lb</b>.
  75 </p>
  76 <p>
  77 The following table specifies some properties used to configure a load balancer worker:
  78 </p>
  79 <ul>
  80 <li><b>balance_workers</b> is a comma separated list of names of the member workers of the
  81 load balancer. These workers are typically of type <b>ajp13</b>. The member workers do
  82 not need to appear in the <code>worker.list</code> property themselves, adding the
  83 load balancer to it suffices.</li>
  84 <li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed
  85 back to the same Tomcat instance that created the session. You can set sticky_session to
  86 <b>False</b> when Tomcat is using a session manager which can share session data across
  87 multiple instances of Tomcat - or if your application is stateless.
  88 By default sticky_session is set to <b>True</b>.</li>
  89 <li><b>lbfactor</b> can be added to each member worker to configure individual
  90 strengths for the members. A higher <code>lbfactor</code> will lead to more
  91 requests being balanced to that worker. The factors must be given by integers and the
  92 load will be distributed proportional to the factors given. Higher factors lead to
  93 more requests.</li>
  94 </ul>
  95
  96 <source>
  97   # The load balancer worker balance1 will distribute
  98   # load to the members worker1 and worker2
  99   worker.balance1.type=lb
 100   worker.balance1.balance_workers=worker1, worker2
 101   worker.worker1.type=ajp13
 102   worker.worker1.host=myhost1
 103   worker.worker1.port=8009
 104   worker.worker2.type=ajp13
 105   worker.worker1.host=myhost2
 106   worker.worker1.port=8009
 107 </source>
 108
 109 <warn>
 110 Session stickyness is not implemented using a tracking table for sessions.
 111 Instead each Tomcat instance gets an individual name and adds its name at
 112 the end of the session id. When the load balancer sees a session id, it
 113 finds the name of the Tomcat instance and sends the request via the correct
 114 member worker. For this to work you must set the name of the Tomcat instances
 115 as the value of the <code>jvmRoute</code> attribute in the Engine element of
 116 each Tomcat's server.xml. The name of the Tomcat needs to be equal to the name
 117 of the corresponding load balancer member. In the above example, Tomcat on host
 118 "myhost1" needs <code>jvmRoute="worker1"</code>, Tomcat on host "myhost2"
 119 needs <code>jvmRoute="worker2"</code>.
 120 </warn>
 121
 122 <p>For a complete reference of all load balancer configuration
 123 attributes, please consult the worker <a href="../reference/workers.html">reference</a>.
 124 </p>
 125 </subsection>
 126
 127 <subsection name="Advanced Load Balancer Worker Properties">
 128 <p>The load balancer supports complex topologies and failover configurations.
 129 Using the member attribute <code>distance</code> you can group members.
 130 The load balancer will always send a request to a member of lowest distance.
 131 Only when all of those are broken, it will balance to the members of the
 132 next higher configured distance. This allows to define priorities between
 133 Tomcat instances in different data center locations.
 134 </p>
 135 <p>When working with shared sessions, either by using session replication
 136 or a persisting session manager (e.g. via a database), one often splits
 137 up the Tomcat farm into replication groups. In case of failure of a member,
 138 the load balancer needs to know, which other members share the session.
 139 This is configured using the <code>domain</code> attribute. All workers
 140 with the same domain are assumed to share the sessions.</p>
 141 <p>For maintenance purposes you can tell the load balancer to not
 142 allow any new sessions on some members, or even not use them at all.
 143 This is controlled by the member attribute <code>activation</code>.
 144 The value <b>Active</b> allows normal use of a member, <b>disabled</b>
 145 will not create new sessions on it, but still allow sticky requests,
 146 and <b>stopped</b> will no longer send any requests to the member.
 147 Switching the activation from "active" to "disabled" some time before
 148 maintenance will drain the sessions on the worker and minimize disruption.
 149 Depending on the usage pattern of the application, draining will take from
 150 minutes to hours. Switching the worker to stopped immediately before
 151 maintenance will reduce logging of false errors by mod_jk.</p>
 152 <p>Finally you can also configure hot spare workers by using
 153 <code>activation</code> set to <b>disabled</b> in combination with
 154 the attribute <code>redirect</code> added to the other workers:</p>
 155
 156 <source>
 157   # The advanced router LB worker
 158   worker.list=router
 159   worker.router.type=lb
 160   worker.router.balance_workers=worker1,worker2
 161
 162   # Define the first member worker
 163   worker.worker1.type=ajp13
 164   worker.worker1.host=myhost1
 165   worker.worker1.port=8009
 166   # Define preferred failover node for worker1
 167   worker.worker1.redirect=worker2
 168
 169   # Define the second member worker
 170   worker.worker2.type=ajp13
 171   worker.worker2.host=myhost2
 172   worker.worker2.port=8009
 173   # Disable worker2 for all requests except failover
 174   worker.worker2.activation=disabled
 175 </source>
 176
 177 <p>
 178 The <code>redirect</code> flag on worker1 tells the load balancer
 179 to redirect the requests to worker2 in case that worker1 has a problem.
 180 In all other cases worker2 will not receive any requests, thus acting
 181 like a hot standby.
 182 </p>
 183
 184 <p>A final note about setting <code>activation</code> to <b>disabled</b>:
 185 The session id coming with a request is send either
 186 as part of the request URL (<code>;jsessionid=...</code>) or via a cookie.
 187 When using bookmarks or browsers that are running since a long time,
 188 it is possible to send a request carrying an old and invalid session id
 189 pointing at a disabled member.
 190 Since the load balancer does not have a list of valid sessions, it will
 191 forward the request to the disabled member. Thus draining takes longer than
 192 expected. To handle such cases, you can add a Servlet filter to your web
 193 application, which checks the request attribute <code>JK_LB_ACTIVATION</code>.
 194 This attribute contains one of the strings "ACT", "DIS" or "STP". If you
 195 detect "DIS" and the session for the request is no longer active, delete the
 196 session cookie and redirect using a self-referential URL. The redirected
 197 request will then no longer carry session information and thus the load
 198 balancer will not send it to the disabled worker. The request attribute
 199 <code>JK_LB_ACTIVATION</code> has been added in version 1.2.32.</p>
 200 </subsection>
 201
 202 <subsection name="Status Worker properties">
 203 <p>
 204 The status worker does not communicate with Tomcat.
 205 Instead it is responsible for the worker management. It is
 206 especially useful when combined with load balancer workers.
 207 </p>
 208 <source>
 209   # Add the status worker to the worker list
 210   worker.list=jkstatus
 211   # Define a 'jkstatus' worker using status
 212   worker.jkstatus.type=status
 213 </source>
 214 <p>Next thing is to mount the requests to the jkstatus worker. For Apache
 215 web servers use the:</p>
 216 <source>
 217   # Add the jkstatus mount point
 218   JkMount /jkmanager/* jkstatus
 219 </source>
 220 <p>To obtain a higher level of security use the:</p>
 221 <source>
 222   # Enable the JK manager access from localhost only
 223  &lt;Location /jkmanager/&gt;
 224     JkMount jkstatus
 225     Order deny,allow
 226     Deny from all
 227     Allow from 127.0.0.1
 228  &lt;/Location&gt;
 229 </source>
 230
 231 </subsection>
 232
 233 </section>
 234
 235 </body>
 236 </document>