Chapter 20. Enabling High Availability in Fuse Fabric

Abstract

When all of your servers and clients are deployed within the same fabric, you can use an alternative mechanism for implementing high availability cluster, which works by exploiting the fabric registry. Because all the parts of the application must be deployed on the same fabric, this mechanism is suitable for deployment on a LAN.

20.1. Load Balancing Cluster

20.1.1. Introduction to Load Balancing

Overview

The fabric load balancing mechanism exploits the fact that fabric provides a distributed fabric registry, which is accessible to all of the container in the fabric. This makes it possible to use the fabric registry as a discovery mechanism for locating WS endpoints in the fabric. By storing all of the endpoint addresses belonging to a particular cluster under the same registry node, any WS clients in the fabric can easily discover the location of the endpoints in the cluster.

Fuse Fabric

A fabric is a distributed collection of containers that share a common database of configuration settings (the fabric registry). Every container in the fabric has a fabric agent deployed in it, which manages the container and redeploys applications to the container whenever a new profile is assigned to the container (a profile is the basic deployment unit in a fabric).

Load-balancing cluster

Figure 20.1, “Fabric Load Balancing for Apache CXF” gives an overview of the fabric load balancing mechanism for Apache CXF endpoints.

Figure 20.1. Fabric Load Balancing for Apache CXF

Fabric Load Balancing for Apache CXF
In this example, two WS servers are created, with the URIs, http://localhost:8185/Foo and http://localhost:8186/Foo. For both of these servers, the load balancer feature is configured to store the cluster endpoints under the path, demo/lb, in the fabric registry.
Now, when the WS client starts, it is configured to look up the cluster path, demo/lb, in the fabric registry. Because the demo/lb path is associated with multiple endpoint addresses, fabric implements a random load balancing algorithm to choose one of the available URIs to connect to.

FabricLoadBalancerFeature

The fabric load balancer feature is implemented by the following class:
io.fabric8.cxf.FabricLoadBalancerFeature
The FabricLoadBalancerFeature class exposes the following bean properties:
fabricPath
This property specifies a node in the fabric registry (specified relative to the base node, /fabric/cxf/endpoints) that is used to store the data for a particular endpoint cluster.
curator
A proxy reference to the OSGi service exposed by the fabric agent (of type, org.apache.curator.framework.CuratorFramework).
maximumConnectionTimeout
The maximum length of time to attempt to connect to the fabric agent, specified in milliseconds. The default is 10000 (10 seconds).
connectionRetryTime
How long to wait between connection attempts, specified in milliseconds. The default is 100.
loadBalanceStrategy
By implementing a bean of type io.fabric8.cxf.LoadBalanceStrategy and setting this property, you can customise the load balancing algorithm used by the load balancing feature.

Prerequisites

To use the fabric load balancer feature in your application, your project must satisfy the following prerequisites:

Maven dependency

The fabric load balancer feature requires the fabric-cxf Maven artifact. Add the following dependency to your project's POM file:
<dependency>
    <groupId>io.fabric8</groupId>
    <artifactId>fabric-cxf</artifactId>
    <version>6.1.0.redhat-379</version>
</dependency>

OSGi package import

If you are packaging your project as an OSGi bundle, you must add io.fabric8.cxf to the list of imported packages. For example, using the Maven bundle plug-in, you can specify this package import by adding io.fabric8.cxf to the comma-separated list in the Import-Package element, as follows:
<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <version>2.2.0</version>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
            <Import-Package>
                ...
 io.fabric8.cxf,
                *
            </Import-Package>
            ...
        </instructions>
    </configuration>
</plugin>

Fabric deployment

When you come to deploy your application into a Red Hat JBoss Fuse container, you must deploy it into a fabric. The fabric load balancer feature is not supported in a standalone container.

Required feature

The fabric load balancer requires the fabric-cxf Apache Karaf feature to be installed in the container. In the context of a fabric, this means you must add the fabric-cxf feature to the relevant deployment profile. For example, if you are using the cxf-lb-server profile to deploy a load-balancing WS server, you can add the fabric-cxf feature by entering the following console command:
JBossFuse:karaf@root> profile-edit -f fabric-cxf cxf-lb-server

20.1.2. Configure the Server

Overview

To configure a WS server to use fabric load balancing, you must configure a fabric load balancer feature and install it in the default Apache CXF bus instance. This section describes how to configure the load balancer feature in Spring XML and in blueprint XML.

Prerequisites

