Upgrade the Navin Manager

This page upgrades the Navin Manager server and the Navin agents to a new release from the packages. It is done by a system administrator and takes about 15 minutes for the server, plus a few minutes per host. The services managed by the Manager keep running during the upgrade: they are upgraded separately from the Lifecycle page (console guide).

Before you begin

• Read the release notes of the new version; the three packages (navin-platform, navin-manager, navin-manager-agent) share one version.
• Back up the Manager database (a pg_dump of navin_manager) and keep a copy of /etc/navin-manager (server.yaml, server.env, master.key, tls/).
• Check that no operation is running: Operations shows no running operation.
• Check the current state: sudo navinctl status and sudo runuser -u navin-manager -- navin-manager migrate --status.

Steps

1. Upgrade the server package. The package rebuilds /opt/navin-manager/venv from the new wheelhouse (the previous venv is restored if the build fails), completes server.env without overwriting a value, keeps server.yaml (%config(noreplace), DEB conffile, pacman backup) and restarts the running server.

   sudo apt update && sudo apt install --only-upgrade navin-manager   # Ubuntu
   sudo dnf upgrade navin-manager                                     # RHEL, Rocky Linux, AlmaLinux
   sudo pacman -Syu                                                   # Arch Linux (the only upgrade it supports)

   With package files: sudo apt install ./navin-manager_<version>_amd64.deb, sudo dnf upgrade ./navin-manager-<version>-1.el9.x86_64.rpm or sudo pacman -U ./navin-manager-<version>-1-x86_64.pkg.tar.zst.

   Expected result: the package manager reports the new version; systemctl is-active navin-manager prints active.

   If it fails: navin-manager: the venv could not be built from /usr/share/navin-manager/wheelhouse; the previous venv is restored: install the Python the package depends on, then run the upgrade again.

2. Check the migrations. The unit applies the pending migrations before each start. --check exits 1 unless every migration is applied and unchanged.

   sudo runuser -u navin-manager -- navin-manager migrate --check

   Expected result: the last line counts only applied migrations, for example 28 applied, 0 pending, 0 changed, 0 unknown (28 migrations in release 1.0.0).

   If it fails: pending means the server has not started yet (journalctl -u navin-manager); unknown means the database is newer than the package (a downgrade): install the newer package again.

3. Upgrade the agents. On each managed host, upgrade the agent package; the package restarts a running agent (try-restart) and keeps its registration (/var/lib/navin-manager-agent). The managed services keep running because the unit stops the agent process only (KillMode=process).

   sudo apt install --only-upgrade navin-manager-agent-go   # Ubuntu, Debian
   sudo dnf upgrade navin-manager-agent-go                  # RHEL family
   sudo pacman -Syu                                         # Arch Linux

   Expected result: nm-agent --version prints the new version and the host is healthy in Hosts.

   If it fails: see Troubleshoot the Navin agent.

warning

On Arch Linux the server package depends on the Python version it was built for (python>= and python< the next minor): pacman refuses a Python upgrade that would break the venv until the Navin release built for the new Python is installed. Upgrade both in the same pacman -Syu.

Verify

sudo navinctl version
sudo navinctl check

Expected result: the versions of navin-manager and navin-manager-agent-go are the new ones, navinctl check prints settings are valid for this environment, and the System page of the console shows the new version.

Next steps

• Upgrade the managed services
• Operations reference

Troubleshooting

Symptom	Cause	Fix
The server does not restart after the upgrade	a new production check fails	sudo runuser -u navin-manager -- navin-manager check
migrate --check reports changed	a migration file was edited after its release	reinstall the package of the release; never edit a released migration
pacman refuses the Python upgrade	the Navin release for the new Python is not installed	upgrade navin-manager in the same transaction