Legacy Platform Upgrade

This guide will assist users in upgrading Itential Platform using the BIN install method for on-premises software in legacy release versions.

If you encounter any blocking issues while upgrading, use the Rollback procedure presented within this guide.

Prerequisites

Before taking any action, please:

• Review this document in full and establish a complete upgrade plan.
• Review all Product Notices related to the Platform version you are targeting.
  • This will ensure you are well informed of any new features, deprecations, and breaking changes associated with upgrading to a target version.
  • To avoid service disruption, be sure to pay particular attention to the detail within the breaking change product notices.
• Ensure that bash and tar are installed on the system.

If you need help establishing an upgrade plan, contact your Itential Account Manager.

Upgrade Support

• Itential provides support for previous releases of the Platform according to its Version Lifecycle.
• If your current version is out of support, you may need to contact your Itential Account Manager for additional upgrade instructions.
• Itential strongly advises that you do not skip major versions when upgrading.

Upgrade Procedure

The Itential Platform upgrade process has several steps. To ensure a successful upgrade, follow these steps as they are presented in this section.

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 & 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 Process

Follow these steps to upgrade Legacy platform versions:

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.

Rollback Procedure

If you encounter any blocking issues while upgrading, use the Rollback Procedure outlined below

Warnings & Precautions

The database must be restored to a previous state to ensure feature compatibility. Any data changes made after your latest backup from the rollback-target version of Itential Platform will be lost.

Rollback Process

1. If you have fully completed the upgrade, and the new version is live, prevent the new version of the 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.

2. If the new version of the Platform has been live for any length of time, now would be an appropriate time to burn down in-flight jobs, if needed. Note that regardless of job burn-down, you will not have access to post-upgrade jobs after you complete the rollback.

3. Once all jobs are in the appropriate state, shut down the Platform.

4. Create a database backup using the mongodump utility. This preserves post-upgrade data changes for reference purposes only, and will not be usable in the version of the Platform targeted by the rollback.

5. Make sure all dependency versions satisfy the requirements of the Platform version targeted by the rollback.

6. Restore the previous database state from the archive that was created before upgrading using the mongorestore utility. Use the --drop flag to ensure all collections are cleared before importing the archived contents. This will delete any data changes made after the upgrade was completed.

7. Link the previous version of the Platform to /opt/pronghorn/current.

   ln -s /opt/pronghorn/<PREVIOUS_IAP_VERSION> /opt/pronghorn/current
   

8. Start the Platform. At this point, Itential Platform should be rolled back to the previous version, with the database as it was prior to upgrading.

Troubleshooting Help

Refer to Common Errors to help identify and resolve the more frequent errors you may encounter in the upgrade. If unable to resolve, please contact the Itential Service Desk.