Preparing Orchestrator

To migrate Orchestrator from standalone to Automation Suite, you must gather settings and various files from the standalone installation and apply them to the Automation Suite installation.

Depending on the configurations you use in Orchestrator, you may need to prepare web.config, appSettings, storage, NLog, credential stores, encryption keys, and encryption key per tenant.

Migration overview

To migrate Orchestrator from standalone to Automation Suite, you must gather settings and various files from the standalone installation and apply them to the Automation Suite installation.

While only part of the settings are configurable at installation time, all of them should be available for post-install configuration.

• To configure settings at installation time, add them in the cluster_config.json file;
• Updating the settings after the installation completes depends on what the setting scope is and if a feature is available for configuration from app-of-apps parameters or not.

You can store custom files that are needed inside the Orchestrator pods, such as assemblies or other storage files, in the built-in Ceph object store. The storage files are stored in a bucket for each tenant. The plugins are stored in the uipath bucket under orchestrator/plugins/nlog or orchestrator/plugins/securestore.

You can add custom configuration as follows:

• by editing the application parameters in ArgoCD (parameter overrides);
• by editing the files inside the Kubernetes ConfigMap orchestrator-customconfig from the namespace uipath.

Preparing web.config

Most web.config settings do not have an equivalent or are implemented in Automation Suite using other mechanisms.

The options that you do need to configure are the following:

security.requestFiltering.requestLimits.maxAllowedContentLength

Note the value of this setting for later use. Decide if you need to configure it in Automation Suite. Its default value is 300MiB.

Preparing appSettings

You may need to migrate custom changes made in the appSettings or secureAppSettings section of the UiPath.Orchestrator.dll.config configuration file. You can add custom appSettings and secureAppSettings to the orchestrator-customconfig config map.

In the UiPath.Orchestrator.dll.config configuration file's appSettings section, identify any modified or added settings. Save these settings in a .json file, so they are available in later steps.

You can decrypt any protected app configuration section with Orchestrator CLI protected-configuration option. You only need to use the settings you have changed or added and are still relevant in Automation Suite.

Note:

You can create the appsettings.json file as shown in the following example:

{
  "ExampleSetting.Enabled": true,
  "ExampleSetting.Type": "BasicExample",
  "ExampleSetting.Count": 3
}

Preparing storage

Decide what you need for the storage migration and if your current storage configuration stays the same or if you would instead let Automation Suite manage the storage for you. Automation Suite offers the option to store the blobs in Ceph, which can be used in all Orchestrator pods. In the case of a migration, you must copy the existing files to the current blob storage.

If you are using storage of type FileSystem with a local folder, copy the data from the storage folder to a folder on a node from Automation Suite. Then, using an utility such as rclone, you can copy the data to Orchestrator. If you use Ceph, then no other configuration is required, as this is the default option.

If you want to use FileSystem with a Windows network share, you need to configure the storage in the ArgoCD Orchestrator app. Retrieve the connection data to the Windows network share from your current Orchestrator config from the Storage.Location key. Since Automation Suite runs on Linux machines, you cannot rely on integrated authentication for accessing the network share, so you need the credentials of an account that can access it.

Note:

Currently, only network shares that use the SMB protocol are supported. Network shares that use NFS are not supported.

If you use remote storage options such as Azure, AWS, or Minio, make sure to add the Storage.Location and Storage.Type settings to the appsettings.json.

Preparing NLog

You can do the following customizations to NLog:

• change existing targets
• add new targets
• add NLog extensions

Review the NLog section of the configuration file, and build the NLog custom configuration. To enable robot logs storage in Elasticsearch, you can provide the username, password, and URI as Automation Suite parameters, and the target are configured automatically. To enable custom scenarios for robot logs, you need to configure the target manually.

If NLog extensions are needed, create a folder containing all the extensions and their dependencies.

Note:

For example, the folder could be named nlogextensions. By default, Orchestrator loads the following extensions, so you do not need to include them in the folder or the NLog configuration:

NLog.Targets.ElasticSearch
UiPath.Orchestrator.Logs.Elasticsearch
Microsoft.ApplicationInsights.NLogTarget
NLog.Extensions.AzureEventHub

