Configuring simple load balancing is one of the common tasks that many developers must deal with in their careers. However, not much content exists that addresses how to configure load balancing in detail. This tutorial shows you how the collective framework and dynamic routing features can be used together to configure simple load balancing in WebSphere Liberty applications.

WebSphere Liberty offers a powerful feature called collectives. A cluster of application servers can be organized and administered by using the collective feature. A set of Liberty Servers that are logically grouped under a single management domain is called a collective. You can read more about the collective architecture in the WebSphere docs.

Whenever anything changes in a cluster (that is, when member servers or applications are stopped, modified, added, or removed) a plugin-cfg.xml must be regenerated. The dynamic routing feature (Intelligent Management plug-in) helps dynamically collect and update the web server (IBM HTTP Server) with changes in a clustered environment, which ensures that the web server has the up-to-date information that it requires to perform workload management across the cluster. You can find more information about configuring dynamic routing in the WebSphere docs.

In this tutorial, we use an example of a stateless application that is deployed on a WebSphere Liberty Profile (WLP) server and walk you through the various steps to create and configure collectives with dynamic routing (that is, simple load balancing).

The following diagram shows a simple application architecture of a web server (IBM HTTP Server (IHS)) sending HTTP requests to the WebSphere Liberty Profile (WLP) server.

Simple app architecture that shows a web server that sends requests to WLP server

This next diagram shows the same application architecture with collectives and dynamic routing.

App architecture that shows a web server that sends requests with load balancing

This tutorial takes you through the steps to convert the simple application architecture to the one with dynamic routing.

Prerequisites

This tutorial assumes that you have a simple SSL-enabled J2EE application that is deployed on a single WebSphere Liberty Profile (WLP) instance. While we assume that your application is a stateless application, the steps in this tutorial are also applicable for stateful applications since session affinity is enabled by default in the IBM HTTP Server configuration.

You need to have installed IBM HTTP Server and then configured IBM HTTP Server to route all requests to the WebSphere Liberty Profile (WLP) server instance. In this tutorial, we assume that this WLP server instance is named MemberSrvr1.

Also, you must install the Intelligent Management plug-in. You can install the plug-in by running Installation Manager in multiple modes such as Wizard Mode, Silent Mode, or Console Mode. The following steps show how you can install the plug-in by using the Console Mode:

Use the Installation Manager imcl utility to list the repositories:

 /opt/IBM/InstallationManager/eclipse/tools/imcl listAvailablePackages -repositories ../images/java8.0.6.36
 /opt/IBM/InstallationManager/eclipse/tools/imcl listAvailablePackages -repositories ../images/was.repo.9000.plugins

Ensure that the package com.ibm.websphere.PLG.v90_9.0.0.20160526 is listed (look for com.ibm.websphere.PLG in the output since version numbers might vary).

Then, you need to install the packages:

 /opt/IBM/InstallationManager/eclipse/tools/imcl install com.ibm.java.jdk.v8_8.0.6036.201210825_0738 com.ibm.websphere.PLG.v90_9.0.0.20160526 -repositories ../images/java8.0.6.36,../images/9.0.5-WS-IHSPLG-FP009,../images/was.repo.9000.plugins -installationDirectory /opt/IBM/HTTPServer_Plugins -sharedResourcesDirectory /opt/IBM/IMShared -acceptLicense -showProgress

For this tutorial, we have used Liberty ND version 21.0.0.9. You can check the product version by using this command: <wlp_install_dir>/bin/productInfo version. However, the steps that are described in this tutorial for configuring simple load balancing with dynamic routing can also be used with Liberty ND version 21.0.0.4.

The following features must be installed:

collectiveController-1.0
collectiveMember-1.0
clusterMember-1.0
websocket-1.1
restConnector-2.0
ssl-1.0
localConnector-1.0
adminCenter-1.0

You can validate that the features are installed by using this command:<wlp_install_dir>/bin/productInfo validate. If any of these features are not installed, use the following command to install them: <wlp_install_dir>/bin/featureManager install <package_name>.

Finally, make sure that the environment variable WLP_USER_DIR is set. If it’s not set, then set it to <wlp_install_dir>/usr.

Steps

Step 1: Create the collective
Step 2: Add member servers to the collective
Step 3: Configuring dynamic routing with the Intelligent Management Plug-in

Step 1: Create the collective

Create another server instance by using this command:

<wlp_install_dir>/bin/server create MemberSrvr2.

You can then import all the artifacts that are deployed on MemberSrvr1 (which is the WLP server instance that you installed in the prerequisites).
Create the collective controller server, controllerOne, by using this command:

<wlp_install_dir>/bin/server create controllerOne
Create the required certificate by using this command:

<wlp_install_dir>/bin /collective create controllerOne --keystorePassword=admin --createConfigFile=$WLP_USER_DIR/servers/controllerOne/controller.xml

Under the WLP_USER_DIR/servers/controllerOne/ directory, add the following lines to the server.xml file for the controllerOne server:

 <featureManager>
       <feature>adminCenter-1.0</feature>
       <feature>websocket-1.1</feature>
       <feature>restConnector-1.0</feature>
       <feature>localConnector-1.0</feature>
 </featureManager>
   <include location="${server.config.dir}/controller.xml" />

Also, change the default HTTP and HTTPS ports and set them to port numbers of your choice in the server.xml file.

Screen capture that shows the features and ports for the controllerOne server in the server.xml file

Add the following line in the controller.xml file:

<quickStartSecurity userName="admin" userPassword="admin" />
Start the controllerOne server by using this command:

