Upgrade Platform 2023.2

This guide assists 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, see the Rollback procedure below.

To upgrade from Itential 2023.x or 2022.x to Platform 6.x, see Upgrade to Platform 6.x.

Prerequisites

Before taking any action:

Review this document in full and establish a complete upgrade plan.
Review all release notes related to the Platform version you are targeting. This ensures you are informed of any new features, deprecations, and breaking changes. Pay particular attention to breaking change notices to avoid service disruption.
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

Before starting

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.
The Itential installer creates a systemd service for the Platform named pronghorn. Ensure you are familiar with systemctl and journalctl for managing and monitoring system services.
Review all release notes related to your target version and audit your system for any potential impact.
Ensure that bash and tar are installed on the system.

Warnings and precautions

During any major version upgrade, all jobs must be in a completed or canceled state. In-flight jobs are not supported across major version upgrades.
Upgrading the Platform writes to your current database to migrate data. Back up your database before upgrading to allow rollback in the event of a failure.
Upgrading the Platform requires a period of downtime.

Upgrade steps

Ensure all jobs are complete or canceled

All jobs must be in a completed or canceled state before the upgrade can be performed.

Prevent new jobs from starting

With the current version of the Platform running, prevent Itential Platform from starting new jobs:

2023.1 and above: From the Admin Essentials UI homepage, go to Admin Essentials > Server Information > Accept New Jobs.
2022.1: Individually disable job sources:
1. Automation Catalog Automations
2. Operations Manager Automation Triggers
3. Any non-Itential product using the startJobWithOptions API from Workflow Engine.

Confirm all jobs are complete or canceled

Verify all jobs are in the appropriate state.

Shut down Itential Platform

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

Back up the database

Create a database backup using the mongodump utility. Refer to the properties.json file to identify the correct logical database name.

If using adapter-local_aaa for any purpose, create a backup of its database as well.

mongodump includes all logical databases by default if you do not specify --db.

Verify dependency versions

Ensure all dependencies align with the version requirements of the target version of Itential Platform.

In the 2023.2 release, the Platform uses Redis for message brokering previously handled by RabbitMQ. This requires new Redis configuration settings. See the Install Platform section for details.

Run the upgrade installer

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

Change <build-id> and <version> in the installer binary above to match the version being installed.

The installer will:

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

Start the new Platform version

By default, the pronghorn systemd service uses /opt/pronghorn/current to determine which version to start.

$ sudo systemctl start pronghorn

If you used AGManager in your previous Platform version, run the discoverAll method after starting the upgraded Platform version. This restores AGManager tasks from your IAG adapters. See Automatic discovery in IAG for more information.

Verify the upgrade

After starting the new version, audit the following:

Roles, accounts, groups, and permissions: If new applications or adapters were added as part of the upgrade, you may need to assign additional roles to users or groups. Verify that admin users and groups contain all newly added roles, such as “SSO” and “SSOGroupMappings” permissions required to access and configure Identity Providers.
Database indexes: These are visible in the Admin Essentials application under the Active Profile. The Platform also automatically detects missing indexes and displays them under Alerts on the Admin Essentials dashboard.
Workflows: Audit your workflows for deprecated tasks and altered input schemas.

Your organization may require additional verification steps, such as checking adapter configuration and health.

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

Rollback procedure

Warnings and 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 will be lost.

Rollback steps

Prevent new jobs from starting

If the new version is live, prevent it from starting new jobs:

2023.1 and above: From Admin Essentials, go to Server Information > Accept New Jobs.
2022.1: Individually disable job sources:
1. Automation Catalog Automations
2. Operations Manager Automation Triggers
3. Any non-Itential product using the startJobWithOptions API from Workflow Engine.

Burn down in-flight jobs if needed

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

Shut down the Platform

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

Back up the post-upgrade database

Create a database backup using the mongodump utility. This preserves post-upgrade data changes for reference purposes only — this backup cannot be used in the Platform version targeted by the rollback.

Verify rollback-target dependency versions

Ensure all dependency versions satisfy the requirements of the Platform version targeted by the rollback.

Restore the pre-upgrade database

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

Link the previous Platform version

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

Start the Platform

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

Refer to Common Errors to help identify and resolve frequent errors encountered during an upgrade. If unable to resolve, contact the Itential Service Desk.