Using uipathctl.sh

The uipathctl.sh script provides an automated way to upgrade a cluster to a newer version, configure a backup, restore a cluster, and more, by running it on one node. The automation of these tasks is done via the IT automation tool Ansible.

uipathctl.sh parameters

Parameter	Description
upgrade	Upgrade the cluster.
sso-generate-connector	Generate a sample file representing a Dex Connector for enabling SSO.
sso-generate-rbac	Generate an example ArgoCD RBAC file.
sso-generate-overlays	Generate the Kustomize overlays for the ArgoCD and Dex deployment with SSO. Useful in debugging.
sso-apply-overlays	Generate and apply the Kustomize overlays for ArgoCD and Dex with SSO.
--steps <all|bundles|infra|fabric|services>	This flag is shown only if you use the upgrade command. Steps to run during upgrade operations. Defaults to all. all – executes all steps bundles – copies required offline bundles to all nodes infra – executes infra installation on server and agent nodes fabric – executes fabric installation on a server services – executes services installation on a server
--install-type <online|offline>	Type of installation. Required for upgrade and restore.
--cluster-config	Path to your cluster_config.json file. If not specified, a configuration file is generated.
--kubeconfig	Path to a Kubeconfig file that allows connecting to the cluster. Defaults to /etc/rancher/rke2/rke2.yaml.
--inventory	Path to a valid Ansible inventory describing the cluster. If not specified, an inventory is generated.
--ansible-username	The username to be used by Ansible to connect to cluster nodes. Defaults to the current user.
--ansible-private-key	The SSH private key that provides connectivity to cluster nodes. If not specified, a set of passwords are prompted.
--ansible-ask-password	Ask Ansible to request a password set for SSH connections and elevation.
--ansible-config	Specify the path to a custom ansible.cfg to be used.
--offline-infra-bundle	Path to the as-infra.tar.gz file. Required for offline upgrades.
--disable-cni-upgrade	Do not perform CNI upgrade.
--sso-connector-type	Connector type for sso-generate-connector.
--sso-connector-file	Path to a file containing a Dex Connector for the SSO integration.
--sso-rbac-file	Path to a file containing a Dex Connector for the SSO integration.

Requirements

Ansible uses the SSH mechanism to log into any of the host nodes or machines to perform tasks.

Before running the uipathctl.sh script, you must take the following steps:

1. Identify the Ansible host node.
2. Add the SSH signature of your nodes to the known hosts.
3. Set up the SSH authentication method.
4. Install Ansible and other prerequisite tools.

You must ensure that the following tools are installed on the Ansible host node:

• ansible (v2.8+)
• ansible-playbook
• sshpass – Required only when using password for authentication along with the --ansible-ask-password parameter.
• zip

For instructions, see the following sections.

Identifying the Ansible host node

The Ansible host node is the machine where you install Ansible. This machine must be a server node so that it has the required permissions to perform all the automations in the cluster.

In online installations, the Ansible host node can be any of the server nodes.

In offline installations, the Ansible host node must be the primary server node on which you mounted the UiPath bundle disk in the /uipath location. If there is no server node with the UiPath bundle disk attached, you can simply mount an additional disk to any of the existing server nodes and consider it to be the Ansible host node.

Adding the SSH signature of your nodes to the known hosts

To add the SSH signature of your node to the known hosts, add the private IP address of each node in the cluster to the known_hosts file in the Ansible host node.

Run the following command on the Ansible host node by replacing <node-private-ip> with the private IP address of each node in the cluster, one at a time.

ssh-keyscan -H <node-private-ip> >> ~/.ssh/known_hosts

Setting up SSH authentication method

Ansible supports two SSH mechanisms:

• Option 1: Key-based SSH authentication – Recommended. It uses private and public keys.
• Option 2: Password-based SSH authentication

Option 1: Key-based SSH authentication (recommended)

Step 1: Setting up the SSH key

The SSH key authentication mechanism uses a combination of private and public keys.

Make sure you grant access to the public key of the Ansible host node on all other nodes by copying it.

If you do not have an SSH key, you can generate one by running the ssh-keygen command.

Generating SSH keys