For the basic prerequisites to build a fabric load-balancing WS server, see the section called “Prerequisites”.

Blueprint XML

The following fragment from a blueprint XML file shows how to add the fabric load balancer feature, FabricLoadBalancerFeature, to an Apache CXF bus. Any Apache CXF endpoints subsequently created on this bus will automatically have the load-balancer feature enabled.
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           ...
           xmlns:cxf="http://cxf.apache.org/blueprint/core"
           ...
>
    ...
    <reference id="curator"
               interface="org.apache.curator.framework.CuratorFramework" />

    <!-- The FabricFailOverFeature will try to access other service endpoint with round rad -->
    <bean id="fabricLoadBalancerFeature" class="io.fabric8.cxf.FabricLoadBalancerFeature">
        <property name="curator" ref="curator" />
        <property name="fabricPath" value="cxf/demo" />
    </bean>

    <!-- setup the feature on the bus to help publish the services to the fabric-->
    <cxf:bus bus="cxf">
        <cxf:features>
            <ref component-id="fabricLoadBalancerFeature"/>
        </cxf:features>
    </cxf:bus>
    ...
</blueprint>
The following beans are used to install the fabric load-balancer feature:
curator reference
The curator reference is a proxy of the local fabric agent, which it accesses through the org.apache.curator.framework.CuratorFramework interface. This reference is needed in order to integrate the load balancer feature with the underlying fabric.
FabricLoadBalancerFeature bean
The FabricLoadBalancerFeature bean is initialized with the following properties:
curator
A reference to the Apache Curator client, CuratorFramework.
fabricPath
The path of a node in the fabric registry, where the cluster data is stored (for example, the addresses of the endpoints in the load-balancing cluster). The node path is specified relative to the base node, /fabric/cxf/endpoints.
Apache CXF bus
The cxf:bus element installs the fabric load balancer feature in the default bus instance.

Example using Blueprint XML

Example 20.1, “WS Server with Fabric Load Balancer Feature” shows a complete Blueprint XML example of a WS endpoint configured to use the fabric load balancing feature.

Example 20.1. WS Server with Fabric Load Balancer Feature

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cxf="http://cxf.apache.org/blueprint/core"
           xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
           xsi:schemaLocation="
           http://www.osgi.org/xmlns/blueprint/v1.0.0
           http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
           http://cxf.apache.org/schemas/blueprint/core
           http://cxf.apache.org/schemas/blueprint/core.xsd
           http://cxf.apache.org/blueprint/jaxws
           http://cxf.apache.org/blueprint/jaxws.xsd
           ">

    <reference id="curator" interface="org.apache.curator.framework.CuratorFramework" />

    <!-- The FabricFailOverFeature will try to access other service endpoint with round rad -->
    <bean id="fabicLoadBalancerFeature" class="io.fabric8.cxf.FabricLoadBalancerFeature">
        <property name="curator" ref="curator" />
        <property name="fabricPath" value="cxf/demo" />
    </bean>

    <!-- setup the feature on the bus to help publish the services to the fabric-->
    <cxf:bus bus="cxf">
        <cxf:features>
            <ref component-id="fabicLoadBalancerFeature"/>
        </cxf:features>
    </cxf:bus>

    <bean id="hello1" class="io.fabric8.demo.cxf.server.HelloImpl">
        <property name="hello" value="Hi"/>
    </bean>

    <bean id="hello2" class="io.fabric8.demo.cxf.server.HelloImpl">
        <property name="hello" value="Hello"/>
    </bean>

    <!--
    TODO: We should use address in the form of http://$[bind.address]:$[app1.port]/server/server1, but currently only fuseenterprise
    has appX.port system properties defined
    -->

    <!-- publish the service with the address of fail, cxf client will get the simulated IOException -->
    <jaxws:server id="service1" serviceClass="io.fabric8.demo.cxf.Hello" address="http://localhost:9000/server/server1">
        <jaxws:serviceBean>
             <ref component-id="hello1" />
        </jaxws:serviceBean>
    </jaxws:server>

    <jaxws:server id="service2" serviceClass="io.fabric8.demo.cxf.Hello" address="http://localhost:9000/server/server2">
        <jaxws:serviceBean>
            <ref component-id="hello2" />
        </jaxws:serviceBean>
    </jaxws:server>

