Setting up a uniform cluster in IBM MQ

Now that you’ve seen what a uniform cluster is and understand the role of the CCDT in facilitating application rebalancing, it’s time to get hands-on with your own uniform cluster.

This tutorial is part of the "Uniform clustering in IBM MQ" series.

In this tutorial, you will learn:

How to set up a uniform cluster
How sample producing and consuming applications are rebalanced
How to deploy a JMS application to connect to the uniform cluster and how that application is rebalanced in the uniform cluster.

The following video goes through this tutorial if you want to jump straight in!

Video will open in new tab or window

Prerequisites

You must have the following software installed on your machine:

Git
Java
Maven
JSON parser
The latest version of the IBM MQ allclient

Estimated Time

This tutorial should take around 30 minutes.

Steps

In this tutorial, we will be using these repositories:

Step 1. Setting up a uniform cluster

To set up a uniform cluster, follow the instructions for the demo that is provided in this repo. Navigate to the demo directory and choose the demo that’s best for your environment (either Linux, Docker, or Docker for M1 Macs). After following the instructions in the README for your chosen demo, you will have set up a uniform cluster that consists of three queue managers and supports twelve producing and consuming application instances.

You start the consuming and producing applications and watch for connections. Initially, the number of producers and consumers that are connected to each queue manager will likely be uneven, due to randomization of connections, but connections are soon rebalanced until there is an equal number of each type of application connected to each queue manager.

Now that you’ve seen how applications are rebalanced across a uniform cluster to ensure efficient resource use, let’s have a look at how to connect an application of your own.

Step 2. Getting a JMS application

In this tutorial, we’ll use JmsGet.jms as our example application to connect to the uniform cluster, which is found in the mq-dev-patterns repository. This application is a simple consumer application and will "get" messages from a queue.

First, clone the repo using this command:

git clone https://github.com/ibm-messaging/mq-dev-patterns

Then, navigate to the JMS directory in this repo, and follow the steps in the README to build the sample applications. NOTE: if you already have this repo cloned, ensure your version is up to date.

Step 3. Configuring the application to be able to connect to the uniform cluster

For the application to be able to connect to the uniform cluster, you must make these changes:

Specify that the application should connect to any queue manager in the uniform cluster.
Make the application reconnectable so that it can be rebalanced across the queue managers.
Make the CCDT file for the uniform cluster available for the JMS application to access.

Let’s go through the steps to do this.

Configure the application to connect to any queue manager in the uniform cluster

Navigate to the env.json file in the mq-dev-patterns directory. Replace what is there with the following:

{
  "MQ_ENDPOINTS": [{
    "QMGR": "*ANY_QM",
    "QUEUE_NAME": "DEV.QUEUE.1",
    "APP_NAME": "amqsghac"
  }]
}

These changes enable the application to be connected to any queue manager in the uniform cluster. Let’s look at what these changes actually do.

The value of the QMGR attribute, *ANY_QM, relates to the queue manager name in the connection list set in the CCDT.json file in the demo repo. (You can read more about the CCDT and connection lists in this article.)
The queue specified in QUEUE_NAME is where our application will be consuming messages from. A property of uniform clusters is that all queue managers have near identical configuration, so all queue managers should have a DEV.QUEUE.1.
Application names are used by the uniform cluster to group applications, and apps with the same name are assumed to have similar properties, making accurate naming essential. The application name specified here is amqsghac, set for the purposes of this demo so that it can be conveniently displayed as a consumer by the connections.sh script.

Make the application reconnectable

Open the com/ibm/mq/samples/JmsGet.java file, and then uncomment this line:

cf.setIntProperty(WMQConstants.WMQ_CLIENT_RECONNECT_OPTIONS, WMQConstants.WMQ_CLIENT_RECONNECT);

This line specifies that the application should attempt to reconnect to a queue manager if it loses connection.

Make the CCDT file accessible to the JMS app

To make the CCDT file available for the application to access, we need to set the environment variable MQCCDTURL to contain the name and location of the CCDT. You set this environment variable when you run the application (after compiling it), which you will do in the next step.

Step 4. Running instances of the consuming application in the uniform cluster

In your uniform cluster, run the ./killDemoApps.sh script to stop the demo apps. You should see the values for producers and consumers in your 3 connection.sh QMx tabs go down to 0.