You can generate a new SSH key using the ssh-keygen command. To generate the new SSH key, just run ssh-keygen command and follow the instructions.

To generate a new SSH key, take the following steps:

1. Generate a new SSH key using the ssh-keygen command.

2. Write down the location of your key. Default values are:

   • Public Key: ~/.ssh/id_rsa.pub
   • Private Key: ~/.ssh/id_rsa
3. Grant access to the public key of the Ansible host node on all other nodes by copying it.

Granting access to the public key on each node

To grant access to the public key, copy it to all nodes in the cluster (including current node) using the ssh-copy-id command. If the path of the SSH public key is not ~/.ssh/id_rsa.pub, make sure to replace it accordingly.

ssh-copy-id -i ~/.ssh/id_rsa.pub username@node-private-ip

Step 2: Providing SSH key access to Ansible

Ansible uses the SSH mechanism to log into host machines and perform the required installation. For this reason, you must provide the SSH key access to Ansible.

Choose between the following methods:

• Option 1: Using ssh-agent (recommended)
• Option 2: Using non-protected private key

Option 1: Using ssh-agent (recommended)

By default, Ansible uses ssh-agent to obtain access to nodes. For more information about ssh-agent, see ssh-agent manual.

To add a new key to ssh-agent, run the following command:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

Option 2: Using non-protected private key

Note: This option is supported only if your private key is not protected by a passphrase.

This method entails using the private key interactively, by adding the --ansible-private-key parameter to your the uipathctl.sh script. The parameter takes the absolute path of private key and uses it for authentication.

Option 2: Password-based SSH authentication

If you opt for password-based SSH authentication, you must provide the --ansible-ask-password parameter to uipathctl.sh script. This parameter will prompt you to provide the password for authentication.

Checking if Ansible and other prerequisite tools are installed

You must ensure that Ansible and the following other supporting tools are installed on the previously selected Ansible host node.

• ansible (v2.8+)
  To check if ansible was installed, run:

  ansible --version &>/dev/null || echo "Error: Ansible is not installed"

• ansible-playbook

  To check if ansible-playbook was installed, run:

  ansible-playbook --version &>/dev/null || echo "Error: Ansible Playbook is not installed"

• sshpass – Required only when using password for authentication along with the --ansible-ask-password parameter.
  To check if sshpass was installed, run:

  sshpass -V &>/dev/null || echo "Error: sshpass is not installed"

• zip

  To check if zip was installed, run:

  zip --version &>/dev/null || echo "Error: zip is not installed"

  Important: If any of the previous commands errors out, the targeted package is not installed on your machine. Make sure to install the required tools.

Advanced Ansible configuration

Enabling the yaml output

To achieve a visually better output, we recommend using the yaml output for Ansible by running the following command:

export ANSIBLE_STDOUT_CALLBACK=yaml

This feature was introduced in Ansible 2.9, and for certain installations, it has to be enabled by running the following command:

ansible-galaxy collection install community.general

If you still encounter the ERROR! Invalid callback for stdout specified: yaml message after installing the community.general collection, you can disable the yaml output by running the following command:

unset ANSIBLE_STDOUT_CALLBACK

Generating the Ansible inventory.ini file

In some scenarios, such as when configuring the backup or upgrading, Automation Suite automatically generates the inventory.ini file for Ansible. However, there are few situations where you must build and provide the inventory.ini file to Ansible. For example:

• While restoring the cluster from the backup data. This is because at the time of restore there is no healthy cluster to derive inventory.ini.
• When you want to provide advanced configuration such as username and SSH key, which is very specific to each node.

For more details, see How to build your own inventory.

The following code block displays the inventory template that the uipathctl.sh script understands.

[FIRST_SERVER]
'10.0.1.1'
[SECONDARY_SERVERS]
'10.0.1.2'
'10.0.1.3'
[AGENTS]
'10.0.1.4'
'10.0.1.5'
[TASKMINING]
'10.0.1.6'
[GPU]
'10.0.1.7'
[ASROBOTS]
'10.0.1.8'
[all:vars]
ansible_connection=ssh
ansible_timeout=10
ansible_user=admin

