Identified as part of documentation planning meeting (20/10/11).

Yes, there are corner cases, but we could create a basic upgrade guide that outlines the general process, order of doing things, recommendations, gotchas, etc. Then we can expand on it by adding additional guidelines for specific corner case scenarios. 

Some existing Discourse articles:

https://opennms.discourse.group/t/upgrading-horizon-23-to-24-on-centos-7-and-switch-to-openjdk-11/421

Documentation Structure

This content should appear in the deployment section of the documentation, since it is a form of deployment.

• Introduction

  • State documentation scope: for basic upgrade, with additional procedures for different upgrade scenarios

  • Describe upgrade process, general steps involved.

  • -Refer to "maintenance" updates such as Java environment? - make this an overall separate topic?-

•  

  •  

    • include backup, restore, etc.

    • -upgrading db? (schema, part of overall ONMS update - upgrade PG 13 to 14, e.g.)-

• -Before you begin - recommended pre-upgrade tasks - where applicable, link to the associated procedure:-

•  

  • Check breaking changes (release notes) and address any issues that may affect you

  • Stop OpenNMS & PG

  • Back up your database (same day/state)

  • Backup RRD files (same day/state)

  • Back up ONMS /etc directory & software (ONMS folder) (same day/state)

  • Assess the Events table Size (ask re: larger customers, could be scale issue)

  • Determine which configuration files you have customized to migrate only config. files that you need to

• Housekeeping/Maintenance

  • Deleting older events, reasonable to delete these

  • Outdated RRD files

  • -Assess events table size (for really large - millions of events/upgrade task will take longer)-

  • Do diff on configuration files

  • Delete cache folder (post-installation task)

• Backup system (need to do this for each supported version like with the install, using tabs)

•  

  • database

  • RRD

  • ONMS installation

• Basic Upgrade procedure

  • Include updating permissions if upgrading from pre-29/2022 version (script to do this isn't available until after 29/2022 packages are installed)

  • Include how to determine installation was successful

• Post installation tasks:

  • Delete cache folder ("Fix Karaf script" deletes the cache folder)

  • Troubleshooting an installation?

• How to uninstall

• Additional upgrade scenarios (TBD)

  • ONMS core and sentinels & Minions (order to upgrade/shutdown/ etc.)

•  

  •  

    • Minion: update/restart (unless breaking change in release notes)

• Rollback procedure

  • restore ONMS directory (easier to copy whole folder from the backup)

• Any issues with Helm and Alec, Nephron after you've upgraded ONMS?

Disaster Recovery

• Backup

• Restore