Merge pull request #760 from stackhpc/yoga-rl9-in-place-docs

yoga rl9 in place docs

Author: markgoddard

doc/source/operations/rocky-linux-9.rst

@@ -602,7 +602,125 @@ Wazuh manager
 
 TODO
 
-In-place migrations
-===================
+In-place upgrades
+=================
 
-TODO
+Sometimes it is necessary to upgrade a system in-place.
+This may be the case for the seed hypervisor or Ansible control host which are often installed manually onto bare metal.
+This procedure is not officially recommended, and can be risky, so be sure to back up all critical data and ensure serial console access is available (including password login) in case of getting locked out.
+
+The procedure is performed in two stages:
+
+1. Migrate from CentOS Stream 8 to Rocky Linux 8
+2. Upgrade from Rocky Linux 8 to Rocky Linux 9
+
+Potential issues
+----------------
+
+Full procedure
+--------------
+
+- Inspect existing DNF packages and determine whether they are really required.
+
+- Use the `migrate2rocky.sh
+  <https://raw.githubusercontent.com/rocky-linux/rocky-tools/main/migrate2rocky/migrate2rocky.sh>`__
+  script to migrate to Rocky Linux 8.
+
+- Disable all DNF modules - they're no longer used.
+
+  .. code-block:: console
+
+     sudo dnf module disable "*"
+
+- Migrate to NetworkManager. This can be done using a manual process or with Kayobe.
+
+  The manual process is as follows:
+
+  - Ensure that all network interfaces are managed by Network Manager:
+
+    .. code:: console
+
+       sudo sed -i -e 's/NM_CONTROLLED=no/NM_CONTROLLED=yes/g' /etc/sysconfig/network-scripts/*
+
+  - Enable and start NetworkManager:
+
+    .. code:: console
+
+       sudo systemctl enable NetworkManager
+       sudo systemctl start NetworkManager
+
+  - Migrate Ethernet connections to native NetworkManager configuration:
+
+    .. code:: console
+
+       sudo nmcli connection migrate
+
+  - Manually migrate non-Ethernet (bonds, bridges & VLAN subinterfaces) network interfaces to native NetworkManager.
+
+  - Look out for lost DNS configuration after migration to NetworkManager. This may be manually restored using something like this:
+
+    .. code:: console
+
+       nmcli con mod System\ brextmgmt.3003 ipv4.dns "10.41.4.4 10.41.4.5 10.41.4.6"
+
+  The following Kayobe process for migrating to NetworkManager has not yet been tested.
+
+  - Set ``interfaces_use_nmconnection: true`` as a host/group variable for the relevant hosts
+
+  - Run the appropriate host configure command. For example, for the seed hypervisor:
+
+    .. code:: console
+
+       kayobe seed hypervisor host configure -t network -kt none
+
+ - Make sure there are no funky udev rules left in
+   ``/etc/udev/rules.d/70-persistent-net.rules`` (e.g. from cloud-init run on
+   Rocky 9.1).
+
+  - Inspect networking configuration at this point, ideally reboot to validate correctness.
+
+- Upgrade to Rocky Linux 9
+
+  .. https://forums.rockylinux.org/t/dnf-warning-message-after-upgrade-from-rocky-8-to-rocky-9/8319/2
+
+  - Install Rocky Linux 9 repositories and GPG keys:
+
+    .. code:: console
+
+       sudo dnf install -y https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/Packages/r/rocky-gpg-keys-9.2-1.6.el9.noarch.rpm \
+                           https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/Packages/r/rocky-release-9.2-1.6.el9.noarch.rpm \
+                           https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/Packages/r/rocky-repos-9.2-1.6.el9.noarch.rpm
+
+  - Remove the RedHat logos package:
+
+    .. code:: console
+
+       sudo rm -rf /usr/share/redhat-logos
+
+  - Synchronise all packages with current versions
+
+    .. code:: console
+
+       sudo dnf --releasever=9 --allowerasing --setopt=deltarpm=false distro-sync -y
+
+  - Rebuild RPB database:
+
+    .. code:: console
+
+       sudo rpm --rebuilddb
+
+  - Make a list of EL8 packages to remove:
+
+    .. code:: console
+
+       sudo rpm -qa | grep el8 > el8-packages
+
+  - Inspect the ``el8-packages`` list and ensure only expected packages are included.
+
+  - Remove the EL8 packages:
+
+    .. code:: console
+
+       cat el8-packages | xargs sudo dnf remove -y
+
+- You will need to re-create *all* virtualenvs afterwards due to system Python version upgrade.