Create the nlog.custom.config file containing the standard sections: extensions, targets and rules.

The extensions section is an array of items that specify the extension assemblies using assemblyFile, and the path of the assembly relative to the nlogextensions folder.

Orchestrator defines NLog targets and rules that are configured or partially configured for common use cases. When customization is needed for these targets, you only need to include the modified properties in the NLog configuration. You cannot remove existing properties from the pre-defined configuration; you can, however, change them. In the Orchestrator pod, the default included targets are defined at the /opt/app-root/app/nlog.config.json location.

Note:

Example: nlog.custom.config file that writes logs to Azure Blob:

{
  "NLog": {
    "autoReload": false,
    "throwConfigExceptions": false,
    "internalLogLevel": "Warn",
    "internalLogToConsole": true,
    "default-wrapper": {
      "type": "UiPrettyExceptionWrapper"
    },
    "extensions": [
      { "assembly": "UiPath.Orchestrator.Logs.DatabaseBulk.NLogTarget" }
    ],
    "targets": {
      "robotElasticBuffer": {
        "type": "BufferingWrapper",
        "flushTimeout": 5000,
        "target": {
          "type": "ElasticSearch",
          "name": "robotElastic",
          "requireAuth": false,
          "uri": "",
          "username": "",
          "password": "",
          "index": "${event-properties:item=indexName}-${date:format=yyyy.MM}",
          "documentType": "logEvent",
          "includeAllProperties": true,
          "layout": "${message}",
          "excludedProperties": "agentSessionId,tenantId,indexName"
        }
      },
      "serverElasticBuffer": {
        "type": "BufferingWrapper",
        "flushTimeout": 5000,
        "target": {
          "type": "ElasticSearch",
          "name": "serverElastic",
          "requireAuth": false,
          "uri": "",
          "username": "",
          "password": "",
          "index": "serverdiagnostics-${date:format=yyyy.MM}",
          "documentType": "logEvent",
          "includeAllProperties": true,
          "layout": "${machinename} ${message}"
        }
      },
      "database": {
        "type": "AsyncWrapper",
        "overflowAction": "Block",
        "queueLimit": 100,
        "fullBatchSizeWriteLimit": 2,
        "batchSize": 60,
        "timeToSleepBetweenBatches": 1,
        "optimizeBufferReuse": true,
        "target": {
          "type": "DatabaseBulk",
          "connectionString": "${ui-connection-strings:item=Default}",
          "tableName": "[dbo].[Logs]",
          "batchSize": "20",
          "parameters": [
            {
              "dbType": "BigInt",
              "name": "OrganizationUnitId",
              "propertyItem": "organizationUnitId"
            },
            {
              "dbType": "Int",
              "name": "TenantId",
              "propertyItem": "tenantId"
            },
            {
              "dbType": "DateTime",
              "name": "TimeStamp",
              "layout": "${date:format=yyyy-MM-dd HH\\:mm\\:ss.fff}"
            },
            {
              "dbType": "Int",
              "name": "Level",
              "propertyItem": "levelOrdinal"
            },
            {
              "dbType": "NVarChar",
              "name": "WindowsIdentity",
              "propertyItem": "windowsIdentity"
            },
            {
              "dbType": "NVarChar",
              "name": "ProcessName",
              "propertyItem": "processName"
            },
            {
              "dbType": "UniqueIdentifier",
              "name": "JobKey",
              "propertyItem": "jobId"
            },
            {
              "dbType": "NVarChar",
              "name": "Message"
            },
            {
              "dbType": "NVarChar",
              "name": "RawMessage",
              "propertyItem": "rawMessage"
            },
            {
              "dbType": "NVarChar",
              "name": "RobotName",
              "propertyItem": "robotName"
            },
            {
              "dbType": "BigInt",
              "name": "MachineId",
              "propertyItem": "machineId"
            },
            {
              "dbType": "UniqueIdentifier",
              "name": "UserKey",
              "propertyItem": "userKey"
            },
            {
              "dbType": "NVarChar",
              "name": "HostMachineName",
              "propertyItem": "machineName"
            }
          ]
        }
      },
      "monitoring": {
        "type": "AsyncWrapper",
        "overflowAction": "Block",
        "queueLimit": 100,
        "fullBatchSizeWriteLimit": 2,
        "batchSize": 60,
        "optimizeBufferReuse": true,
        "target": {
          "type": "DatabaseBulk",
          "connectionString": "${ui-connection-strings:item=Default}",
          "tableName": "[stats].[ErrorLogs]",
          "batchSize": "20",
          "parameters": [
            {
              "dbType": "BigInt",
              "name": "OrganizationUnitId",
              "propertyItem": "organizationUnitId"
            },
            {
              "dbType": "BigInt",
              "name": "TenantId",
              "propertyItem": "tenantId"
            },
            {
              "dbType": "DateTime",
              "name": "TimeStamp",
              "layout": "${date:format=yyyy-MM-dd HH\\:mm\\:ss.fff}"
            },
            {
              "dbType": "UniqueIdentifier",
              "name": "CorrelationId",
              "propertyItem": "Correlation"
            },
            {
              "dbType": "Int",
              "name": "Source",
              "propertyItem": "logSource"
            },
            {
              "dbType": "Int",
              "name": "Level",
              "propertyItem": "levelOrdinal"
            },
            {
              "dbType": "BigInt",
              "name": "RobotId",
              "propertyItem": "robotId"
            },
            {
              "dbType": "NVarChar",
              "name": "ProcessName",
              "propertyItem": "processName"
            },
            {
              "dbType": "UniqueIdentifier",
              "name": "JobKey",
              "propertyItem": "jobId"
            },
            {
              "dbType": "BigInt",
              "name": "QueueDefinitionId",
              "propertyItem": "queueId"
            },
            {
              "dbType": "NVarChar",
              "name": "Message"
            }
          ]
        }
      },
      "insightsRobotLogs": {
        "type": "AsyncWrapper",
        "overflowAction": "Block",
        "queueLimit": 100,
        "fullBatchSizeWriteLimit": 2,
        "batchSize": 60,
        "optimizeBufferReuse": true,
        "target": {
          "type": "DatabaseBulk",
          "connectionString": "${ui-connection-strings:item=Insights}",
          "tableName": "[dbo].[RobotLogs]",
          "batchSize": "20",
          "parameters": [
            {
              "dbType": "BigInt",
              "name": "OrganizationUnitId",
              "propertyItem": "organizationUnitId"
            },
            {
              "dbType": "Int",
              "name": "TenantId",
              "propertyItem": "tenantId"
            },
            {
              "dbType": "DateTime",
              "name": "TimeStamp",
              "layout": "${date:format=yyyy-MM-dd HH\\:mm\\:ss.fff}"
            },
            {
              "dbType": "NVarChar",
              "name": "WindowsIdentity",
              "propertyItem": "windowsIdentity"
            },
            {
              "dbType": "NVarChar",
              "name": "ProcessName",
              "propertyItem": "processName"
            },
            {
              "dbType": "UniqueIdentifier",
              "name": "JobKey",
              "propertyItem": "jobId"
            },
            {
              "dbType": "NVarChar",
              "name": "RawMessage",
              "propertyItem": "rawMessage"
            },
            {
              "dbType": "NVarChar",
              "name": "RobotName",
              "propertyItem": "robotName"
            },
            {
              "dbType": "BigInt",
              "name": "MachineId",
              "propertyItem": "machineId"
            },
            {
              "dbType": "NVarChar",
              "name": "Message"
            },
            {
              "dbType": "Int",
              "name": "LevelOrdinal",
              "propertyItem": "levelOrdinal"
            },
            {
              "dbType": "Int",
              "name": "NumCustomFields",
              "layout": "${ui-robot-logs-num-custom-fields}"
            }
          ]
        }
      },
      "stdout": {
        "type": "Console",
        "layout": {
          "type": "JsonLayout",
          "includeAllProperties": true,
          "Attributes": [
            {
              "name": "ts",
              "layout": "${longdate}"
            },
            {
              "name": "traceId",
              "layout": "${aspnet-TraceIdentifier}"
            },
            {
              "name": "level",
              "layout": "${level:upperCase=true}"
            },
            {
              "name": "logger",
              "layout": "${logger}"
            },
            {
              "name": "message",
              "layout": "${message}"
            },
            {
              "name": "exception",
              "layout": "${onexception:${ui-pretty-exception}}"
            }
          ]
        }
      }
    },
    "rules": {
      "10_Robot_Insights": {
        "logger": "Robot.*",
        "ruleName": "insightsRobotLogsRule",
        "minLevel": "Info",
        "writeTo": "insightsRobotLogs",
        "enabled": false,
        "final": false,
        "filters": {
          "defaultAction": "Ignore",
          "when": {
            "condition": "level >= LogLevel.Error or ends-with('${message}',' execution ended')",
            "action": "Log"
          }
        }
      },
      "20_Robot_Primary": {
        "logger": "Robot.*",
        "ruleName": "primaryRobotLogsTarget",
        "writeTo": "database",
        "minLevel": "Trace",
        "maxLevel": "Fatal",
        "final": true
      },
      "30_Business_Exceptions": {
        "logger": "BusinessException.*",
        "minLevel": "Info",
        "writeTo": "",
        "enabled": true,
        "final": true
      },
      "40_Monitoring": {
        "logger": "Monitoring.*",
        "minLevel": "Warn",
        "maxLevel": "Fatal",
        "writeTo": "monitoring",
        "final": true
      },
      "70_Final": {
        "logger": "*",
        "minLevel": "Info",
        "maxLevel": "Fatal",
        "writeTo": "stdout",
        "final": false
      }
    }
  }
}

