Red Hat AMQ migration CC0

Since Red Hat OpenShift Container Platform was first released, Red Hat Middleware products were provided to deploy on it and help developers to build more complex solutions. Messaging Brokers are a very important piece in most new application architectures, such as microservices, event sourcing, and CQRS. Red Hat JBoss AMQ was provided from the beginning to deploy Messaging Brokers on Red Hat OpenShift easily.

Red Hat AMQ 7 is the latest version of a high-performance, scalable, and multi-protocol broker based on the Apache ActiveMQ Artemis open source project. It is also available as a containerized image for use with Red Hat OpenShift, so it allows developers to quickly deploy messaging brokers in a cloud environment.

There is a Red Hat AMQ 7 migration guide with the most important topics; however, how to do this on Red Hat OpenShift is not completely covered. From my field experience with customers, we defined an automated process to do it on OpenShift including:

  • Zero downtime for consumers and producers
  • Move any persisted message from Red Hat JBoss AMQ 6 to Red Hat AMQ 7
  • Automated using Ansible Playbooks

Migration Process

Red Hat JBoss AMQ 6 (AMQ 6) provides a drainer pod, only available for persistent templates, which is responsible for managing the migration of messages. When AMQ 6 is deployed using a multi-node configuration, it is possible for messages to be left in the KahaDB store directory when the AMQ 6 cluster is scaled down. To prevent messages from remaining, the drainer pod will recover them and move them to other AMQ 6 pod instance. Behind the scenes, a network of brokers is established between the drainer pod and other AMQ 6 pods.

Red Hat AMQ 7 provides the same protocols that previous version. The drainer pod uses OpenWire protocol to move messages, so we will use it to move messages to the new Red Hat AMQ 7 broker.

We need to change the service selectors of each AMQ 6 protocol service (openwire, amqp, stomp, mqtt) to identify the new Red Hat AMQ 7 pod instances. When an AMQ 6 broker is scaled down (replicas = 0), the drainer pod will move the persisted messages.

This feature defines a very straight forward migration process as:

  1. Scale up Red Hat AMQ 7 broker and wait to be ready.
  2. Patch AMQ 6 services to balance connections to Red Hat AMQ 7 broker pods.
  3. Scale down AMQ 6 drainer (it will be started later).
  4. Scale down AMQ 6 broker to avoid new connections. New connections are established to new Red Hat AMQ 7 broker.
  5. Scale up AMQ 6 drainer to drain messages to new Red Hat AMQ 7 broker.
  6. Check AMQ 6 drainer concluded two migration cycles. If after two cycles there are not messages to migrate, we can confirm that drainer finished successfully.
  7. Scale down AMQ 6 drainer.

Ansible Playbook

The migration process described above includes steps and checks, which are very easy to execute manually. However, it could be more difficult if you need to do this for each AMQ 6 broker deployed in Red Hat OpenShift. Ansible playbooks and Ansible roles can help you automate it easily.

I developed a simple Ansible playbook to migrate brokers using command module and OpenShift CLI. Of course, there are other alternatives to implement other approaches, such as, oc module, openshift_raw module, openshift module, etc.

This Ansible playbook sample is available in this GitHub repository.


This article shows how easy it is to migrate Red Hat JBoss AMQ 6 brokers to Red Hat AMQ 7 brokers on Red Hat OpenShift. Do not miss the opportunity to get the best improvements of Red Hat AMQ 7 in your Red Hat OpenShift deployments.

Last updated: June 30, 2023