Manual: Online upgrade

Preparation

Important:

Perform the following steps on the first server node and then on all the other nodes (both server and agent) in the cluster.

Make sure you have 10GiB of free space in the /opt/UiPathAutomationSuite folder on all the nodes. If you do not have enough space, you can either increase the capacity of this folder or remove all the previous installer files except for cluster_config.json. You can always download the previous installer again.

To verify available space, run the following command: df -h /opt/UiPathAutomationSuite.

To prepare for the upgrade, take the following steps:

1. Log into any server machine using SSH. In the case of single-node evaluation profile, where you have only one server node, log into that node.
2. Become root user:

   sudo su -

3. Create an installation folder under the /opt/UiPathAutomationSuite directory:

   # Please replace {version} with installer version
   mkdir -p /opt/UiPathAutomationSuite/{version}/installer

4. Download as-installer.zip and copy it to /opt/UiPathAutomationSuite/{version}/installer. For download instructions, see sf-installer.zip.

   cp /path/to/as-installer.zip /opt/UiPathAutomationSuite/{version}/installer

5. Unzip as-installer.zip:

   cd /opt/UiPathAutomationSuite/{version}/installer
   unzip as-installer.zip -d .

6. Provide permission to the installer:

   chmod 755 -R /opt/UiPathAutomationSuite/{version}/installer

7. Generate the latest cluster_config.json file on the first server node and copy it to the rest of the nodes.
   Note: For details on how to configure the cluster_config.json parameters, see Advanced installation experience.

   • If you have the old cluster_config.json, generate the configuration file from the cluster:

     cd /opt/UiPathAutomationSuite/{version}/installer
     
     ./configureUiPathAS.sh config get -i /path/to/old/cluster_config.json -o ./cluster_config.json

   • If you do not have the old cluster_config.json file, generate any override of any default values, which you may have done at the time of previous version installation:

     cd /opt/UiPathAutomationSuite/{version}/installer
     
     ./configureUiPathAS.sh config get -o ./cluster_config.json

   • If you upgrade from Automation Suite 2022.10 to Automation Suite 2023.4 or later, and Orchestrator is enabled on both the old and new versions, you must set the orchestrator.block_classic_executions flag to true in the cluster_config.json file. Using the flag shows that you agree with blocking classic folders executions. Not using the flag causes the upgrade operation to fail. For a configuration example, see Orchestrator-specific configuration.
   • If you are using AI Center^TM connected to an external Orchestrator, make sure that you have the Orchestrator certificate in the cluster_config.json file. If you upgrade from a version older than 2022.10, copy the Orchestrator certificate to the virtual machine. After you copy the certificate, the following configuration details are needed in cluster_config.json:

     "aicenter": {
         "enabled": true,
         "orchestrator_url": "https://orchestrator.example.com", //Specify the Orchestrator URL for AI Center
         "identity_server_url": "https://orchestrator.example.com/identity", //Specify the Identiy URL for AI Center
         "orchestrator_cert_file_path": "/opt/UiPathAutomationSuite/UiPath_Installer/orch.cer", //Specify the path to the Orchestrator certificate
         "identity_cert_file_path": "/opt/UiPathAutomationSuite/UiPath_Installer/orch.cer", //Specify the path to Identity certificate file
         "metering_api_key": "test" //Specify the metering API key
       }

     Note: If AI Center requires an external Orchestrator, add sql_connection_string_template and sql_connection_string_template_odbc in the cluster_config.json file.

     After upgrading to AI Center 2023.4 and moving to external storage, making a skill created in 2022.4 public will fail. To fix this, run the script from here.

   • If you upgrade Automation Suite from a previous version and now enable Process Mining as well, you must update the sql_connection_string_template_sqlalchemy_pyodbc. Below is an example.

     "sql_connection_string_template_sqlalchemy_pyodbc": "mssql+pyodbc://[e-mail]:[e-mail]:1433/DB_NAME_PLACEHOLDER?driver=ODBC+Driver+17+for+SQL+Server"

   • If you upgrade Automation Suite from a version previous to 2023.4 and you have Apps enabled, you must create the SQL database for Apps, and then update the cluster_config.json file with the following configuration:

     "apps": {
     "enabled": "true" // This will already be true in existing cluster_config.json if apps is enabled
     "sql_connection_str": "" // Provide ODBC database connection string if apps is enabled
     }

     Note:

     Use the updated cluster_config.json file in the next upgrading steps.

   See also Manual: Advanced installation experience.

8. (Optional) If you still use a self-signed certificate generated by the installer, run the following command. This step is required on the first server node, where you will perform the upgrade of UiPath products.

   ### Please replace /path/to/cert with path to location where you want to store certificates.
   ./configureUiPathAS.sh tls-cert get --outpath /path/to/cert
   
   ### Now copy the ca.crt file generated in above location to trust store location
   sudo cp --remove-destination /part/to/cert/ca.crt /etc/pki/ca-trust/source/anchors/
   
   ### Update the trust store
   sudo update-ca-trust

Execution

Important: If any errors or issues occur during or following the upgrade, you can rollback to the previous version, provided that you previously configured a backup. For instructions, see Rollback on error.

Configuring the backup

To configure the backup, take the following steps:

