A look at IBM MQ Uniform Clusters

IBM MQ Uniform Clusters address a common weakness in traditional cluster designs: applications can reconnect after a disruption, but they do not automatically redistribute themselves in a way that keeps consumer capacity aligned with message placement.

In a Uniform Cluster, queue managers are configured to behave as a single logical service. IBM MQ then uses application-level balancing to move client connections toward an even distribution, which is the key difference from traditional cluster message routing.

This article explains the core concepts behind Uniform Clusters and points to a reference lab, a Docker-based demo maintained on GitHub where you can observe the balancing behaviour directly.

1. What this article covers

• Why Uniform Clusters exist and how they differ from traditional clusters
• The architectural conditions they require
• What they do not solve on their own
• Where to run the practical lab

2. Why Uniform Clusters matter

To understand Uniform Clusters, it helps to contrast them with traditional IBM MQ clustering.

2.1 Routing in traditional clusters

In a traditional cluster, workload balancing is primarily about message routing.

If an application connected to QM1 opens a cluster queue such as APP.QUEUE, IBM MQ decides where each put operation should go. If the queue exists on both QM1 and QM2, messages are distributed according to MQ cluster workload rules, often resulting in an even split.

That sounds correct until consumer placement changes.

Consider this sequence:

1. Four consumers are connected to QM1 and four to QM2.
2. QM2 goes down for maintenance.
3. It’s consumers reconnect to QM1.
4. QM2 returns.
5. Producers start sending half the messages back to QM2.

At that point, all consumers may still be attached to QM1, while some of the messages now live on QM2. Those messages become effectively stranded until consumers reconnect there or an administrator intervenes.

2.2 What Uniform Clusters change

Uniform Clusters solve that by re-balancing applications, not just messages.

Instead of assuming that consumers will eventually reconnect to the right place, IBM MQ actively works to distribute reconnect-capable client applications evenly across the cluster members. The balancer tracks which applications are connected to which queue manager and moves them one at a time toward an even distribution.

2.3 What balanced means in practice

IBM MQ's definition of a balanced cluster is not necessarily a strict even split. Do not judge balance by the raw per-QM connection count alone. BALANCED(YES) on the DISPLAY APSTATUS output is the indicator to rely on.

3. Key architectural requirements

Uniform Clusters depend on a few prerequisites:

3.1 Auto-clustering configuration

Two qm.ini stanzas drive the automatic configuration of a Uniform Cluster queue manager: AutoCluster and AutoConfig. Both apply on every queue manager start, and both are used with Uniform Clusters.

AutoCluster defines cluster membership. The Repository1Name and Repository2Name attributes identify two full repositories that act as bootstrap contact points: a starting queue manager contacts them to discover and join the cluster. Either attribute can name the starting queue manager itself. All queue managers in the cluster share the same stanza:

AutoCluster:
   Type=Uniform
   ClusterName=UNICLUS
   Repository1Name=QM1
   Repository1Conname=QM1(1414)
   Repository2Name=QM2
   Repository2Conname=QM2(1414)

When a queue manager starts with this stanza, IBM MQ automatically creates the necessary cluster channels. No manual channel definitions are required.

AutoConfig handles the automatic application of MQSC scripts and supplementary ini settings on every start. It accepts a file path or a directory where all .mqsc or .ini files are applied:

AutoConfig:
   MQSCConfig=/etc/mqm/config.mqsc
   IniConfig=/etc/mqm/config.ini
   ConfigTimeout=120

This is how queues, channels, and other objects are defined consistently across queue managers in the cluster, particularly in containerised deployments where configuration must be reproduced on each start.

The MQSC file referenced by MQSCConfig must contain at minimum a cluster receiver channel definition (CLUSRCVR). This definition describes how other members of the cluster connect to each queue manager and serves as a template for connecting to any member. A single file can work identically on every queue manager by using insert variables that IBM MQ resolves at startup:

A minimal example:

DEFINE CHANNEL('+AUTOCL+_+QMNAME+') CHLTYPE(CLUSRCVR) TRPTYPE(TCP) CONNAME('+CONNAME+') CLUSTER('+AUTOCL+') REPLACE

Because +QMNAME+ is substituted at runtime, the channel name is unique per queue manager even though the file is shared. +AUTOCL+ and +CONNAME+ make the cluster name and connection address equally generic.

ConfigTimeout sets how long (in seconds) the queue manager waits for auto-configuration to complete before accepting application connections. The default is no timeout: the queue manager does not become available until all configuration commands finish. IBM advises against setting a timeout unless necessary, because applications could connect before the objects they depend on exist.

3.2 Creating queue managers

Each queue manager is created with a single crtmqm command that wires up the configuration at creation time. The flags reference the files defined in section 3.1:

Every queue manager in the cluster uses an almost identical command — only the queue manager name and its CONNAME differ:

crtmqm -p 1414 -ii /shared/uniclus.ini -ic /shared/uniclus.mqsc -iv CONNAME=QMA.host(1414) QMA
strmqm QMA

crtmqm -p 1414 -ii /shared/uniclus.ini -ic /shared/uniclus.mqsc -iv CONNAME=QMB.host(1414) QMB
strmqm QMB