<wlp_install_dir>/bin/server start controllerOne
In the controller server message logs (WLP_USRE_DIR/servers/controllerOne/log/messages.log), look for the following messages in any order:

CWWKX8112I: The server's host information was successfully published to the collective repository.

CWWKX8114I: The server's paths were successfully published to the collective repository.

CWWKX8116I: The server STARTED state was successfully published to the collective repository.

Step 2: Add member servers to the collective

In the /opt/IBM/WebSphere/Liberty/bin/ directory, run the following command:

./collective join MemberSrvr1 –host=<hostname> --port=9331 –user=”admin” –password=”admin” –keystorePassword=admin --createConfigFile=$WLP_USER_DIR/servers/MemberSrvr1/ MemberSrvr1_include.xml

Add the following lines to the server.xml file:

 <featureManager>
   <feature>restConnector-1.0</feature>
     <feature>localConnector-1.0</feature>
 </featureManager>
   <include location="${server.config.dir}/MemberSrvr1.xml" />

Add the following lines to the frameworkServer_include.xml file:

 <feature>clusterMember-1.0</feature>
 <clustermember name="wlpCluster" />
   <remoteFileAccess>
     <writeDir>${server.config.dir}</writeDir>
   </remoteFileAccess>

Restart the MemberSrvr1 server by using these commands:

 /opt/IBM/WebSphere/Liberty/bin/server stop MemberSrvr1
 /opt/IBM/WebSphere/Liberty/bin/server start MemberSrvr1 --clean

Run the updateHost command on the collective utility script to change the authentication information of a registered host.

./collective updateHost <hostname> --host=<hostname> --port=9331 --user="admin" --password="admin" --hostReadPath=$WLP_USER_DIR/servers --hostWritePath=$WLP_USER_DIR/servers --rpcUser=root --rpcUserPassword=<rootpassword>
Add the MemberSrvr2 server to the collective controller as a member. Repeat the previous steps but change the name of the server to MemberSrvr2. In our example, MemberSrvr1 and MemberSrvr2 were on the same host. But if MemberSrvr2 is on a different host, then you must run the ./collective updateHost command with the hostname of the server that is hosting MemberSrvr2.

Restart the MemberSrvr2 server:

 /opt/IBM/WebSphere/Liberty/bin/server stop MemberSrvr2
 /opt/IBM/WebSphere/Liberty/bin/server start MemberSrvr2 --clean

Log in to the Liberty Admin Center and check if you can see Controller MemberSrvr1 and MemberSrvr2: https:// <controller_host>:<controller_port>/adminCenter/.

After you log in to the Liberty Admin Center, you see a toolbox. Click Server Config in the Toolbox.

Select one of the member servers from the list of servers and see if the deployed applications are listed.

Step 3: Configuring Dynamic Routing with the Intelligent Management Plug-in

Add the following feature to the server.xml file for the controllerOne server: <feature>dynamicRouting-1.0</feature>.
Run the dynamicRouting setup command:

./dynamicRouting setup --port=9331 --host=<hostname> --user=admin --password=admin --keystorePassword=admin --pluginInstallRoot=/opt/IBM/HTTPServer_Plugins/ --webServerNames=<webserver_name>
The dynamicRouting setup command creates two files in your <wlp_install_dir>/bin directory. Copy the generated plugin-key.p12 and plugin-cfg.xml files to a temporary directory on the web server host.
On the web server host, run the following command to convert the keystore to CMS format and to set personal certificates as the default. CMS format is the only format that is supported by the Intelligent Management plug-in.
```
 gskcmd -keydb -convert -pw admin -db /tmp/plugin-key.p12 -old_format pkcs12 -target /tmp/plugin-key.kdb -new_format cms -stash
 gskcmd -cert -setdefault -pw admin -db /tmp/plugin-key.kdb -label default
```
Copy the four files that were generated from the previous command to the config directory under the Intelligent Management plug-in installation directory: <Plugin_Installation_Directory>/config/<web_server_name>.
Add the following lines to the httpd.conf file:
```
 LoadModule was_ap24_module /opt/IBM/HTTPServer_Plugins/bin/mod_was_ap24_http.so
 WebSpherePluginConfig /opt/WebSphere/Liberty/bin/plugin-cfg.xml
```
In our example, the IBM HTTP Server and WebSphere Liberty Server instances are on the same host. If IBM HTTP Server (the web server) is installed on a different server, then you might have to merge the plugin-cfg.xml files from each of the Liberty Server profiles by using the pluginCfgMerge tool and copy the merged plugin-cfg.xml file into the plugin_installation_root/config/web_server_name/ directory on the web server host.
Remove any references to the proxypass directive in your httpd.conf file. Otherwise, the IBM HTTP Server Intelligent Management plug-in continues to route all requests to the mapped remote url (endpoint).
If you configured your member servers to use any SSL keystore, comment them out in the appropriate server.xml files. Otherwise, the SSL handshake between the IBM HTTP Server (web server) and the member servers will fail.


Restart IBM HTTP Server.
Now try accessing your application by using a URL like this one: https://<webserverhost>/resource.

Summary

This tutorial describes the steps that you can take to configure simple load balancing for your stateless application by leveraging two powerful features, dynamic routing using the Intelligent Management plug-in and the WebSphere Liberty Collective feature. You now understand how collectives and dynamic routing work together to configure simple load balancing for WebSphere Liberty applications.

Configuring simple load balancing for WebSphere Liberty applications

Configuring simple load balancing for WebSphere Liberty applications