Subscribe

UiPath Automation Suite

The UiPath Automation Suite Guide

Using uipathctl.sh

This page provides instructions on how to use the uipathctl.sh script.

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


ParameterDescription
upgradeUpgrade the cluster.
sso-generate-connectorGenerate a sample file representing a Dex Connector for enabling SSO.
sso-generate-rbacGenerate an example ArgoCD RBAC file.
sso-generate-overlaysGenerate the Kustomize overlays for the ArgoCD and Dex deployment with SSO. Useful in debugging.
sso-apply-overlaysGenerate 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-configPath to your cluster_config.json file. If not specified, a configuration file is generated.
--kubeconfigPath to a Kubeconfig file that allows connecting to the cluster. Defaults to /etc/rancher/rke2/rke2.yaml.
--inventoryPath to a valid Ansible inventory describing the cluster. If not specified, an inventory is generated.
--ansible-usernameThe username to be used by Ansible to connect to cluster nodes. Defaults to the current user.
--ansible-private-keyThe SSH private key that provides connectivity to cluster nodes. If not specified, a set of passwords are prompted.
--ansible-ask-passwordAsk Ansible to request a password set for SSH connections and elevation.
--ansible-configSpecify the path to a custom ansible.cfg to be used.
--offline-infra-bundlePath to the sf-infra.tar.gz file. Required for offline upgrades.
--disable-cni-upgradeDo not perform CNI upgrade.
--sso-connector-typeConnector type for sso-generate-connector.
--sso-connector-filePath to a file containing a Dex Connector for the SSO integration.
--sso-rbac-filePath 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)

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 [email protected]

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)

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
GroupValue
[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.
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>
VariableValue
installer_pathThe 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_pathThe path where the installer will be copied on the nodes. The default value is /opt/UiPathAutomationSuite/{version}/installer.
install_typeThe installation method. Possible values are: online and offline.
target_bundle_base_pathThe path on the nodes where the offline bundles will be copied. The default location is /opt/UiPathAutomationSuite/{version}.
target_tmp_pathThe path on the nodes where the bundle is extracted. The default location is /opt/UiPathAutomationSuite/tmp.
cluster_config_filenameThe name of the cluster configuration file. The default value is cluster_config.json.
cluster_config_basepathThe location where cluster_config.json will be stored temporarily on the nodes during orchestration. The default value is /var/tmp/uipathctl_{version}.
backup_config_filenameThe name of the backup configuration file. The default value is backup.json.
backup_config_basepathThe location where backup.json will be stored temporarily on the nodes during orchestration. The default value is /var/tmp/uipathctl_{version}.
restore_config_filenameThe name of the restore configuration file. The default value is restore.json.
restore_config_basepathThe location where restore.json will be stored temporarily on the nodes during orchestration. The default value is /var/tmp/uipathctl_{version}.
infra_bundle_filenameThe name of the bundle containing the infrastructure layers. This is the same as the one you provided to the uipathctl.sh script.
infra_bundle_basepathThe 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.

Updated 22 days ago


Using uipathctl.sh


This page provides instructions on how to use the uipathctl.sh script.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.