When each queue manager starts, IBM MQ performs three steps automatically:

1. The ini file is applied to qm.ini, adding the AutoCluster stanza.
2. IBM MQ checks whether this queue manager is named in the AutoCluster stanza as one of the full repositories. If it is, IBM MQ converts it to a full repository (equivalent to ALTER QMGR REPOS(ClusterName)); otherwise it becomes a partial repository (ALTER QMGR REPOS(' ')).
3. When the CLUSRCVR definition is processed, IBM MQ automatically defines cluster sender channels from this queue manager to each full repository in the AutoCluster stanza (excluding the local queue manager if it is itself a full repository). Sender channels inherit their attributes from the local cluster receiver.

3.3 Client connections are mandatory

Applications must use client connections over TCP/IP. They cannot participate in Uniform Cluster balancing through local bindings because local bindings tie the application to the same process space as the queue manager, which prevents transparent movement to another queue manager.

3.4 Applications must support reconnection

The balancer works by disconnecting an application from its current queue manager and allowing it to reconnect to a different one. For this to be transparent, the application must:

• Be built with reconnect behaviour enabled, for example using MQCNO_RECONNECT
• Have an application name set, for example through MQAPPLNAME
• Keep transactions short enough that the client can safely move at a transaction boundary

If those conditions are not met, the application may still connect and run, but it will behave like a pinned legacy connection and the balancer will not move it.

3.5 Client Channel Definition Table

Client applications connect to the cluster through a Client Channel Definition Table (CCDT). The CCDT lists all the queue managers in the cluster so that the client has fallback options if one queue manager is unavailable. The example below shows a JSON CCDT for a three-node cluster:

{
  "channel": [
    {
      "name": "UNI.SVRCONN",
      "type": "clientConnection",
      "connectionManagement": {
        "defaultReconnect": "yes",
        "affinity": "none"
      },
      "clientConnection": {
        "connection": [
          {"host": "qm1-host", "port": 1414},
          {"host": "qm2-host", "port": 1414},
          {"host": "qm3-host", "port": 1414}
        ],
        "queueManager": "*UNICLUS"
      }
    }
  ]
}

Setting affinity to none ensures the client does not pin itself to the first queue manager it connects to, which is required for the balancer to be able to move it later.

4. Monitoring application balancing

IBM MQ provides the DISPLAY APSTATUS command to observe balancing state across a Uniform Cluster. Full reference documentation is at Monitoring application balancing.

4.1 Cluster-wide view

Run this on any queue manager in the cluster to get an aggregate picture:

DISPLAY APSTATUS('YourAppName') TYPE(APPL) BALANCED CLUSTER COUNT MOVCOUNT

4.2 Queue manager perspective

Run this to see the connection count and movability of instances on a specific queue manager:

DISPLAY APSTATUS('YourAppName') TYPE(LOCAL) CONNS MOVABLE IMMREASN IMMCOUNT

4.3 Why an application is not rebalancing

If BALANCED(NO) persists or MOVCOUNT is lower than expected, check IMMREASN on each queue manager. Common values are:

The most common root causes in new Uniform Cluster deployments are RECONNECT and APPNAME. Both indicate that the application was not built or configured to participate in balancing. See Applications not balancing correctly in the IBM MQ documentation for the full list of reason codes and remediation steps.

5. What Uniform Clusters do not solve alone

Uniform Clusters improve application connectivity and balancing, but they do not remove the storage boundary between queue managers.

Each queue manager still owns its own message data. If QM1 crashes, applications can reconnect elsewhere, but persistent messages that were only on QM1 remain inaccessible until that node returns or a separate high-availability technology protects its storage.

That is why Uniform Clusters are often combined with:

• Multi-Instance Queue Managers: two instances of the same queue manager sharing a network file system, with automatic failover
• Native HA: a three-way replicated queue manager group where one standby takes over automatically

Uniform Clusters improve application balancing across the cluster. They do not, by themselves, make each node's local message store instantly available from other nodes.

6. Running the practical lab

Use the Uniform Clusters demo repository on GitHub:

github.com/ibm-messaging/mq-uniform-clusters

The repository includes several demos, including the one of interest here (demo/Docker), which starts a three-node Uniform Cluster and includes sample client applications to demonstrate balancing.

7. Conclusion

Traditional MQ clusters are strong at message-level routing, but they leave application placement largely outside the scope of the cluster itself. IBM MQ Uniform Clusters close that gap by combining reconnect-capable clients, application identity, and auto-clustered queue managers into a messaging platform that rebalances connections as the cluster expands or recovers from disruption.

That makes Uniform Clusters especially attractive in elastic environments such as Kubernetes, where infrastructure layout changes are expected rather than exceptional.

8. Useful IBM documentation

• IBM MQ Uniform Clusters overview
• How automatic balancing uses automatic reconnect
• Influencing application re-balancing in uniform clusters
• Monitoring application balancing
• MQ clients: Client Channel Definition Table (CCDT)
• JSON CCDT examples
• IBM MQ Uniform Clusters GitHub repository