Migration

Migrating IAP

This guide explains how to migrate IAP from one environment to another.

Note: Breaking changes to be aware of prior to migrating or upgrading IAP are discussed in the Product Notices section.

Steps to Migrate Software

To migrate the core Pronghorn (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 customer portal.

2. Migrating will capture your latest /opt/pronghorn/current/properties.json file and use it for upgraded installations.

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 Info

   • 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:

     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 above output from the migration script 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 the startup logs. Errors 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 the problem.