Platform Upgrade

  • Updated on Apr 16, 2025
  • Published on Feb 27, 2025
Prev Next

This guide will provide users instructions on how to upgrade their Itential Platform installation from 22.1, 23.1, or 23.2 to Platform 6, Itential's latest platform product.

Due to changes in the Platform 6 directory structures, Itential strongly recommends against an in-place upgrade, and instead recommends a greenfield installation and migration of applications, adapters, and database. The instructions below will detail that process.

Prerequisites

Before taking any action, please:

  • Review this document in full to understand the steps involved for your upgrade to successfully take place, and be sure to review all Product Notices related to Platform 6.
    • This will ensure you are well informed of any Deprecations associated with upgrading to the target version.
    • To avoid service disruption, be sure to pay particular attention to the detail within the Breaking Changes.

If you need help establishing an upgrade plan for your Itential software, please contact your Itential Account Manager.

Installation of Platform 6

Installation of Platform 6 may be accomplished following the instructions here:

Migration of Encrypted Secrets

With the change to Platform 6, Itential has enabled users to define an encryption key for use within the platform.

An encryption key is required for operation of Itential Platform 6

Existing data sets from prior Platform releases will likely contain encrypted secret values. These values must be migrated to use the encryption key provided by the user in Platform configuration prior to platform start.

Itential provides a one-time migration utility as part of the Platform installation to assist in this process.

This utility will connect to an existing Itential Platform database, decrypt existing secrets, re-encrypt them with a user-specified key, and then write them back to the database. Additionally, if a properties.json file is used to configure the database connection, and that properties.json file contains $ENC encrypted values, the values in that file will be migrated as well.

⚠ A backup of the MongoDB Database is required prior to running the Key Migration Utility. The Key Migration Utility is designed to connect and write to the database it is directed to operate on.

⚠ If a properties.json file is used and contains $ENC encrypted secrets, create a backup of the file before running the Key Migration Utility. Encrypted values will be rotated in-place in the original file.

⚠ The Key Migration Utility cannot be run multiple times on a single database. All collections within the database must be migrated when running the tool. Any collections not migrated cannot be migrated at a later time. If a collection is not migrated, or the migration script is interrupted, users must restore the database from backup and run the Key Migration Utility again.

To run the migration utility, use the command npm run key:migrate from inside /opt/itential/platform/server. This utility requires a database connection, and is compatible with the same environment variables, properties configuration file, and legacy properties.json file that the platform server supports.

The migration utility requires that either the --config-file parameter or --properties-json parameter to be given, and requires that the --encryption-key parameter be provided.

All arguments passed to the script must be separated from the script name by an “end-of-options delimiter”: --. This is required by npm.

Valid application of an argument for --encryption-key:

npm run key:migrate -- --encryption-key "$KEY"

Invalid application of an argument for --encryption-key (missing end-of-options delimiter):

npm run key:migrate --encryption-key "$KEY"

To configure the script's database connection with a properties configuration file, use the --config-file parameter.

npm run key:migrate -- --config-file /etc/itential/platform.properties

To use a legacy properties.json file to configure the script, use the --properties-json parameter. Note that this parameter is mutually exclusive with the --config-file parameter. They cannot both be given in the same command.

npm run key:migrate -- --properties-json ./properties.json

To use environment variables to amend configuration in the event that a property is not present in your configuration file, ensure they are set before running the command.

ITENTIAL_MONGO_URL=mongodb://127.0.0.1:27017 \
ITENTIAL_MONGO_DB_NAME=itential \
  npm run key:migrate -- --config-file /etc/itential/platform.properties

The key migration utility requires an explicitly defined key. Placing your encryption key in configuration is not supported. Use the --encryption-key parameter to specify your key.

npm run key:migrate -- --encryption-key "$KEY"

The key migration utility will migrate encrypted secrets in the following collections by default:

  • service_configs
  • oauth_clients
  • accounts
  • iap_profiles

If your organization uses custom collections, and those collections are known to contain values encrypted with Itential Platform’s legacy $ENC encryption scheme, the key migration utility supports additional collections with the --extra-collections parameter. Specify this parameter once for each collection name you wish to migrate alongside Itential’s standard set of collections.

A full example command is provided below:

