kolla-ansible: Add RabbitMQ 4.2 support and dynamic upgrade paths

The RabbitMQ version check currently hardcodes allowed version jumps.
This makes supporting new major/minor releases (like 4.2) rigid and
requires modifying the core task file.

This commit introduces the `rabbitmq_allowed_upgrades` variable in
the role's defaults. This allows operators to define explicit version
jumps (e.g., 3.13 to 4.2) and makes the upgrade logic more flexible.

The version validation logic now:
1. Checks for standard minor increments (e.g., 4.1 -> 4.2).
2. Checks for explicitly defined jumps in `rabbitmq_allowed_upgrades`.

By moving these definitions to defaults, operators can easily override
them in globals.yml if necessary.

Depends-On: https://review.opendev.org/c/openstack/kolla/+/966017

Change-Id: I0e19cf109eb5665045806b7d925779e82164c2dc
Signed-off-by: Piotr Milewski <vurmil@gmail.com>

1 files changed, 31 insertions, 0 deletions

diff --git a/doc/source/reference/message-queues/rabbitmq.rst b/doc/source/reference/message-queues/rabbitmq.rst
index 3bd364564..1eed7ef14 100644
--- a/doc/source/reference/message-queues/rabbitmq.rst
+++ b/doc/source/reference/message-queues/rabbitmq.rst
@@ -160,6 +160,37 @@ different type, the follow procedure will be needed.
 
       kolla-ansible deploy --tags <service-tags>
 
+
+Upgrading RabbitMQ
+~~~~~~~~~~~~~~~~~~
+
+RabbitMQ upgrades in Kolla Ansible are typically restricted to a single minor
+version increment at a time (e.g., from 4.0.x to 4.1.x). This is a safety
+measure to ensure that RabbitMQ's internal data migrations and feature flags
+are processed correctly.
+
+In some cases, specific multi-version upgrade paths are supported (for example,
+jumping from 3.13 directly to 4.2). These allowed paths are defined
+using the ``rabbitmq_allowed_upgrades`` variable in the RabbitMQ role defaults.
+
+Operators can customize or extend these allowed upgrade paths by overriding
+this variable in ``globals.yml``.
+
+.. code-block:: yaml
+
+   rabbitmq_allowed_upgrades:
+     "3.13":
+       - "4.0"
+       - "4.1"
+       - "4.2"
+     "4.0":
+       - "4.1"
+       - "4.2"
+
+If an invalid upgrade path is detected, the deployment will fail with a
+descriptive error message during the ``rabbitmq-version-check`` task,
+suggesting the next appropriate intermediate version.
+
 Handling Stream Replicas
 ~~~~~~~~~~~~~~~~~~~~~~~~