Post-migration steps

Post-migration steps are mandatory and include:

Step 1: Updating secrets and Identity Server configuration

Updating Identity Application Secrets With Previously Saved Identity Configuration Data

Take the following steps:

1. Run kubectl edit secret platform-service-secrets -n uipath and update identity.sqlConnectionString, identity.hostAdminUsername, and identity.hostAdminPassword using base64 encoded values.
2. Use the instructions provided in Updating the Identity token signing certificate.
3. If using SAML, run kubectl edit secret identity-saml-certificates -n uipath and update current.saml2.pfx and future.saml2.pfx via the decrypted private keys, and currentCertPassword and futureCertPassword via base64 encoded values.
4. If using Kerberos, run kubectl edit secret krb5-keytab -n uipath and update the krb5.keytab value.

Remove old Identity cache keys

Take the following steps:

1. Run kubectl --kubeconfig <directory of SF cluster yaml file> get secrets/redb-redis-cluster-db -n uipath --template '{{ .data.password }}' to get Redis password. Decode the Base64 value.
2. Run kubectl --kubeconfig <directory of SF cluster yaml file> get secrets/redb-redis-cluster-db -n uipath --template '{{ .data.port }}' to get Redis port. Decode the Base64 value.
3. Run kubectl  --kubeconfig <directory of SF cluster yaml file>  exec -i -t -n redis-system redis-cluster-0 -c redis-enterprise-node "--" sh -c "clear; (bash || ash || sh)" to get into Redis node.
4. Use port and password got from previous commands to run redis-cli -p <Port number> -a <Password> --scan --pattern is:* | xargs redis-cli -p <Port number> -a <Password> del to delete the old keys.
5. Run exit to get out.

Running Identity Server DataMigrator CLI

Run Identity Server DataMigration from a domain-joined machine using the following parameters. You can find the migrator executable inside the Orchestrator installation folder, e.g., C:\Program Files (x86)\UiPath\Orchestrator\Identity\Tools\DataMigrator.Cli

• .\UiPath.DataMigrator.Cli.exe kube-migrate -d <identity.sqlConnectionString for the k8s env>

  Restart identity-service-api after running the migrator command.

Step 2: Linking tenants from a standalone installation to Automation Suite

For Linux

Prerequisites

The MSIToAutomationSuiteTenantMigrator tool requires .NET 6.0 at a minimum. If .NET 6.0 or later is not present, download and install .NET Runtime for Linux before using the MSIToAutomationSuiteTenantMigrator tool.

To install .NET Runtime 3.1 on RHEL, run the following command: sudo yum install dotnet-sdk-6.0 -y

Downloading the tool

The MSIToAutomationSuiteTenantMigrator tool is available for download here.

Running the tool

Note: Make sure to follow the general escape instructions for different Shell types. In Bash, add \ before special characters.

To link tenants from a standalone installation to Automation Suite, run:

./MSIToAutomationSuiteTenantMigrator -s '<Orchestrator DB connection string (the one cloned from the standalone installation server)>' -p '<Platform DB connection string (Automation Suite)>' -t '<List of tenant names separated by comma, e.g. orchTenant1,orchTenant2>'

For Windows

Prerequisites

The MSIToAutomationSuiteTenantMigrator tool requires .NET 6.0 at a minimum. If .NET 6.0 and beyond is not present, download and install .NET Runtime 6.0.3 for Windows before using the MSIToAutomationSuiteTenantMigrator tool.

Downloading the tool

The MSIToAutomationSuiteTenantMigrator tool is available for download here.

Running the tool

