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>

4 files changed, 103 insertions, 29 deletions

diff --git a/ansible/roles/rabbitmq/defaults/main.yml b/ansible/roles/rabbitmq/defaults/main.yml
index 0b502a7c0..f1ed69f38 100644
--- a/ansible/roles/rabbitmq/defaults/main.yml
+++ b/ansible/roles/rabbitmq/defaults/main.yml
@@ -109,3 +109,17 @@ rabbitmq_version_suffix: ""
 ####################
 rabbitmq_enable_tls_backend: "{{ rabbitmq_enable_tls }}"
 rabbitmq_copy_certs: "{{ kolla_copy_ca_into_containers | bool or rabbitmq_enable_tls | bool }}"
+
+####################
+# RabbitMQ upgrade paths
+####################
+# This variable defines explicitly allowed version jumps that go beyond
+# a single minor version increment.
+rabbitmq_allowed_upgrades:
+  "3.13":
+    - "4.0"
+    - "4.1"
+    - "4.2"
+  "4.0":
+    - "4.1"
+    - "4.2"
diff --git a/ansible/roles/rabbitmq/tasks/version-check.yml b/ansible/roles/rabbitmq/tasks/version-check.yml
index 5a5f87555..5b87d2282 100644
--- a/ansible/roles/rabbitmq/tasks/version-check.yml
+++ b/ansible/roles/rabbitmq/tasks/version-check.yml
@@ -46,40 +46,57 @@
           failed_when: false
           check_mode: false
 
-        # As an example, when the new RabbitMQ version is 3.13.6:
-        # new_major_version = 3
-        # new_minor_version = 13
-        # new_version = 3.13
-        # And if the current RabbitMQ version is 3.11.28:
-        # upgrade_version = 3.12
-        - name: Check if running RabbitMQ is at most one version behind
+        - name: Parse RabbitMQ versions
+          ansible.builtin.set_fact:
+            ver_curr_raw: "{{ rabbitmq_version_current.stdout | trim }}"
+            ver_new_raw: "{{ rabbitmq_version_new.stdout | trim }}"
+
+        - name: Calculate Major and Minor components
+          ansible.builtin.set_fact:
+            curr_major: "{{ ver_curr_raw.split('.')[0] }}"
+            curr_minor: "{{ ver_curr_raw.split('.')[1] }}"
+            new_major: "{{ ver_new_raw.split('.')[0] }}"
+            new_minor: "{{ ver_new_raw.split('.')[1] }}"
+
+        - name: Determine Short Versions (X.Y)
+          ansible.builtin.set_fact:
+            ver_curr_short: "{{ curr_major }}.{{ curr_minor }}"
+            ver_new_short: "{{ new_major }}.{{ new_minor }}"
+
+        - name: Check version upgrade validity
           vars:
-            current_version_major: "{{ rabbitmq_version_current.stdout | regex_search('^[0-9]+') }}"
-            current_version_minor: "{{ rabbitmq_version_current.stdout | regex_search('(?<=.)[^.].') }}"
-            current_version: "{{ rabbitmq_version_current.stdout | regex_replace('.[^.]+$', '') }}"
-            new_version_major: "{{ rabbitmq_version_new.stdout | regex_search('^[0-9]+') }}"
-            new_version_minor: "{{ rabbitmq_version_new.stdout | regex_search('(?<=.)[^.].') }}"
-            new_version: "{{ rabbitmq_version_new.stdout | regex_replace('.[^.]+$', '') }}"
-            # Note: 3.13 is the last release before 4.0.
-            upgrade_version: "{{ '4.0 or 4.1' if current_version == '3.13' else current_version_major + '.' + (current_version_minor | int + 1) | string }}"
+            is_standard_upgrade: >-
+              {{ (curr_major == new_major) and (new_minor | int == curr_minor | int + 1) }}
+            is_allowed_path: >-
+              {{
+                 ver_curr_short in rabbitmq_allowed_upgrades and
+                 ver_new_short in rabbitmq_allowed_upgrades[ver_curr_short]
+              }}
+            suggested_next_version: >-
+              {{ curr_major }}.{{ curr_minor | int + 1 }}
+
           ansible.builtin.assert:
-            that: (current_version_major == new_version_major and
-              new_version_minor | int - current_version_minor | int <= 1) or
-              (new_version | float == 4.0 and current_version | float == 3.13) or
-              (new_version | float == 4.1 and current_version | float == 3.13)
+            that:
+              - is_standard_upgrade or is_allowed_path or (ver_curr_short == ver_new_short)
             fail_msg: >
-              Looks like you're trying to run a skip-release upgrade!
-              RabbitMQ must be at most one version behind the target release version ({{ rabbitmq_version_new.stdout | trim }}) to run this upgrade.
-              You are running {{ rabbitmq_version_current.stdout }}.
-              Please first upgrade to {{ upgrade_version }} with the command ``kolla-ansible rabbitmq-upgrade {{ upgrade_version }}``.
-              See these docs for more details: https://docs.openstack.org/kolla-ansible/latest/reference/message-queues/rabbitmq.html#slurp
+              Invalid upgrade path detected!
+
+              You are trying to go from RabbitMQ {{ ver_curr_short }} ({{ ver_curr_raw }}) to {{ ver_new_short }} ({{ ver_new_raw }}).
+
+              Allowed paths logic:
+              1. Standard minor version upgrade (Current + 1). Example: {{ suggested_next_version }}.
+              2. Explicit paths defined in role defaults.
+                 {% if ver_curr_short in rabbitmq_allowed_upgrades %}
+                 Allowed jumps for your version: {{ rabbitmq_allowed_upgrades[ver_curr_short] }}.
+                 {% else %}
+                 No explicit jumps defined for your version.
+                 {% endif %}
+
+              Please upgrade to an intermediate version first.
 
         - name: Catch when RabbitMQ is being downgraded
           ansible.builtin.assert:
-            that: rabbitmq_version_current.stdout is version(rabbitmq_version_new.stdout | trim, 'le', version_type='semver')
+            that: ver_curr_raw is version(ver_new_raw, 'le', version_type='semver')
             fail_msg: >
-              Looks like you're about to downgrade RabbitMQ
-              from version {{ rabbitmq_version_current.stdout }} to version {{ rabbitmq_version_new.stdout | trim }}.
+              Looks like you're about to downgrade RabbitMQ from version {{ ver_curr_raw }} to version {{ ver_new_raw }}.
               If you're absolutely certain you want to do this, please skip the tag `rabbitmq-version-check`.
-              Otherwise, see these docs for how to pin the version of RabbitMQ:
-              https://docs.openstack.org/kolla-ansible/latest/reference/message-queues/rabbitmq.html#rabbitmq-versions
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
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/releasenotes/notes/rabbitmq-42-1c1178a735e3e55c.yaml b/releasenotes/notes/rabbitmq-42-1c1178a735e3e55c.yaml
new file mode 100644
index 000000000..da29ebd42
--- /dev/null
+++ b/releasenotes/notes/rabbitmq-42-1c1178a735e3e55c.yaml
@@ -0,0 +1,12 @@
+---
+features:
+  - |
+    The RabbitMQ upgrade path validation now supports explicitly allowed
+    version jumps (e.g., major or multi-minor upgrades) via the
+    ``rabbitmq_allowed_upgrades`` variable. This allows operators to
+    manage supported RabbitMQ upgrade paths through role defaults or
+    ``globals.yml`` without modifying the core Ansible task files.
+upgrade:
+  - |
+    Adds support for seamless RabbitMQ 4.2 upgrades by defining the
+    required version jump paths in the default configuration.