Configuration Enhancements

The end-to-end experience of installing, configuring and completing a first-time run of Itential Platform has been simplified, and you can now configure Platform 6, Itential's latest software release, through environment variables with the ability to deploy as a container. There are several feature benefits to deploying installation of the Platform in this way, namely:

• Consolidated Startup Configuration: All startup configuration is now in a single location.

• User-Defined Environmental Variables: Platform 6 can be configured entirely through environmental variables, including an encryption key.

• Intelligent Default Values: Itential Platform will automatically generate and pre-fill default common values if a customer does not fully configure their system.

• Hierarchical Configuration: Configuration will follow a hierarchy that allows customers to configure once and deploy to several locations.

• Default User: Enable customers to login and configure Itential Platform without first setting up Local AAA (default user).

Another improvement to the experience of installing and configuring Itential Platform is the efficiency gain of time and resources during upgrades. Additionally, having this new install allows users to define their own Encryption Key, and provide that key within environmental variables, or via the on-disk properties document. Lastly, these start up features are inherent to Platform 6 and require no installation.

Configuration

In previous Itential Platform releases, configuration was delegated between a properties.json file and a profile configured within MongoDB. Starting with the Platform 6 release, Itential Platform is now primarily configured through Environment Variables or a functionally equivalent platform.properties configuration file. This functionality replaces the legacy properties.json file. As such,configuration via properties.json is fully deprecated in Platform 6.

Starting with Platform 6, the bin installer will no longer copy over the previous properties.json file. To migrate a properties.json file into a new itential.properties file, run this command:

npm run migrate:properties -- --json-file=<path> --out-file=<path>

The file generated by this script includes commented out defaults and descriptions for all excluded properties.

Itential Platform can be supplied a itential .properties file (or a properties.json) with the --config-file=<path> launch option. If no --config-file argument is given, Itential Platform will first look in /etc/itential/platform.properties, then the Platform installation directory for a properties.json. If neither file exists, defaults will be used for all configurations not defined by Environment Variables.

Profiles are also no longer required for configuration. It is best practice in Platform 6 to use Profiles only for configurations that may change while the server is running, such as prebuiltProps.

Additionally, if no configuration for a property exists, Platform 6 will now supply a sensible default value. When conflicting configuration properties are provided, they are resolved in the following priority order:

1. Environment Variable
2. Configuration File
3. Profile
4. Default Value

This hierarchy allows users to make a reusable Configuration File and override any necessary properties with Environment Variables for deployment.

To view the current configuration in Platform 6, navigate to the Itential Platform → Admin Essentials → Configuration page. From this page view, all configuration properties, their values and their origins are shown (Figure 1).

Property File Formats

To illustrate the differences in property file formats between Itential Platform release versions, the following samples will demonstrate how property names are displayed. For a complete table of properties in Platform 6 see the References section within this document.

Legacy Platform

Legacy properties.json file (Itential Platform 2022.1, 2023.1 and 20232.2)

This is also the format used by Profiles.

{
  "serviceDirectory": "dev/services",
  "mongoProps": {
    "db": "platform6"
  },
  "loggerProps": {
    "log_directory": "dev",
    "webserver": {
      "log_directory": "dev"
    }
  },
  "authenticationProps": {
    "admins": [
      {
        "provenance":"Local AAA",
        "group":"pronghorn_admin"
      }
    ]
  },
  "encryptionKey": "74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37"
}

Platform 6

Here is the equivalent platform.properties Configuration file (Itential Platform 6).

# My Comment
service_directory = dev/services
mongo_db_name = platform6
log_directory = dev
webserver_log_directory = dev
auth_admin_groups = [{"provenance":"Local AAA","group":"pronghorn_admin"}]
encryption_key = 74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37

Env Variables Platform 6

Here is an equivalent declaration of Environment Variables (Itential Platform 6).

export ITENTIAL_SERVICE_DIRECTORY="dev/services"
export IAP_MONGO_DB_NAME=platform6
export IAP_LOG_DIRECTORY=dev
export IAP_WEBSERVER_LOG_DIRECTORY=dev
export IAP_AUTH_ADMIN_GROUPS='[{"provenance":"Local AAA","group":"pronghorn_admin"}]'
export IAP_ENCRYPTION_KEY=74b589bce5a0aaae1d45f13479208f34f5eb0458bde7fb81a2f26ee8d61fae37

Default User

Previously, Itential Platform required users to install an AAA adapter before being able to log in and use the platform, which meant the install had to be done without the GUI. Platform 6 now enables a default user account to log in and configure any necessary AAA adapters through Admin Essentials. The default user can be configured with the following variables.

The primary purpose of the default user is only to set up the first admin account. Once any AAA/SSO adapter is enabled, the default user will be disabled from logging in again, and the Platform should be restarted.

Status Page

Prior to Platform 6, the Profiles page in Admin Essentials contained “Applications”, “Adapters”, “Configure”, and “Indexing” tabs. Now that Itential Platform can now run without a Profile, the “Applications”, “Adapters”, and “Indexing” tabs were moved for accessibility.

The Profiles page in Admin Essentials now only contains the contents of the “Configure” tab. As implied by the location, any configuration done inside of a Profile will only affect that Profile; there is no way to modify a Config File or Environment Variables in Admin Essentials.

The contents of the three moved tabs (“Applications”, “Adapters”, and “Indexing”) can be found on the new Status page. These moved tabs still provide the same information and controls as before; Applications gives status information of all configured Platform services, Adapters gives information about configured Adapters, and Indexing gives the status of the MongoDB indexing.

Limitations

Some known limitations associated with the Platform 6 configuration include:

• Profiles are still only accessible after connecting to MongoDB. Any configuration related to MongoDB (including encryption) cannot be defined within a Profile.
   
• Any Configuration setting that captures the Platform state must only exist in a Profile document. As of Platform 6, the only stateful property is prebuiltProps.
   
• The switchActiveProfileAPI has been deprecated. Switching profiles is only possible when Itential Platform has been configured with a deprecated properties.json file.
   
• Environment Variables and Config Files are only read when Itential Platform starts. You must restart the platform to see changes in configuration.
   
• Itential Platform will never automatically modify the contents of your platform.properties file or your Environment Variables. Any changes to your platform.properties file must be done outside of the Platform.
   
• The Default User is only able to log in before any AAA/SSO Adapter is configured. Once a qualifying Adapter is running, Itential Platform will not accept new logins by the default user, though active sessions with this user may continue to function.
   
• Only one configuration file may be supplied to the Platform. If there is both a file at /etc/itential/platform.properties, a legacy properties.json in the installation directory, and no --config-file option is supplied, only the platform.properties file will be used, as it is the first location checked.

Should you encounter any issues during configuration or need extra support, please reach out to the Itential Service Desk using the Customer Portal link.

Related Reading

Platform 6

• Installation
• Upgrading
• Adapters & Custom Apps