Note: To successfully run the MSIToAutomationSuiteTenantMigrator tool, you must escape your SQL password if it contains special characters. To do that, make sure to replace every instance of $ with `$.

To link tenants from a standalone installation to Automation Suite, run:

MSIToAutomationSuiteTenantMigrator.exe -s "<Orchestrator DB connection string (the one cloned from the standalone installation server)>" -p "<Platform DB connection string (Automation Suite)>" -t "<List of tenant names separated by comma, e.g. orchTenant1,orchTenant2>"

Updating SMTP Configuration Information

Configure SMTP for the host and (optionally) for any organizations where you want to use different SMTP settings than the host.

Note: You can no longer use default credentials, so you must provide a username and password for the sender email account and you also need a valid TLS certificate, otherwise the SMTP connection does not work when you try to test the connection.

Step 3: Updating AD Integration and Authentication

To configure AD integration, refer to Configuring SSO: Active Directory.

If AD integration and authentication were enabled in the standalone deployment, take the following steps in the Automation Suite cluster:

• Make sure the domain controllers are discoverable by the Automation Suite cluster. If not, use the Kube DNS configuration;
• Configure integrated Windows authentication and Kerberos authentication using keytab file;
• Configure LDAP integration via the Portal under the host admin;
• Configure Windows authentication via the Portal under the host admin;

• Configure LDAPS for secure connection to LDAP.

  Note: The account used for the LDAP integration configuration should only have read access to all trusted domains in the current and trusted forests.

Step 4: Updating the Orchestrator Configuration

Update the Orchestrator configuration. Make sure to review the following:

• Custom configuration from UiPath.Orchestrator.dll.config
• Any web.config settings.
• Storage (packages, execution media, and buckets data) - mostly applicable to Storage.Type=FileSystem
• Custom NLog targets.
• Custom credential stores.
• Encryption key per tenant configuration.

You can simplify many of the following steps by using the provided Orchestrator Configurator Tool.

The orchestrator_configurator.sh bash tool can update the Orchestrator custom config map and upload files to the Orchestrator well-known blob storage locations. Use the -y parameter to skip confirmation of the proposed actions.

Configuring web.config

Edit the orchestrator-customconfig config map using a tool such as Lens or kubectl.

Configure the request limit in the values.json file. The Orchestrator deployment should restart automatically after this configuration change.

{
  "Kestrel": {
    "Limits": {
      "MaxRequestBodySize": 314572800
    }
  }

Configuring appSettings

The appSettings.custom.json file edited in the pre-migration steps now contains all the customization needed in the appSettings section. You need to place this .json file in the orchestrator-customconfig config map, in the values.json file, under the appSettings key.

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

The Orchestrator Configurator Tool can merge the keys in the custom appSettings with the keys already present in the config map. You can upload the app settings using the -c|--app-settings parameter:

./orchestrator-configurator.sh -c appSettings.custom.json

If using the configurator tool, go through all the steps to gather all required appSettings overrides, and run the script once at the end.

Configuring Storage

If you are using local FileStore, and you need to upload existing storage contents to Orchestrator, make sure to place them in any Orchestrator pod at the /var/orchestator/data path.

The Orchestrator Configurator can upload the files with kubectl cp, using the -s|--storage-folder parameter:

./orchestrator-configurator.sh -s blobstoragefolder

The script ensures that the content of the storage folder becomes the content of the /var/orchestrator/data folder.

To use network FileStore, edit the Orchestrator ArgoCD app parameters, and set the following:

• storage.type = smb
• storage.smb.domain
• storage.smb.password
• storage.smb.source
• storage.smb.username
• storage.smb.size

To configure other storage options, edit the Orchestrator ArgoCD app parameters and set the following:

• storage.type to the desired provider (Azure, AWS, Minio)
• storage.connectionString

Overview of the Orchestrator app storage settings:

Azure/Amazon S3 Storage Buckets

Orchestrator web browser access to Amazon and Azure storage buckets can be restricted due to the same-origin policy on the provider side. Successfully accessing the content of such a bucket requires you to configure the respective provider to allow cross-origin requests from Orchestrator.

See instructions on how to configure each provider to allow cross-origin requests from Orchestrator.

Configuring NLog

To install NLog extensions, they need to be copied in Ceph, in the uipath bucket. The Orchestrator pod will then be able to load them at startup. You also need to place the configuration in orchestrator-customconfig in the nlog.json file.

The configurator can do this with the -n|--nlog-extensions-folder and -l|--nlog-config-file parameters.

./orchestrator-configurator.sh -n nlogextensions -l nlog.custom.json

The plugins will be available in the Orchestrator pod at the local path /var/orchestrator/plugins/nlog. The configurator automatically updates the assemblyFile paths, prepending the plugins path to them.

Configuring credential stores

Credential stores configuration changes are included in appsettings.custom.json, so there are no more required configuration updates.

To make the changes manually, place them in the values.json file of orchestrator-customconfig under the appSettings section.

If secure stores assemblies are also required, then you must place them in any Orchestrator pod at the /var/orchestrator/plugins/securestore/ path.

The Orchestrator Configurator Tool can do that using the -p|--securestore-plugins-folder parameter:

./orchestrator-configurator.sh -p securestoreplugins

Configuring encryption key

To configure the EncryptionKey, replace it in the Kubernetes secret orchestrator-generated-secrets by overwriting the value of APPSETTINGS__EncryptionKey.

Configuring encryption key per tenant

To migrate the encryption key per tenant, take the following steps:

1. Add the AzureKeyVault settings and the certificate in the ArgoCD UI, as parameter overrides for the Orchestrator application.
   • encryptionKeyPerTenant.certificateBase64
   • encryptionKeyPerTenant.certificatePassword
   • encryptionKeyPerTenant.clientId
   • encryptionKeyPerTenant.directoryId
   • encryptionKeyPerTenant.vaultAddress
   1. Use the values from the following configuration keys (referenced in the preparation steps):
      • Azure.KeyVault.VaultAddress
      • Azure.KeyVault.ClientId

      • Azure.KeyVault.DirectoryId

   2. Convert the certificate to base64 and use it as a parameter override. To convert it, use the following command:

      PowerShell:

      [convert]::ToBase64String((Get-Content -path "path_to_certificate" -Encoding byte))

      Shell:

      base64 [_path_to_certificate_]

2. Apply the Orchestrator ArgoCD app parameter overrides, and then run the Orchestrator Configurator Tool.
3. Once the new configuration is reflected in ArgoCD, wait until the application is synced again.
4. Enable the EncryptionKeyPerTenant feature as follows:
   • use the two settings placed in appSettings.custom.json and run the Orchestrator Configurator Tool;
   • or manually in the orchestrator-customconfig, in the appConfig section of the values.json file.

   "EncryptionKeyPerTenant.Enabled": "true", "EncryptionKeyPerTenant.KeyProvider": "AzureKeyVault",

5. Restart the Orchestrator Automation Suite deployment from the cluster for the changes to take effect.
   Note: SMTP settings in Identity Server are not encrypted with the per-tenant key. Once the migration is complete, make sure to re-enter the SMTP password in the Automation Suite portal.

Step 5: Recreating cluster_config.json

To complete the migration, you must recreate the cluster_config.json file. This ensures all changes made via ArgoCD are properly saved in the Automation Suite configuration file.

To recreate cluster_config.json, run the following command:

./configureUiPathAS.sh config get -i /path/to/old/cluster_config.json -o ./cluster_config.json

As part of this step, you must also manually set create_db to false. Not doing so would prevent the installer from overriding SQL connection strings and retaining the latest state of the cluster.

Important:

Do not configure Kerberos authentication via cluster_config.json at this stage. The operation requires running the installer, which reverts the changes made to the SQL connection strings.

For details on the alternative options to configure Kerberos authentication, see Configuring Automation Suite as a Kerberos client.

Step 6: Reconnecting Robots

Reconnect the robots to Orchestrator in the Automation Suite.