Executing the upgrade

Execute an Automation Suite cluster upgrade, including maintenance mode, backup steps, and upgrade process.

Important:

To perform an Automation Suite upgrade, you must put the cluster in maintenance mode. Maintenance mode causes downtime during the entire upgrade process, and your business automation is suspended during this time. It is strongly recommended to create a backup of the cluster and the SQL database before the upgrade. This is to ensure you can restore the cluster if something goes wrong during the upgrade operation.

To execute the upgrade, you must take the following steps:

1. Run the prerequisite checks.
2. Configure the backup.
3. Disable the backup.
4. Put the cluster in maintenance mode.
5. Migrate Longhorn workloads, MongoDB data, and Ceph to Helm-based deployment.
6. Update Kubernetes and other infrastructure components.
7. Upgrade the shared components and UiPath® services.

Running the prerequisite checks

You must verify that all the upgrade requirements are met before you put the cluster in maintenance mode.

1. Run the infrastructure prerequisite checks, using the following command:

   cd /opt/UiPathAutomationSuite/latest/installer
   ./bin/uipathctl rke2 prereq run cluster_config.json --versions versions/helm-charts.json
   

2. Run the shared component and services prerequisite checks, using the following command:

   cd /opt/UiPathAutomationSuite/latest/installer
   ./bin/uipathctl prereq run cluster_config.json --versions versions/helm-charts.json
   

Note:

If your current Automation Suite version uses an uppercase FQDN, the prerequisite checks will fail with a message asking you to switch to a lowercase FQDN. In this case, update the FQDN to lowercase before proceeding with the upgrade. For instructions, refer to Configuring the FQDN post-installation.

Configuring the backup

To configure the backup, take the following steps:

1. Make sure you 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 details, refer to 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 2023.4, refer to the 2023.4 guide.

2. Connect to one of the server nodes via SSH.

3. Verify that all desired volumes have backups in the cluster:

   • If you upgrade from 2022.4 or older, run the following command:

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

   • If you upgrade from 2022.10 or newer, run the following command:

     ./configureUiPathAS.sh snapshot list
     

   • If you upgrade from 2024.10 or newer, run the following command:

     ./bin/uipathctl snapshot list
     

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.

Note:

Make sure you use the uipathctl command from the target version directory when you upgrade from 23.10.0 or later versions.

Disabling the backup

Before you place the cluster in the maintenance mode, you must disable the backup to avoid backing up the cluster in a suboptimal state. For details, refer to Disabling the snapshot backup.

Putting the cluster in maintenance mode

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

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

   ./bin/uipathctl cluster maintenance enable
   

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

   ./bin/uipathctl cluster maintenance is-enabled
   

Performing pre-upgrade migration operations

Run the following mandatory pre-upgrade command:

./bin/uipathctl cluster pre-upgrade cluster_config.json --versions-dir ./versions

This command selectively migrates Longhorn workloads to local PV, MongoDB data to SQL, and migrates the Ceph deployment from ArgoCD to a Helm-based deployment.

Updating Kubernetes and other infrastructure components

To upgrade Kubernetes and the other infrastructure components, run the following command on the primary server node:

Important:

Make sure you updated the generated cluster_config.json file as described in Updating the cluster configuration.

Note:

Since Task Mining is no longer available starting with Automation Suite 2.2510.0, if you had a dedicated Task Mining node, you can remove it from the cluster by following the instructions in Removing a node from the cluster.

If you want to reuse the node in Automation Suite, you can remove the taint by running the following command:

kubectl taint nodes <nodename> task.mining/cpu=present:NoSchedule-

cd /opt/UiPathAutomationSuite/latest/installer

./bin/uipathctl rke2 upgrade cluster_config.json --versions versions/helm-charts.json

Note:

• Running the previous command on the primary server node copies the installer and cluster_config.json to the /opt/UiPathAutomationSuite/<version>/installer default location and upgrades the infrastructure on all the machines.

• The /opt/UiPathAutomationSuite/<version> default location must have at least 5 GB available across all nodes.

• To change the default location, update the following environment variable with the desired location. Make sure that the location is available on all the nodes and has the required permissions to run the upgrade.

  export INSTALLER_DIRECTORY=/path/to/copy/installer
  

• After executing the previous command and running the upgrade, the installer is copied to the /path/to/copy/installer/<version>/installer location. version is replaced with the version of the installer that you execute.

Troubleshooting

• The upgrade logs on the primary server are available in the /opt/UiPathAutomationSuite/latest/installer/upgrade-logs default location, unless you explicitly used a custom location for the installer.
• On all the other nodes, the logs are available in the /opt/UiPathAutomationSuite/<version>/installer/upgrade-logs default location, unless you explicitly changed this location via the INSTALLER_DIRECTORY variable.

Upgrading the shared components and UiPath® services

1. If you have Insights enabled, you must run the following command to ensure that the Insights data persists after the upgrade:

   kubectl -n uipath create cm migration-lock --from-literal=migration=pending --dry-run=client -o yaml | kubectl apply -f -
   

   Note:

   Running this command will not have any adverse impact if Insights is not enabled.

2. To upgrade the shared components and the UiPath® product services, run the following command on the primary server node:

   cd /opt/UiPathAutomationSuite/latest/installer
   ./bin/uipathctl manifest apply cluster_config.json --versions versions/helm-charts.json
   

   Important:

   After completing the upgrade, maintenance mode is disabled automatically.

3. To verify if Automation Suite is healthy, run one of the following commands:

   cd /opt/UiPathAutomationSuite/latest/installer
   ./bin/uipathctl health check
   

   Note:

   If you cannot find helm-charts.json, you can alternatively use versions.json. To download versions.json, refer to Downloading the installation packages.

After completing the upgrade, perform the cleanup and migration activity applicable to you.