- 01 May 2024
-
DarkLight
-
PDF
IAP Upgrade Procedure
- Updated on 01 May 2024
-
DarkLight
-
PDF
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
andmongorestore
utilities on the MongoDB Database Tools site. - Itential installer creates a systemd service for IAP named
pronghorn
. Make sure you are familiar withsystemctl/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
andtar
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:
- Before the upgrade can be performed, all jobs must be in a “completed” or “canceled” state.
- With the current version of IAP running, prevent IAP from starting new jobs:
- For IAP 2023.1 and above, this may be done from the Admin Essentials UI homepage (Admin Essentials → Server Information → Accept New Jobs).
- For IAP 2022.1, this must be done by individually disabling job sources:
- Automation Catalog Automations
- Operations Manager Automation Triggers
- Any non-Itential product that uses the
startJobWithOptions
API from Workflow Engine.
- Ensure all jobs are complete, or canceled.
- Once all jobs are in the appropriate state, shut down IAP.
- 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 also.
mongodump
will include all logical databases by default if you do not specify --db
- Make sure all dependencies align with the version requirements of the target version of IAP.
- Make sure your configuration complies with the requirements detailed in the Installing Dependencies section.
- 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.
-
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
Change <build-id>
and <version>
in the installer binary above to match the version being installed.
-
Using the installer will:
- Leave the existing version of IAP in place.
- Install the new version of IAP alongside the existing version.
- 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.