1. Make sure you have enabled the backup on the cluster. You must create the backup using the same version of the installer as the one you used for the current deployment. For instructions, see the backup and restore documentation corresponding to the Automation Suite version from which you plan to upgrade. For instance, if you plan to upgrade from Automation Suite 2021.10, follow the instructions in the 2021.10 guide.
2. Connect to one of the server nodes via SSH.
3. To verify that all desired volumes have backups in the cluster, run:

   /path/to/old-installer/configureUiPathAS.sh verify-volumes-backup

   Note: The backup might take some time, so wait for approximately 15-20 minutes, and then verify the volumes backup again.

Once the backup is created, continue with the following steps.

Putting the cluster in maintenance mode

Putting the cluster in maintenance mode will shut down the ingress controller and all the UiPath services, blocking all the incoming traffic to the Automation Suite cluster.

Important: This operation will cause downtime, and your business automation will be suspended during the entire upgrade process.

1. To put the cluster in maintenance mode, run:

   cd /opt/UiPathAutomationSuite/{version}/installer
   ./configureUiPathAS.sh enable-maintenance-mode

2. To verify that the cluster is in maintenance mode, run:

   ./configureUiPathAS.sh is-maintenance-enabled

   Important: Create a backup of your SQL Server after enabling maintenance mode so that no further transactions are recorded in your SQL database.

Updating Kubernetes and other infrastructure components

Important:

You must perform the infrastructure upgrade on all the nodes in the cluster.

You cannot perform this step on multiple nodes at the same time; you must wait for the upgrade to finish on each node before moving to another.

1. Log into each node where you want to perform the infrastructure upgrade.
2. Become root by running sudo su -.
3. Make sure rke service is enabled on server and agent nodes.

   If the service is disabled, enable it by running the following command:

   • For a server node:

     [[ $(systemctl is-enabled rke2-server.service) != "enabled" ]] && systemctl enable rke2-server.service

   • For an agent node:

     [[ $(systemctl is-enabled rke2-agent.service) != "enabled" ]] && systemctl enable rke2-agent.service

4. To start the upgrade, run the following command:
   Important: Make sure you have updated cluster_config.json generated as described in the Preparation steps.

   # replace {version} with the version you are upgrading to
   cd /opt/UiPathAutomationSuite/{version}/installer
   
   ./install-uipath.sh --upgrade -k -i ./cluster_config.json -o ./output.json --accept-license-agreement

   Important:

   If you get the following error, follow the instructions in Downgrading Ceph from 16.2.6 to 15.2.9.

   Ceph cluster is running on version: 16.2.6 with known bug(https://docs.ceph.com/en/quincy/releases/pacific/#v16-2-6-pacific). Please provide temporary backup directory (via environment variable 'TMP_CEPH_BACKUP_PATH') to downgrade ceph

Updating shared components and UiPath product services

Important: If you previously deployed your single-node installation using any Azure template version prior to 2022.10.3, and you now want to upgrade to a newer Automation Suite version, you must set the zone_resilience flag to false in the cluster_config.json file in /opt/UiPathAutomationSuite/Installer.

This step upgrades the fabric and service components running with the cluster. You must follow this steps only once from any of the server nodes.

1. Connect to any server node.
2. Become root by running sudo su -.
3. Run the following command:

   # replace {version} with the version you are upgrading to
   cd /opt/UiPathAutomationSuite/{version}/installer
   
   ./install-uipath.sh --upgrade -f -s -i ./cluster_config.json --accept-license-agreement -o ./output.json

   Important:

   Once the upgrade is done, maintenance mode will be disabled automatically.

   After manually upgrading from Automation Suite 2021.10, you must also migrate to Cilium CNI. For instructions, see Migrating from Canal to Cilium CNI.

After performing the upgrade, you can take the following additional steps:

• To verify if Automation Suite is healthy, run:

  kubectl get applications -n argocd

• When upgrading from an Automation Suite version prior to 2023.4.0, verify if Apps is running, then remove MongoDB:

  ./configureUiPathAS.sh mongodb uninstall --force

• If you face an error when removing MongoDB with ./configureUiPathAS.sh mongodb uninstall --force command, run the following command:

  kubectl patch application "fabric-installer" -n argocd --type=merge -p '{"spec" : {"syncPolicy" : {"automated" : {"selfHeal": false }}}}'
  
  ./configureUiPathAS.sh mongodb uninstall --force
  
  kubectl patch application "fabric-installer" -n argocd --type=merge -p '{"spec" : {"syncPolicy" : {"automated" : {"selfHeal": true }}}}'

• If you experience issues with image vulnerabilities or storage consumption after performing an upgrade, delete the images from the old installer. For details, see the Troubleshooting section.

Enabling the backup post-upgrade

You must resume the backup after upgrading and performing the cleanup and migration operations.

Important:

Make sure Automation Suite is up and running and your automation continues as expected before proceeding with the following steps.

To enable the backup, follow the instructions in described in the Backing up and restoring the cluster documentation.

Completing an upgrade with a deployment template

After performing an Automation Suite cluster upgrade, Azure and AWS template deployments require some changes to ensure a new node joins the cluster correctly through scale-out operations. To automate the changes, we recommend using the dedicated scripts. For instructions, see the Azure deployment template docs and the AWS deployment template docs.

Special considerations

When performing an upgrade for a cluster deployed with Azure templates, an error similar to the one shown in the following image might occur:

This is due to the way the Azure load balancer works. To fix the issue, modify the fixed_rke_address field in the cluster_config.json file. You must change the value of this field to the IP address of the first server instance prior to running the upgrade command. The cluster_config.json uploaded to the key vault should continue to have the IP address of the ILB since the node is not healthy, and traffic will not be balanced to it.