Pre-migration steps

To ensure you successfully migrate a standalone platform installation to Automation Suite, make sure to take the steps described in the following sections. The pre-migration steps are mandatory.

Step 1: Saving the Identity Server configuration data

Make sure to save the following Identity Server configuration data:

Host administrator username and password

Save the host administrator username and password.

Token signing certificates

Identity Server uses .pfx certificates to sign OAuth tokens. If you use your own tokens in the standalone deployment, you need to convert them to .pfx and update them in the Automation Suite cluster’s corresponding secret(s).

Note: You can also take this step during the initial cluster setup if you decide to use the same signing certificates in the Automation Suite deployment: kubectl edit secret identity-token-signing-certificate -n uipath.

SAML certificates

SAML identity provider configuration uses certificates store(s) to read client and server certificates. You need to update any certificate previously used in the standalone deployment in the Automation Suite cluster’s corresponding secret(s): kubectl edit secret identity-saml-certificates -n uipath.

Identity Server application settings

Save the following Identity Server application settings:

• DatabaseProtectionSettings from appsetting.production.json in /identity folder of the standalone deployment.
• DatabaseProtectionSettings.EncryptionKey2021 setting is used to encrypt sensitive data at rest. You must replicate this value in the Automation Suite deployment in the post-migration phase: kubectl edit secret identity-generated-secrets -n uipath.

Export certificates

If you are using Azure Key Vault or Windows Certificate Store, export the certificates to .pfx format.

Step 2: Creating organization-tenant pairs

For each tenant from the standalone deployment, create an organization-tenant pair in the Automation Suite environment.

Example: If in standalone Orchestrator you have a tenant named Tenant1, in Automation Suite, you need to create an organization Tenant1 and a tenant within that organization also named Tenant1. Once you create the tenant, make sure the Orchestrator service is enabled for that tenant.

Note: A tenant ‘Default’ is automatically created for each organization. You do not have to delete it, but you need to add another tenant named exactly like your organization. E.g., in the previous example, when creating an organization Tenant1, you end up also having a tenant named Default in that organization. The final step for you is to add another tenant called Tenant1 to that organization. You can then move on to creating the next organization-tenant pair.

Step 3: Saving the connection strings and tenant names

Save the following information for further usage:

• The connection string to the Orchestrator database in the standalone deployment;
• The connection string to the AutomationSuite_Platform database in the Automation Suite deployment;
• The tenant name(s) from the standalone deployment; you can look it up in the Orchestrator UI or using the TenancyName column in Orchestrator’s tenant table;
• Insights connection string.

Step 4: Preparing Orchestrator

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.custom.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 S3 utility such as s3cmd, 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.custom.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": {
        "extensions": [
            { "assemblyFile": "NLog.Extensions.AzureBlobStorage.dll" }
        ],
        "targets": {
            "azureBlob": {
                "type": "AzureBlobStorage",
                "connectionString": "DefaultEndpointsProtocol=https;AccountName=test;AccountKey=key;EndpointSuffix=core.windows.net",
                "container": "orchestratorlogs",
                "blobName": "${date:format=yyyy-MM-dd hh.mm}",
                "layout": {
                  "type": "JsonLayout",
                  "includeAllProperties": true,
                  "Attributes": [
                    {"name": "ts","layout": "${longdate}"},
                    {"name": "level","layout": "${level:upperCase=true}"},
                    {"name": "logger","layout": "${logger}"},
                    {"name": "message","layout": "${message}"},
                    {"name": "exception","layout": "${onexception:${ui-pretty-exception}}"}
                  ]
                }
            }
        },
        "rules": { "70_Final": { "writeTo": "stdout,azureBlob" } }
    }
}

Note: To overwrite robot logs target, replace 70_final with 20_robot_primary in the above example .

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.custom.json file as follows:

• to disable default plugins, add the config Plugins.SecureStores.Default with an empty string value in appSettings.custom.json;
• add all custom plugins to the Plugins.SecureStores setting, separated by ; in appSettings.custom.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.

From the secureAppSettings section of the configuration, retrieve the value of EncryptionKey and store it safely for later use.

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.