npm run key:migrate -- \
  --encryption-key "$KEY" \
  --properties-json ./properties.json \
  --extra-collections custom-collection-1 \
  --extra-collections custom-collection-2

As it runs, the migration utility will report on its progress and any encrypted values it finds. After the script completes, you are free to connect Itential Platform 6 to your existing database.

Example output transcript:

> @itential/iap@6.0.0 key:migrate
> node utils/keyMigrate.js --encryption-key 0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff --properties-json ./properties.json --extra-collections custom-collection-1 --extra-collections custom-collection-2

Decrypting mongo properties
Collection service_configs migrated document 1 with _id 67c07c608998f13133c9ba97 pointer /properties/properties/database/url
Collection service_configs migrated document 1 with _id 67c07c608998f13133c9ba97 pointer /properties/properties/database/credentials/passwd
Collection service_configs migrated document 1 with _id 67c07c608998f13133c9ba97 pointer /properties/properties/database/credentials/user
Collection service_configs: Successfully replaced 1 of 1 documents
Couldn't find collection oauth_clients in available collections. Skipping...
Collection accounts migrated document 1 with _id 67c07c8da129bb3309dddbb3 pointer /gitTokens/GitHub
Collection accounts: Successfully replaced 1 of 1 documents
Collection iap_profiles migrated document 1 with _id 67c07c608998f13133c9ba8d pointer /redisProps/host
Collection iap_profiles migrated document 1 with _id 67c07c608998f13133c9ba8d pointer /redisProps/username
Collection iap_profiles migrated document 1 with _id 67c07c608998f13133c9ba8d pointer /redisProps/password
Collection iap_profiles: Successfully replaced 1 of 1 documents
Collection custom-collection-1 migrated document 1 with _id 67c082a124031ad65dc191b7 pointer /token
Collection custom-collection-1 migrated document 2 with _id 67c082a124031ad65dc191b8 pointer /token
Collection custom-collection-1 migrated document 3 with _id 67c082a124031ad65dc191b9 pointer /token
Collection custom-collection-1 migrated document 4 with _id 67c082a124031ad65dc191ba pointer /token
Collection custom-collection-1: Successfully replaced 4 of 4 documents
Collection custom-collection-2 migrated document 1 with _id 67c07f7a6a36a677248d730b pointer /device/secret
Collection custom-collection-2 migrated document 2 with _id 67c07f8f6a36a677248d730c pointer /device/secret
Collection custom-collection-2: Successfully replaced 2 of 2 documents
properties.json migrated pointer /mongoProps/url
properties.json migrated 1 items
properties.json added new encryptionKey field. DO NOT MODIFY THIS FIELD
Decryption recheck validated -- key migration successful!

Encryption Key:
0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff

Migration of Apps and Adapters

Due to changes in installation directories, custom applications and adapters must be migrated to a new directory. The default location of custom applications and adapters is:

/opt/itential/platform/services

Users may define a directory for Custom Apps and Adapters, if desired. Either the service_directory property in the platform.properties file, the ITENTIAL_SERVICE_DIRECTORY environment variable, or the serviceDirectory field in a profile document can specify a user-defined directory for adapter installation.

After defining the new location for custom applications and adapters, copy any custom applications and adapters from the Itential Platform 22.1, 23.1, or 23.2 installation. Itential's Open Source adapter offering is installed to the following path:

/opt/itential/current/node_modules/@itentialopensource

Applications and adapters produced by your organization will likely have a different path. If you have organization-managed applications or adapters, consult with your system administrator to determine their location.

Copy all custom apps and adapters into the new custom service directory associated with Platform 6. This is located at the following path by default:

/opt/itential/platform/services

Migration of Properties

Beginning with Platform 6, Itential Platform configuration within a properties.json file has been deprecated.

The platform is now fully configurable via:

  • On-disk platform.properties file
  • Environment variables

Platform 6 continues to support database profiles and the legacy properties.json file, but recommends that the user transitions to environment variables or the platform.properties file.

Transition to Platform Properties

A template platform.properties file is supplied within the following directory:

/opt/itential/platform/server/utils/template.properties

Users may continue to utilize a properties.json file by placing the file within the following directory:

/opt/itential/platform/server

Related Reading

Platform 6