Note:

The extensions folder nlogextensions is copied in the object store in the well known plugins location. The Orchestrator Configurator Tool can automatically do that while also updating the NLog configuration. The script automatically changes nlog.custom.config to prefix each assemblyFile from the extensions array with /var/orchestrator/plugins/nlog/ if not already prefixed.

Preparing credential stores

You can migrate custom plugins for credentials stores to Automation Suite. To do that, update the configuration in the config map, and copy the plugins assemblies to the corresponding object store bucket.

Note:

• The plugins must work on Linux.
• The plugins must not write to any storage, apart from /tmp.

The following credential stores plugins automatically are deployed to Orchestrator in Automation Suite:

• UiPath.Orchestrator.AzureKeyVault.SecureStore.dll
• UiPath.Orchestrator.SecureStore.CyberArkCCP.dll

Note:

Automation Suite does not support CyberArk AIM, so you cannot migrate it. We recommend migrating to the CyberArkCCP credential store.

If you use any other Credential Stores plugins, copy them in a folder, such as securestoreplugins.

Add the Credential Store settings in the appsettings.json file as follows:

• to disable default plugins, add the config Plugins.SecureStores.Default with an empty string value in appsettings.json;
• add all custom plugins to the Plugins.SecureStores setting, separated by ; in appsettings.json;
• add any custom plugin settings as follows: Plugins.SecureStores.<<FriendlyName>>.<<SettingName>>.

