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.

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.

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.

Add 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.

Installing Ansible and Other Prerequisite Tools

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. To install all the desired tools, take the steps in the following section. If all tools are already installed, you can skip these steps.

Installing Ansible and Other Prerequisite Tools

To install Ansible and other related packages, take the following steps:

1. Navigate to the installer folder on the Ansible host node. The installer is usually located in the /opt/UiPathAutomationSuite/{version} folder.
2. Run the following commands:

• For online:

  ./uipathctl.sh install-prerequisites --install-type online --accept-license-agreement

  • For offline:

You need an additional Ansible tarball, which contains Ansible and other dependent packages. Download ansible.tar.gz and store it anywhere outside the installer folder. For download instructions, see ansible.tar.gz.

If ansible.tar.gz is located in some different location, update the absolute location for the --offline-prerequisites-bundle parameter.

./uipathctl.sh install-prerequisites --install-type offline --offline-prerequisites-bundle ../ansible.tar.gz --accept-license-agreement

Advanced Ansible configuration

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'
[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.
[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: sf-infra.tar.gz
infra_bundle_basepath: /var/tmp/uipath_upgrade_<version>

Variable	Value
installer_path	The path of sf-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 /var/tmp/uipathctl_{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 sf-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.