Group	Value
[FIRST_SERVER]	The starting point where you run the uipathctl.sh script. This is also called the Ansible host node. You must provide the Private IP address for this node.
[SECONDARY_SERVER]	The group of other server nodes in the cluster. You must provide the Private IP address of all the other server nodes.
[AGENTS]	The group of agent nodes in the cluster. You must provide the Private IP address of all agent nodes.
[TASKMINING]	The group of Task Mining nodes in the cluster. You must provide the Private IP address of all the Task Mining nodes.
[GPU]	The group of GPU nodes in the cluster. You must provide the Private IP address of all the GPU nodes.
[ASROBOTS]	The group of Automation Suite Robots nodes in the cluster. You must provide the Private IP address of all the Automation Suite Robots nodes.
[all:vars]	The group of variables applied to all the previously defined host groups. ansible_connection - The authentication method. Two SSH mechanisms are supported: key-based SSH authentication and password-based SSH authentication. ansible_timeout - The default amount of time during which an SSH connection can be established before the operation times out. It also controls how long it takes to access the connection, once established. ansible_user - The name of the user logging in to the remote server. You can provide the variables per group or per host node. For details, see Assigning a variable to many machines: group variables.

Generating the Ansible variable file

For Ansible orchestration on other nodes, you must define some parameters that Ansible uses to determine the location of the installer and corresponding files on other nodes. These parameters are define in the Yaml file and provided to Ansible.

If you want to modify the default configuration, create a file in following format and provide it to uipathctl.sh using --ansible-variables-file.

#Path where installer zip is available. By default, uipathctl.sh takes the current folder and compress it to zip before copying it to other nodes.
installer_path: /path/to/installer.zip
# Path where installer will be copied on nodes
target_installer_base_path: /opt/UiPathAutomationSuite/<version>/installer
# Install type - online or offline
install_type: online
# Path on nodes where offline bundles will be copied
target_bundle_base_path: /opt/UiPathAutomationSuite/{version}
# Path on nodes where offline bundles will be extracted
target_tmp_path: /opt/UiPathAutomationSuite/tmp
# Basepath and filname for the various config files and bundles on the local machine
cluster_config_filename: cluster_config.json
cluster_config_basepath: /var/tmp/uipathctl_{version}
backup_config_filename: backup_config.json
backup_config_basepath: /var/tmp/uipathctl_{version}
restore_config_filename: restore.json
restore_config_basepath: /var/tmp/uipathctl_{version}
infra_bundle_filename: as-infra.tar.gz
infra_bundle_basepath: /var/tmp/uipath_upgrade_<version>

Variable	Value
installer_path	The path of as-installer.zip. If you do not provide this value, uipathctl.sh will zip the current directory and copy it to other nodes, as an installer zip.
target_installer_base_path	The path where the installer will be copied on the nodes. The default value is `/opt/UiPathAutomationSuite/{version
install_type	The installation method. Possible values are: online and offline.
target_bundle_base_path	The path on the nodes where the offline bundles will be copied. The default location is `/opt/UiPathAutomationSuite/{version
target_tmp_path	The path on the nodes where the bundle is extracted. The default location is /opt/UiPathAutomationSuite/tmp.
cluster_config_filename	The name of the cluster configuration file. The default value is cluster_config.json.
cluster_config_basepath	The location where cluster_config.json will be stored temporarily on the nodes during orchestration. The default value is /var/tmp/uipathctl_{version}.
backup_config_filename	The name of the backup configuration file. The default value is backup.json.
backup_config_basepath	The location where backup.json will be stored temporarily on the nodes during orchestration. The default value is /var/tmp/uipathctl_{version}.
restore_config_filename	The name of the restore configuration file. The default value is restore.json.
restore_config_basepath	The location where restore.json will be stored temporarily on the nodes during orchestration. The default value is /var/tmp/uipathctl_{version}.
infra_bundle_filename	The name of the bundle containing the infrastructure layers. This is the same as the one you provided to the uipathctl.sh script.
infra_bundle_basepath	The location where as-infra.tar.gz will be stored temporarily on the nodes during orchestration. This is the same as the one you provided to the uipathctl.sh script.