docs/manual/src/docbkx/clustering.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<chapter id="clustering"          
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="
               http://docbook.org/ns/docbook
               http://www.docbook.org/xml/5.0/xsd/docbook.xsd"
         version="5.0" xml:lang="en">
   	<title>Clustering and High Availability</title>
   	<para>
   	    ServiceMix supports both High Availability (HA) and clustering of containers.
   	</para>
   	<section id="ha">
   	    <title>High Availability (HA)</title>
   	    <para>
   	        High Availability (HA) can be defined as two distinct ServiceMix container instances configured in a master/slave
   	        configuration. In all cases, the master is <emphasis>active</emphasis> and the slave is in <emphasis>standby</emphasis>
   	        mode waiting for a failover event to trigger it to take over.
   	    </para>
   	    <para>
   	        <itemizedlist>
   	            <listitem><para><emphasis>Active</emphasis>: components are listening for and servicing requests.</para></listitem>
   	            <listitem><para><emphasis>Standby</emphasis>: administrative ports may be open (e.g. JMX) but the process is not listening for or servicing requests.</para></listitem>
   	        </itemizedlist> 
   	    </para>
   	    <para>
   	        As ServiceMix leverages ActiveMQ to provide HA availability, there are a few choices in terms of how to configure 
   	        master/slave via ActiveMQ:
   	        <itemizedlist>
   	            <listitem><para><emphasis>Shared Filesystem Master-Slave</emphasis> - with shared database master/slave
   	                two containers use the same physical data store container state. Care should be taken to ensure
   	                that the file system supports file level locking as this is the mechanism used to select the master.
   	                If the master process exists, the database lock is released and the slave acquires it and it then 
   	                becomes the master.</para></listitem>
   	            <listitem><para><emphasis>JDBC Master-Slave</emphasis> - In JDBC master/slave, the master will lock
   	                a table in the backend database. The failover event in this case is that the lock is released from
   	                the database.</para></listitem>
   	            <listitem><para><emphasis>Pure Master-Slave</emphasis> - With pure master/slave either a shared database
   	                or a shared filesystem can be used. The master replicates all state changes to the slave so there
   	                is additional overhead incurred. The failover trigger in pure master/slave is that the slave loses
   	                its network connection to its master.</para></listitem>
   	        </itemizedlist>
   	        <section>
   	            <title>Configuring HA</title>
   	            <para>
   	                When learning about ServiceMix HA configuration, a good starting point is to configure HA on a single host. In this scenario lets assume we have container1_host1 (master)
   	                and container2_host1 (slave).
   	            </para>
   	            <para>
   	                To configure our example using a shared filesystem master/slave, the steps involved including the following:
   	                <orderedlist>
   	                    <listitem><para>Install two ServiceMix instances (servicemix1 and servicemix2)</para></listitem>
   	                    <listitem><para>Ensure servicemix2 is an exact replica of servicemix1. The exact same files should be installed in servicemix2/hotdeploy directory and servicemix2/conf.</para></listitem>
   	                    <listitem><para>Edit <code>servicemix1/conf/activemq.xml</code> and configure the ActiveMQ persistence adapter:<abbrev>
   	                        <code>
<![CDATA[
  <!-- We use 0.0.0.0 per AMQ-2094 -->
  <amq:transportConnectors>
     <amq:transportConnector uri="tcp://0.0.0.0:61616"/>
  </amq:transportConnectors>

  <amq:persistenceAdapter>
      <amq:amqPersistenceAdapter directory="file:<shared>/data/amq"/>
  </amq:persistenceAdapter>
]]>   	                  
   	                        </code>
   	                    </abbrev></para></listitem>
   	                </orderedlist>
   	            </para>
   	        </section>
   	    </para>
   	    
   	    <section id="clustering">
   	        <title>Clustering</title>
   	        <para>
   	            A cluster can be defined as two or more ACTIVE ServiceMix container instances that are networked together.
   	            A cluster provides the following benefit:
   	            <itemizedlist>
   	                <listitem><para>Connectivity to other ServiceMix containers forming a network of containers.
   	                Containers can be dynamically added and removed from the network.</para></listitem>
   	                <listitem><para>Remote component awareness where each container is aware of its peer container's components.
   	                Networked containers listen for remote component registration/deregistration events and once
   	                aware can route request to those components.</para></listitem>
   	                <listitem><para>Load balancing where a cluster provides the ability to balance requests in a couple of ways including:
   	                    <itemizedlist>
   	                        <listitem><para>Installation of the same component on multiple containers to provide increased capacity and additional HA capabilities.
   	                        If one container fails the same component in another container can still service the request.</para></listitem>
   	                        <listitem><para>Partition workload among container instances whereby different containers can handle different tasks and flows can span multiple containers.</para></listitem>
   	                    </itemizedlist>
   	                </para></listitem>
   	            </itemizedlist>
   	        </para>
   	    </section>
   	</section>
</chapter>