🏃 Ubuntu LTS Release Upgrade Runbook

This runbook provides step-by-step instructions to upgrade one Ubuntu 24.04 LTS VM to Ubuntu 26.04 LTS using the existing Ansible VM role and release-upgrade playbook.

1️⃣ Login to an Ansible Control Node

Start on a control node with Ansible and the repository environment available:

cd ~/ansible
source /opt/python_3.12/bin/activate
INV=inventory/services/inventory.ini

⚡ Important: Run the playbook from the Ansible control node, not from the VM being upgraded.

2️⃣ Pull the Latest Code

Check for local changes, then update the repository:

git status --short
git pull --ff-only origin main

If you have uncommitted changes, resolve or preserve them before pulling.

3️⃣ Select and Verify the VM

Set the inventory hostname. lidarr-0 is an example; replace it with the single VM you intend to upgrade:

HOST=lidarr-0
ansible vms -i "$INV" --list-hosts --limit "$HOST"
ansible "$HOST" -i "$INV" -m ansible.builtin.setup -a 'filter=ansible_distribution*'

Proceed only if the host list contains exactly one VM and its facts report Ubuntu 24.04. The playbook rejects other source releases and upgrades only to 26.04.

4️⃣ Confirm the Rollback Plan

Schedule a maintenance window and confirm you have a usable backup. The playbook creates a uniquely named Proxmox snapshot before package changes, using the existing vms role. Confirm Proxmox snapshot storage has sufficient space and the control node can access the configured Proxmox API.

The snapshot does not include VM memory state. Keep it until the application and host have been verified; follow your normal retention process before removing it.

5️⃣ Run the Release Upgrade

Run the dedicated playbook, explicitly limiting it to the selected VM and confirming the release upgrade:

ansible-playbook -i "$INV" playbooks/linux/release_upgrade_ubuntu.yml \
  --limit "$HOST" \
  -e linux_release_upgrade_confirm=true

The playbook updates installed packages first, installs/configures Ubuntu’s release upgrader for LTS releases, runs do-release-upgrade, reconnects, and verifies Ubuntu reports version 26.04. It also performs a reboot when required. Use -k if Ansible needs an SSH password or -K if it needs a become password.

⚡ Important: Do not omit --limit or the explicit confirmation. The playbook is intentionally guarded to run against exactly one host.

6️⃣ Redeploy Python 3.12

After the release-upgrade playbook confirms the VM is on Ubuntu 26.04, repair Python 3.12 on VM to fix mismatched Ubuntu and PPA packages. Review APT’s removal plan before confirming, and do not run apt autoremove as part of this repair:

sudo apt remove python3.12 libpython3.12-minimal libpython3.12-stdlib

Redeploy Python 3.12:

ansible-playbook -i "$INV" playbooks/python/deploy_python3.yml

7️⃣ Update Python to 3.14

After the release upgrade succeeds, ensure the selected host’s inventory config in inventory/services/group_vars/all/main.yml sets all three values as shown:

python3_version: 3.14
python3_venv_folder: "/opt/python_{{ python3_version }}"
ansible_python_interpreter: "{{ python3_venv_folder }}/bin/python3"

The ansible_python_interpreter inventory variable intentionally overrides the /opt/python_3.12/bin/python3 default in ansible.cfg for services hosts; do not change the global default just for this upgrade. Deploy Python 3.14 to only the upgraded VM:

ansible-playbook -i "$INV" playbooks/python/deploy_python3.yml \
  --limit "$HOST"

The deployment playbook recreates the configured Python virtual environment if it does not match the requested version. Verify the virtual environment reports Python 3.14:

ansible "$HOST" -i "$INV" -m ansible.builtin.command \
  -a '/opt/python_3.14/bin/python3 --version'

8️⃣ Verify the Upgrade

Confirm the reported OS version:

ansible "$HOST" -i "$INV" -m ansible.builtin.setup -a 'filter=ansible_distribution_version'

Confirm the facts report 26.04, then check the service is healthy. For the Lidarr example, open https://lidarr.refol.us and verify the application loads and is operational.

If the playbook fails after the release-upgrade command starts, inspect the VM’s current state and Ansible output before retrying. Do not rerun blindly; use the Proxmox snapshot only through your normal recovery procedure.

✅ Notes