IAP Upgrade Procedure

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

Before Starting

Prepare for the upgrade:

• Obtain an installer for the target version of IAP.
• Review the official documentation for the mongodump and mongorestore utilities on the MongoDB Database Tools site.
• Itential installer creates a systemd service for IAP named pronghorn. Make sure you are familiar with systemctl/journalctl for managing and monitoring system services.
• Review all Product Notices related to your target IAP 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 IAP, all jobs must be in a “completed” or “canceled” state.
  • In-flight jobs are not supported across major version upgrades of IAP.
• Upgrading IAP 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 IAP requires a period of downtime.

Upgrade Procedures

Follow these steps to upgrade IAP:

1. Before the upgrade can be performed, all jobs must be in a “completed” or “canceled” state.
2. With the current version of IAP running, prevent IAP from starting new jobs:
   1. For IAP 2023.1 and above, this may be done from the Admin Essentials UI homepage (Admin Essentials → Server Information → Accept New Jobs).
   2. For IAP 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 IAP.
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 IAP.
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 IAP.

    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 IAP in place.
    2. Install the new version of IAP alongside the existing version.
    3. Link /opt/pronghorn/current to the newly installed version of IAP.

Start New IAP Version

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

Run the following to start the new version of IAP.

sudo systemctl start pronghorn

Verify Upgrade

Log into IAP 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. IAP 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.