Upgrade Procedure

The high-level steps of the Itential Platform upgrade process are explained as follows.

Before Starting

Prepare for the upgrade:

• Obtain an installer for the target version of the Platform.
• Review the official documentation for the mongodump and mongorestore utilities on the MongoDB Database Tools site.
• Itential installer creates a systemd service for the Platform named pronghorn. Make sure you are familiar with systemctl/journalctl for managing and monitoring system services.
• Review all Product Notices related to your target Itential Platform version and audit your system for any potential impact.
• Ensure that bash and tar are installed on the system.

Warnings and Precautions

After preparing for the upgrade, you will need to consider how long the process will take and when users need to be logged off the system so that you can schedule your upgrade accordingly.

• During any major version upgrade of the Platform, all jobs must be in a “completed” or “canceled” state.
  • In-flight jobs are not supported across major version upgrades of Itential Platform.
• Upgrading the Platform will write to your current database in order to migrate data.
  • Be sure to make a backup of your database to allow rollback in the event of an upgrade failure.
• Upgrading the Platform requires a period of downtime.

Upgrade Procedures

Follow these steps to upgrade:

1. Before the upgrade can be performed, all jobs must be in a “completed” or “canceled” state.
2. With the current version of the Platform running, prevent Itential Platform from starting new jobs:
   1. For 2023.1 and above, this may be done from the Admin Essentials UI homepage (Admin Essentials → Server Information → Accept New Jobs).
   2. For 2022.1, this must be done by individually disabling job sources:
      1. Automation Catalog Automations
      2. Operations Manager Automation Triggers
      3. Any non-Itential product that uses the startJobWithOptions API from Workflow Engine.
3. Ensure all jobs are complete, or canceled.
4. Once all jobs are in the appropriate state, shut down Itential Platform.
5. Create a database backup using the mongodump utility.
6. Refer to the properties.json file to identify the correct logical database name.
7. If using adapter-local_aaa for any purpose, create a backup of its database also.

8. Make sure all dependencies align with the version requirements of the target version of Itential Platform.
9. Make sure your configuration complies with the requirements detailed in the Installing Dependencies section.
10. Follow the official documentation when upgrading dependency versions wherever a version upgrade is required.

11. Set permissive mode and use the installer to upgrade to the new version of Itential Platform.

    sudo setenforce permissive
    sudo bash ./itential-<build-id>_<version>.linux.x86_64.bin --upgrade
    

12. Using the installer will:

    1. Leave the existing version of Itential Platform in place.
    2. Install the new version of Itential Platform alongside the existing version.
    3. Link /opt/pronghorn/current to the newly installed version of Itential Platform.

Start New Platform Version

By default, the pronghorn Systemd service uses /opt/pronghorn/current to decide which version of Itential Platform to start.

Run the following to start the new version of the Platform.

sudo systemctl start pronghorn

Verify Upgrade

Log into Itential Platform and audit the following.

• Roles, Accounts, Groups, and associated permissions: If new applications or adapters have been added as part of the upgrade, you may need to assign additional roles to users or groups.

• Database Indexes: These are visible in the Admin Essentials application, under the Active Profile. The Platform will also automatically detect missing indexes and display them under Alerts on the Admin Essentials dashboard page.

• Workflows: Audit your workflows for deprecated tasks and altered input schemas.

After verifying the correctness of the new install (upgrade), enable new jobs on the system from the Admin Essentials UI.