IAP Upgrade Procedure
  • 01 May 2024
  • Dark
    Light
  • PDF

IAP Upgrade Procedure

  • Dark
    Light
  • PDF

Article summary

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.

  mongodump will include all logical databases by default if you do not specify --db

  1. Make sure all dependencies align with the version requirements of the target version of IAP.
  2. Make sure your configuration complies with the requirements detailed in the Installing Dependencies section.
  3. Follow the official documentation when upgrading dependency versions wherever a version upgrade is required.

If this was not done during installation, refer to the Template Builder Security Dependency page to appropriately configure your system for secure Jinja Template execution.

In the 2023.2 release, IAP uses Redis for message brokering previously handled by RabbitMQ. This requires new configuration settings for Redis which deserve special attention. Please see the Redis Dependency section for more detail.

  1. 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
    
Installer Version

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

  1. 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.

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

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


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.