Upgrading

This guide explains how to upgrade your software for the Itential Automation Platform (IAP).

Prerequisites

• Please review all Breaking Changes in the Product Notices section before upgrading IAP.
• Itential currently supports the use of MongoDB 4.2.x on all released IAP versions. If you are using an earlier version it is recommended that you upgrade.

Steps to Upgrade IAP Software

To upgrade the core IAP software from 2018.3 or 2019.1:

1. Verify the latest version of IAP has been copied to the server. You can acquire the link for this build from the portal.

2. The upgrade will capture your latest /opt/pronghorn/current/properties.json file and use it for your upgraded installation.

3. Shutdown IAP.

4. Refer to the Installing Dependencies section in the IAP Installation Guide to ensure that all dependency requirements have been met prior to continuing.

5. Change, cd, to the directory where the latest IAP install build .bin file is stored.

6. Run the following command to upgrade IAP (add -v for verbose output).

   bash pronghorn-<build-id>.linux.x86_64.bin -p

7. Change, cd, to the migration script directory.

   /opt/pronghorn/current/node_modules/@itential/pronghorn-core/migration_scripts

8. Run the migration script.

   node migratePropertiesToDatabase.js

   Important Notes

   • Running node migratePropertiesToDatabase.js unattended will automatically respond yes to all prompts, requiring no user input.

   • During an upgrade, a database backup will be triggered via installer script. For instances where IAP is connected via SSL to a mongo database and mongo is configured with the requireSSL property, the backup may fail with the following message:

     Failed: error connecting to db server: no reachable servers.

   • A mongo database backup can be created using a mongodump command like this:

     sudo mongodump --ssl --db pronghorn --host $hostname --port 27017 --username $mongoUsername --password $MONGOPASS --sslCAFile $pathToCert

9. Respond to the migration script prompts to match the deployment environment.

   Retrieving properties.json file...
   Found properties.
   
   Connecting to Database...
   Are you sure you want to delete the following databases:
   iap_profiles
   service_configs
   (y)es (n)o y
   y
   No service_configs collection detected, skipping.
   No iap_profiles collection detected, skipping.
   RabbitMQ hostname and port are currently set to "localhost:5671". Do you wish to keep these?
   (y)es (n)o y
   y
   Retaining localhost:5671
   Would you like to run WITHOUT SSL?
   (y)es (n)o y
   y
   RabbitMQ credentials currently set to
   
   username: guest
   password: guest
   
   Do you wish to keep these?
   (y)es (n)o y
   y
   Retaining guest credentials
   RabbitMQ properties:
   
   {
   "protocol": "amqp",
   "hostname": "localhost",
   "port": 5672,
   "username": "guest",
   "password": "$ENC84ff82395069f15bdb8e014991d32417818a228dad",
   "locale": "en_US",
   "frameMax": 0,
   "heartbeat": 0,
   "vhost": "/",
   "certPath": "",
   "keyPath": "",
   "passphrase": "guest",
   "caPath": ""
   }
   Backing up properties.json to /opt/pronghorn/itential-1568912783776/properties_9c95343d-51df-41a7-9073-d21f34c840f8.json
   
   Loading services...
   (node:7345) Warning: Use Cipheriv for counter mode of aes-256-ctr
   Services loaded 8
   
   Generating init file data...
   Config data generated.
   
   Generating DB data...
   DB data generated.
   
   Connection established.
   
   Creating databases...
   Creating service_configs
   Creating iap_profiles
   Database creation complete.
   
   Creating IAP database config...
   Collection iap_profiles created!
   IAP database config created.
   
   Creating service configs entries...
   Collection service_configs created!
   Service configs entries created.
   
   Cleaning up properties.json...
   Migration complete!

   Note: The migration script output above assumes that RabbitMQ is running on the same node as IAP, using default RabbitMQ credentials, and has SSL disabled. For security reasons this RabbitMQ configuration is not recommended for a production environment.

10. The migration script will migrate much of the /opt/pronghorn/current/properties.json content to the Mongo database. A backup of the original properties.json file is generated during migration and will appear similar to /opt/pronghorn/current/properties_4d37a26d-e5e1-4796-845d-220f09681d65.json.

11. Note any adapter schema errors in startup logs. Errors for adapter schema issues should be fixed in the properties.json file, or using the System > Adapters view.

Restart IAP & Login

1. Restart IAP.

2. Login to verify the service is up.

3. In the event you are unable to find old automations, tags, etc., run the migration script for the respective application and refresh IAP.

4. For example, if you are not finding tags created on a previous version of IAP:

   • Locate the migration script for tags.

     cd
     /opt/pronghorn/current/node_modules/@itential/tags/migration_scripts

   • Run the script.

     node migrateTagRefs.js

   • Refresh IAP.

5. If you are still experiencing issues after running the migration script, please log a ticket with the Itential Service Desk. Be sure to provide all necessary information to reproduce the issue and one of our Customer Success Agents will help to address your issue.