Note:

The securestoreplugins plugin folder is copied in the object store in the well known plugins location.

The assemblies in Plugins.SecureStores are loaded from this folder.

The assemblies from Plugins.SecureStore.Default are loaded from the plugins folder in the Orchestrator app folder.

Preparing the encryption key

By default, at installation time, Orchestrator generates an encryption key to be used for the sensitive information in the database. You must migrate this key if you want to reuse a database on a new Orchestrator deployment.

To retrieve the encryption key, take the following steps:

1. Decrypt the secureAppSettings section of the UiPath.Orchestrator.dll.config file, if needed. For details, see Encrypting UiPath.Orchestrator.dll.config Sections.
2. Retrieve the encryption key from UiPath.Orchestrator.dll.config. For details, see EncryptionKey.

Preparing encryption key per tenant

The encryption key certificate is installed in the Windows certificate store. You must provide the certificate to the Automation Suite environment so that it becomes available to the Orchestrator pods.

The CertificatesStoreLocation and Azure.KeyVault.CertificateThumbprint settings are no longer required in Automation Suite, but you can use the CertificatePassword if needed.

Take the following steps:

1. Review the appSettings and obtain the AzureKeyVault.* settings.
2. Store the Azure.KeyVault.VaultAddress, Azure.KeyVault.ClientId, and Azure.KeyVault.DirectoryId for later use.
3. Retrieve the certificate, and if necessary, the certificate password.