From 34a97c50033924622139f0851f4e095b27fb96a2 Mon Sep 17 00:00:00 2001 From: Raven Kaur Date: Sun, 29 Mar 2026 21:57:31 -0400 Subject: [PATCH] Updates cluster refresh docs, adds Vault refresh section --- how-to/operations/cluster-upgrades.rst | 104 ++++++++++++++++++------- 1 file changed, 75 insertions(+), 29 deletions(-) diff --git a/how-to/operations/cluster-upgrades.rst b/how-to/operations/cluster-upgrades.rst index 7dd9a6e..62bf5f3 100644 --- a/how-to/operations/cluster-upgrades.rst +++ b/how-to/operations/cluster-upgrades.rst @@ -4,57 +4,67 @@ Cluster upgrades Overview -------- -Use ``sunbeam cluster refresh`` to apply the latest charm updates to a running -deployment without changing the OpenStack release track. The command updates -all managed components to the latest available revision in their currently -configured channel. +A full cluster refresh is a multi-step process. Some components require +dedicated refresh commands and must be refreshed in a specific order before +running the general ``sunbeam cluster refresh`` command. .. note:: - Refreshing across release tracks is not supported. For example, you cannot - use this command to upgrade from ``2024.1/stable`` to ``2025.1/stable``. + use the refresh command to upgrade from ``2024.1/stable`` to ``2025.1/stable``. -.. note:: +Prerequisites +------------- - To ensure the latest charms are applied, refresh the ``openstack`` snap - before running the cluster refresh command. For the **manual provider**, - run ``sudo snap refresh openstack`` on all nodes. For the **MAAS provider**, - run it on the sunbeam client node only. +To ensure the latest updates are available to the cluster charms, refresh the +``openstack`` snap before running any cluster refresh commands. -Refresh the cluster -------------------- +* **Manual provider:** Run ``sudo snap refresh openstack`` on all nodes. +* **MAAS provider:** Run it on the sunbeam client node only. -To refresh the deployment, run: +.. important:: + Refreshing the ``openstack`` snap does not automatically refresh the + cluster. You must explicitly run the dedicated cluster refresh commands + described below to apply updates to the running services. -.. code:: text +.. _refresh-vault: - sunbeam cluster refresh +Step 1 - Refresh Vault +---------------------- -If the snap has been refreshed to a different channel risk (for example, from -``stable`` to ``beta``) since the last update, the command will prompt you to -confirm before proceeding. It is recommended to supply a manifest in that case: +Vault requires a dedicated refresh command. Run: .. code:: text - sunbeam cluster refresh --manifest + sunbeam cluster refresh vault -Use ``--force`` to skip the confirmation prompt: +Following a refresh, the Vault charm is left in a sealed state. +Unless Vault was enabled in dev mode, you must manually unseal it. -.. code:: text +For detailed instructions on unsealing and authorizing Vault, see +:doc:`Vault feature`. - sunbeam cluster refresh --force +.. _refresh-mysql: -Refresh MySQL -------------- +Step 2 - Refresh MySQL +---------------------- -The MySQL database requires a dedicated refresh command to ensure the database -remains available throughout the upgrade. If the upgrade is interrupted, it can -be safely re-run and will resume from where it left off. +The MySQL database must be refreshed before the application charms that depend +on it. Run the following command to refresh the charm to the latest revision +in its channel: .. code:: text sunbeam cluster refresh mysql +During this process, the MySQL cluster is temporarily scaled up to the +nearest odd number of units to maintain quorum while units are upgraded +on a rolling basis. To ensure the upgrade proceeds as intended, it should +be triggered from a healthy MySQL cluster state. If the cluster state is manually +manipulated during the upgrade, the process may not proceed as expected. + +If the upgrade is interrupted, it can usually be re-run and will resume from +where it left off. + If the upgrade has been interrupted and is in an inconsistent state, use the ``--reset-mysql-upgrade-state`` flag to restart it from the beginning: @@ -62,4 +72,40 @@ If the upgrade has been interrupted and is in an inconsistent state, use the sunbeam cluster refresh mysql --reset-mysql-upgrade-state -You will be prompted to confirm before the reset takes effect. +You will be prompted to confirm before resetting the state. This action +resets the internal upgrade tracking and starts a new refresh process. It does +not revert any changes already applied to the cluster. + +.. _refresh-cluster: + +Step 3 - Refresh the cluster +----------------------------- + +Once Vault and MySQL have been refreshed, refresh all remaining OpenStack +charms: + +.. code:: text + + sunbeam cluster refresh + +If the snap has been refreshed to a different risk level in its channel +(for example, from ``stable`` to ``beta``) since the last update, the command +will prompt you to confirm before proceeding. In this case, it is recommended +to supply a manifest file: + +.. code:: text + + sunbeam cluster refresh --manifest + +Use ``--force`` to skip the confirmation prompt: + +.. code:: text + + sunbeam cluster refresh --force + +Use the ``--clear-manifest`` flag to remove a previously +stored manifest: + +.. code:: text + + sunbeam cluster refresh --clear-manifest