From 249c1e89de0bef6a00f3abecdd8dfc820a5719fb Mon Sep 17 00:00:00 2001
From: Matt Crees <mattc@stackhpc.com>
Date: Thu, 9 May 2024 17:18:41 +0100
Subject: [PATCH] Add command to upgrade to a target version of RMQ

Required before a SLURP upgrade

Change-Id: I09a45d26a6075554b204e007f64122f23de5f53c
---
 ansible/rabbitmq-upgrade.yml                  | 21 +++++++++
 ansible/roles/rabbitmq/defaults/main.yml      |  2 +
 .../reference/message-queues/rabbitmq.rst     | 44 +++++++++++++++++++
 ...rget-upgrade-command-d5f9d9fc27fa28f8.yaml |  6 +++
 tools/kolla-ansible                           |  8 ++++
 5 files changed, 81 insertions(+)
 create mode 100644 ansible/rabbitmq-upgrade.yml
 create mode 100644 releasenotes/notes/rabbitmq-target-upgrade-command-d5f9d9fc27fa28f8.yaml

diff --git a/ansible/rabbitmq-upgrade.yml b/ansible/rabbitmq-upgrade.yml
new file mode 100644
index 0000000000..3677676500
--- /dev/null
+++ b/ansible/rabbitmq-upgrade.yml
@@ -0,0 +1,21 @@
+---
+- import_playbook: gather-facts.yml
+
+- name: Group hosts based on configuration (RabbitMQ Only)
+  hosts: all
+  gather_facts: false
+  max_fail_percentage: >-
+    {{ group_hosts_max_fail_percentage |
+       default(kolla_max_fail_percentage) |
+       default(100) }}
+  tasks:
+    - name: Group hosts based on enabled services (RabbitMQ Only)
+      group_by:
+        key: "enable_rabbitmq_{{ enable_rabbitmq | bool }}"
+      changed_when: false
+  tags: always
+
+- import_playbook: rabbitmq.yml
+  vars:
+    kolla_action: upgrade
+    rabbitmq_image: "{{ docker_registry ~ '/' if docker_registry else '' }}{{ docker_namespace }}/rabbitmq-{{ rabbitmq_version_suffix | regex_replace('\\.', '-') }}"
diff --git a/ansible/roles/rabbitmq/defaults/main.yml b/ansible/roles/rabbitmq/defaults/main.yml
index 384f92becd..6ccd7ba5b9 100644
--- a/ansible/roles/rabbitmq/defaults/main.yml
+++ b/ansible/roles/rabbitmq/defaults/main.yml
@@ -98,3 +98,5 @@ rabbitmq_plugins:
 rabbitmq_enabled_plugins: "{{ rabbitmq_plugins | selectattr('enabled', 'equalto', true) | list }}"
 
 kolla_externally_managed_cert: False
+
+rabbitmq_version_suffix: ""
diff --git a/doc/source/reference/message-queues/rabbitmq.rst b/doc/source/reference/message-queues/rabbitmq.rst
index 42980affa1..ac56539526 100644
--- a/doc/source/reference/message-queues/rabbitmq.rst
+++ b/doc/source/reference/message-queues/rabbitmq.rst
@@ -163,3 +163,47 @@ additional steps needed to migrate from transient to durable queues.
    .. code-block:: console
 
       kolla-ansible deploy --tags <service-tags>
+
+SLURP
+~~~~~
+
+RabbitMQ has two major version releases per year but does not support jumping
+two versions in one upgrade. So if you want to perform a skip-level upgrade,
+you must first upgrade RabbitMQ to an intermediary version. To do this, Kolla
+provides multiple RabbitMQ versions in the odd OpenStack releases. To use the
+upgrade from Antelope to Caracal as an example, we start on RabbitMQ version
+3.11. In Antelope, you should upgrade to RabbitMQ version 3.12 with the command
+below. You can then proceed with the usual SLURP upgrade to Caracal (and
+therefore RabbitMQ version 3.13).
+
+.. warning::
+
+   This command should be run from the Antelope release.
+
+.. code-block:: console
+
+   kolla-ansible rabbitmq-upgrade 3.12
+
+RabbitMQ versions
+~~~~~~~~~~~~~~~~~
+
+Alternatively, you can set ``rabbitmq_image`` in your configuration
+``globals.yml`` for idempotence in deployments. As an example, Kolla ships
+versions 3.11, 3.12 and 3.13 of RabbitMQ in Antelope. By default, Antelope
+Kolla-Ansible will deploy version 3.11. If you wish to deploy a later version,
+you must override the image. if you want to use version 3.12 change
+``rabbitmq_image`` in ``globals.yml`` as follows:
+
+.. code-block:: yaml
+
+   rabbitmq_image: "{{ docker_registry ~ '/' if docker_registry else '' }}{{ docker_namespace }}/rabbitmq-3.12"
+
+You can then upgrade RabbitMQ with the usual command:
+
+.. code-block:: console
+
+   kolla-ansible upgrade --tags rabbitmq
+
+Note again that RabbitMQ does not support upgrades between more than one major
+version, so if you wish to upgrade to version 3.13 you must first upgrade to
+3.12.
diff --git a/releasenotes/notes/rabbitmq-target-upgrade-command-d5f9d9fc27fa28f8.yaml b/releasenotes/notes/rabbitmq-target-upgrade-command-d5f9d9fc27fa28f8.yaml
new file mode 100644
index 0000000000..4ba4ab951f
--- /dev/null
+++ b/releasenotes/notes/rabbitmq-target-upgrade-command-d5f9d9fc27fa28f8.yaml
@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Added a command to upgrade to a target version of RabbitMQ. This is
+    required before a SLURP upgrade. See the docs for more details:
+    https://docs.openstack.org/kolla-ansible/latest/reference/message-queues/rabbitmq.html#slurp
diff --git a/tools/kolla-ansible b/tools/kolla-ansible
index f2daa7f4eb..7a5eef31fa 100755
--- a/tools/kolla-ansible
+++ b/tools/kolla-ansible
@@ -199,6 +199,7 @@ Commands:
     post-deploy          Do post deploy on deploy node
     pull                 Pull all images for containers (only pulls, no running container changes)
     rabbitmq-reset-state Force reset the state of RabbitMQ
+    rabbitmq-upgrade <version> Upgrade to a specific version of RabbitMQ
     reconfigure          Reconfigure OpenStack service
     stop                 Stop Kolla containers
     certificates         Generate self-signed certificate for TLS *For Development Only*
@@ -247,6 +248,7 @@ gather-facts
 post-deploy
 pull
 rabbitmq-reset-state
+rabbitmq-upgrade
 reconfigure
 stop
 certificates
@@ -572,6 +574,12 @@ EOF
         ACTION="Force reset the state of RabbitMQ"
         PLAYBOOK="${BASEDIR}/ansible/rabbitmq-reset-state.yml"
         ;;
+(rabbitmq-upgrade)
+        RMQ_VERSION="$2"
+        ACTION="Upgrade to a specific version of RabbitMQ"
+        PLAYBOOK="${BASEDIR}/ansible/rabbitmq-upgrade.yml"
+        EXTRA_OPTS="$EXTRA_OPTS -e rabbitmq_version_suffix=${RMQ_VERSION}"
+        ;;
 (bash-completion)
         bash_completion
         exit 0