Now, run only the producers (and not the consumers so we can clearly see where our JMS application connects) by only running the producers.sh script. This will put messages onto the queues for our JMS consumer applications to get. Now, we need to add the JmsGet.java application to the uniform cluster. To do this, simply run the application by using one of the following commands:

If you used maven to build the JMS samples, run this command:

  java -DMQCCDTURL=file:///<location_of_your_CCDT_file>  -cp target/mq-dev-patterns-0.1.0.jar: com.ibm.mq.samples.jms.JmsGet

Otherwise, compile:

  javac -cp ./com.ibm.mq.allclient-9.2.5.0.jar:./javax.jms-api-2.0.1.jar:./json-20230227.jar:. com/ibm/mq/samples/jms/JmsGet.java

And run:

  java -DMQCCDTURL=file:///<location_of_your_CCDT_file> -cp ./com.ibm.mq.allclient-9.2.5.0.jar:./javax.jms-api-2.0.1.jar:./json-20230227.jar:. com.ibm.mq.samples.jms.JmsGet

You should see one consumer being added to one of the queue managers.

Now that you’ve successfully added one instance of this application to the uniform cluster, let’s add a few more so we can see them being rebalanced.

For convenience, the multi-jms-sample-driver.sh script (which only works for Linux and Mac users) will run 6 instances of this application in our uniform cluster. Navigate to the JMS/scripts directory and run:

./multi-jms-sample-driver.sh

You should now see the consumer count increasing for each queue manager, until there are at least 2 consumers on each queue manager. These are the default settings of the script, but you can change them by running:

./multi-jms-sample-driver.sh <jms_application_name> <number_of_instances>

If you had connected too many consuming applications to the uniform cluster, you would have noticed some of the applications disconnecting since there wouldn't be enough messages being put to the queues, causing consumer starvation and timeout of their ‘get’ operation. If you encounter other errors in using the multi-jms-sample-driver.sh script, check out the IBM MQ uniform clusters cheat sheet.

Essential Criteria

Now that you have seen how to set up a uniform cluster and how to connect an application to that cluster, you have seen some of the features an application needs to have to connect to a uniform cluster. In order for your application to be eligible for rebalancing, it must fulfill the criteria summarized in the following table.

Criteria	Description
The client must use a CCDT to get connection information	The CCDT provides the application with the connection information of all queue managers in a uniform cluster. By using the CCDT, the host and port information can be provided to applications dynamically when they are requested to reconnect.
The application must use a client mode connection	Using a client mode connection allows your application to connect to a queue manager using the host and port information over TCP/IP, and it should get this information from the CCDT. By using a client mode connection, the application doesn’t need to be on the same system as the queue manager it's connected to, so is free to be reconnected to any queue manager in the uniform cluster.
The client application must be set to reconnectable	You need to set the `WMQ_CLIENT_RECONNECT_OPTIONS` property to `WMQ_CLIENT_RECONNECT` to allow the application to be reconnected to any queue manager in the CCDT. NOTE: If you set `WMQ_CLIENT_RECONNECT_OPTIONS` to `WMQ_CLIENT_RECONNECT_Q_MGR` instead, your application won’t be eligible for rebalancing. Beware of this distinction.
The IBM MQ allclient version must be 9.2.0 or later	Version 9.2.0 is the earliest release that provides uniform clustering functionality.
The application should not share sockets with other applications	If your application is sharing a socket with another application, there will be multiple connections on the same TCP connection. Though these connections will have different application names, the uniform cluster won’t be able to separate them reliably so it will prevent rebalancing them. For more sophisticated use cases, you'll need to optimise your `SHARECNV` value.

Your application must meet all of the criteria described in the previous table to ensure it can be rebalanced over a uniform cluster effectively. Despite meeting these criteria, it is possible that you still have some non-reconnectable applications. If your app instances are addressing too many messaging scenarios, intervention from the uniform cluster administrator might be necessary. This document explains several reasons why your application might be unavailable for rebalancing and the actions you can take in response.

Summary and next steps

By completing this tutorial, you set up a uniform cluster, observed producing and consuming applications being rebalanced across it, and made the changes required to enable a JMS application to connect to that uniform cluster.

Next, take a closer look at application rebalancing scenarios in the final article in our uniform clustering in IBM MQ" series.