</blueprint>
The preceding Spring XML configuration consists of the following main sections:
  • Enabling the fabric load balancing feature—the fabric load balancing feature is installed in the default bus instance, as previously described. In this example, the fabricPath property is set to the value, cxf/demo.
  • Creating the WS endpoints—create the WS endpoints in the usual way, using the jaxws:server element (this can be used as an alternative to the jaxws:endpoint element). By default, this endpoint is automatically associated with the default bus instance, which has load balancing enabled.

20.1.3. Configure the Client

Overview

To configure a WS client to use fabric load balancing, you must install the fabric load balancer feature directly in the client proxy instance. This section describes how to configure the load balancer feature in Blueprint XML, and by programming in Java.

Prerequisites

For the basic prerequisites to build a fabric load-balancing WS client, see the section called “Prerequisites”.

Blueprint XML

The following fragment from a blueprint XML file shows how to add the fabric load balancer feature, FabricLoadBalancerFeature, directly into a WS client proxy instance.
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           ...
           xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"
           xmlns:cxf="http://cxf.apache.org/blueprint/core"
           ...
>
    <!-- Create a client proxy, with load balancing enabled -->
    <jaxws:client id="ClientProxyBeanID"
        address="http://dummyaddress"
        serviceClass="SEI">
        <jaxws:features>
            <ref component-id="fabricLoadBalancerFeature" />
        </jaxws:features>
    </jaxws:client>
    ...
    <reference id="curator"
               interface="org.apache.curator.framework.CuratorFramework" />

    <!-- The FabricFailOverFeature will try to access other service endpoint with round rad -->
    <bean id="fabricLoadBalancerFeature" class="io.fabric8.cxf.FabricLoadBalancerFeature">
        <property name="curator" ref="curator" />
        <property name="fabricPath" value="ZKPath" />
    </bean>
    ...
</blueprint>
The fabric load balancer feature is installed directly into the WS client proxy by inserting it as a child of the jaxws:features element (or, as in this case, by inserting a bean reference to the actual instance). The following beans are used to initialise the fabric load-balancer feature:
curator reference
The curator reference is a proxy of the local fabric agent, which it accesses through the org.apache.curator.framework.CuratorFramework interface. This reference is needed in order to integrate the load balancer feature with the underlying fabric.
FabricLoadBalancerFeature bean
The FabricLoadBalancerFeature bean is initialized with the following properties:
curator
A reference to the Apache Curator client, curator.
fabricPath
The path of a node in the fabric registry, where the cluster data is stored (for example, the addresses of the endpoints in the load-balancing cluster). The node path is specified relative to the base node, /fabric/cxf/endpoints.

Java

As an alternative to using XML configuration, you can enable the fabric load balancing feature on the client side by programming directly in Java. The following example shows how to enable fabric load balancing on a proxy for the Hello Web service.
// Java
package io.fabric8.demo.cxf.client;

import org.apache.cxf.feature.AbstractFeature;
import org.apache.cxf.frontend.ClientProxyFactoryBean;
import org.apache.cxf.jaxws.JaxWsProxyFactoryBean;
import io.fabric8.cxf.FabricLoadBalancerFeature;
import io.fabric8.demo.cxf.Hello;

import java.util.ArrayList;
import java.util.List;

public class Client {
    
    private Hello hello;

    public void initializeHelloProxy() {
        // The feature will try to create a zookeeper client itself
        // by checking the system property of zookeeper.url
        FabricLoadBalancerFeature feature = new FabricLoadBalancerFeature();
        // Feature will use this path to locate the service
        feature.setFabricPath("demo/lb");

        ClientProxyFactoryBean clientFactory = new JaxWsProxyFactoryBean();
        clientFactory.setServiceClass(ClientProxyFactoryBean.class);
        // The address is not the actual address that the client will access
        clientFactory.setAddress("http://dummyaddress");

        List<AbstractFeature> features = new ArrayList<AbstractFeature>();
        features.add(feature);
        // we need to setup the feature on the client factory
        clientFactory.setFeatures(features);

        // Create the proxy of Hello
        hello = clientFactory.create(Hello.class);
    }
    
    public static void main(String args[]) {
        initializeHelloProxy();
        ...
    }
}
In this example, the fabricPath property is set to the value, demo/lb (which matches the example value used by the server in Example 20.1, “WS Server with Fabric Load Balancer Feature”).
The address that the client proxy accesses is set to a dummy value, http://dummyaddress, because this value is not used. When the client is initialized, the load balancer feature substitutes the address value retrieved from the demo/lb node of the fabric registry.