Subscribe

UiPath Automation Suite

The UiPath Automation Suite Guide

Advanced installation experience

This page explains how to use Automation Suite's cluster_config.json configuration file.

The cluster_config.json file defines the parameters, settings, and preferences applied to the UiPath services deployed via Automation Suite. You need to update this file if you want to change defaults and use any advanced configuration for your cluster.

To edit cluster_config.json, you can use either:

  • a Linux text editor, such as vi or GNU nano, directly on the Linux machine via SSH (e.g., command: vi cluster_config.json);
  • your favorite text editor and then copy paste the file on the machine.

The cluster_config.json file allows you to configure the UiPath services you want to deploy. There are two types of UiPath services:

  • mandatory services: these are installed by default and do not have the enabled flag available on them;
  • optional services: these are not required to complete the install. However, be aware that products may have dependencies. Please see Product dependencies for more details on this.

To enable or disable a service via the cluster_config.json file, use true or false for the enabled flag.

cluster_config.json sample

{
  "fqdn": "PLACEHOLDER",
  "fixed_rke_address": "PLACEHOLDER",
  "multinode": "false",
  "admin_username": "PLACEHOLDER",
  "admin_password": "PLACEHOLDER",
  "profile": "ha",
  "telemetry_optout": "true",
  "gpu_support": "false",
  "rke_token": "PLACEHOLDER",
  "server_certificate": {
    "ca_cert_file": "/absolute/path/to/rootCA.crt",
    "tls_cert_file": "/absolute/path/to/server.crt",
    "tls_key_file": "/absolute/path/to/server.key"
  },
  "infra": {
    "docker_registry": {
      "username": "PLACEHOLDER",
      "password": "PLACEHOLDER"
    }
  },
  "identity_certificate": {
    "token_signing_cert_file": "/absolute/path/to/identity.pfx",
    "token_signing_cert_pass": ""
  },
  "sql": {
    "server_url": "PLACEHOLDER",
    "username": "PLACEHOLDER",
    "password": "PLACEHOLDER",
    "port": "PLACEHOLDER",
    "create_db": "PLACEHOLDER"
  },
  "sql_connection_string_template": "PLACEHOLDER",
  "sql_connection_string_template_jdbc": "PLACEHOLDER",
  "sql_connection_string_template_odbc": "PLACEHOLDER",
  "orchestrator": {
    "testautomation": {
      "enabled": true
    },
    "updateserver": {
      "enabled": true
    }
  },
  "aicenter": {
    "enabled": true,
    "sql_connection_str": "PLACEHOLDER"
  },
  "documentunderstanding": {
    "enabled": true,
    "datamanager": {
      "sql_connection_str": "PLACEHOLDER"
    },
    "handwriting": {
      "enabled": true,
      "max_cpu_per_pod": 2
    }
  },
  "insights": {
    "enabled": true
  },
  "test_manager": {
    "enabled": true
  },
  "automation_ops": {
    "enabled": true
  },
  "automation_hub": {
    "enabled": true
  },
  "apps": {
    "enabled": true
  },
  "action_center": {
    "enabled": true
  },
  "task_mining": {
    "enabled": true
  }
}

 

General configuration


Mandatory parameters

Description

fqdn

The load balancer (multi-node) or machine (single-node) domain name.

fixed_rke_address

Fixed address used to load balance node registration and kube API requests. This should be fqdn if load balancer is configured as recommended. Otherwise FQDN of 1st Server Node. Refer to Configuring the load ode-configurinbalancer.

Can be the IP/FQDN of the first rke2 server in your setup.

multinode

Set to true when choosing a multi-node profile. The value of this flag is set automatically by the interactive install wizard. It is used for internal purposes only and should not be modified manually.

admin_username

The username that you would like to set as admin (such as: admin ) for the host organization.

admin_password

The host tenant admin password to be set.

rke_token

Use a newly generated GUID here. This is a pre-shared, cluster-specific secret. It is needed for all the nodes joining the cluster.

profile

Sets the profile of the installation. The available profiles are:
default: single-node evaluation profile.
ha: Multi-node HA-ready production profile.
The value of this flag is set automatically by the interactive install wizard. It is used for internal purposes only and should not be modified manually.

infra.docker_registry.username

The username that you would like to set for the docker registry installation.

infra.docker_registry.password

The password that you would like to set for the docker registry installation.

gpu_support

Set to false by default. The value of this flag is set automatically by the interactive install wizard. It is used for internal purposes only and should not be modified manually.
Please refer to Adding a dedicated agent node with GPU support for instructions on how to add a GPU agent node to the cluster.

🚧

Important!

gpu_support flag is set to false and should not be modified. To add a dedicated agent node with GPU support to the cluster, please refer to Adding a dedicated agent node with GPU support for instructions on how to add a GPU agent node to the cluster.

Optional parameters

Description

telemetry_optout

true or false - used to opt-out of sending telemetry back to UiPath. It is set to false by default.

If you wish to opt out, then set to true.

 

Setting certificates


Please refer to the prerequisite documents to obtain certificate:

If no certificate is provided at time of installation, the installer creates a self-issued certificate and configures it in the cluster. The validity of the certificate is 90 days.

In multi-node installations, a certificate is required only on the first node.

📘

Note:

Make sure to specify the absolute path for certificate files. Run pwd to get the path of the directory where files are placed and append the certificate file name in the cluster_config.json. In multi-node installations, a certificate is required only on the first node.

Parameter

Description

server_certificate.ca_cert_file

Absolute path to Certificate Authority certificate. This certificate is the authority that signs the TLS certificate. In case of self-signed is the rootCA.crt created in earlier steps. Leave blank, in case you want installer to generate.

server_certificate.tls_cert_file

Absolute path to TLS certificate (server.crt for self-signed created in earlier steps). Leave blank, in case you want installer to generate.

server_certificate.tls_key_file

Absolute path to certificate key (server.key for self-signed created in earlier steps). Leave blank, in case you want installer to generate.

identity_certificate.token_signing_cert_file

Absolute path to the Identity Service certificate used to sign tokens (identity.pfx for self-signed created in earlier steps). Leave blank, in case you want installer to generate identity certificate using server certificate.

identity_certificate.token_signing_cert_pass

Plain text password set when it was exported.

additional_ca_certs

Absolute path to the file containing additional CA certificates that you want to be trusted by all the services running as part of Automation Suite. All certificates in the file should be valid PEM format.

For example, you need to provide the file containing the SQL server CA certificate if the certificate is not issued by a public certificate authority.

 

Database configuration


Automatically create the necessary databases

If you want the installer to create the databases, then please fill in the following fields:

Parameter

Description

sql.create_db

Set to true.

sql.server_url

FQDN of the SQL server, where you want the installer to configure database.

sql.port

Port number on which a database instance should be hosted in the SQ: server.

sql.username

Username / userid to connect to the SQL server.

sql.password

Password of the username provided earlier to connect to the SQL server.

📘

Important:

Ensure the user has the dbcreator role. This grants them permission to create the database in SQL Server. Otherwise the installation fails.

ODBC connection does not support usernames that contain special characters. For database usernames for AI Center and Document Understanding, use only uppercase and lowercase letters.

 

Bring your own database

In case if you are providing the database, then we need SQLconnection strings for every database. Automation Suite supports the following SQL connection string formats.

Parameter

Description

Products

sql_connection_string_template

Full ADO.NET connection string where Catalog name is set to DB_NAME_PLACEHOLDER. The installer will replace this placeholder with the default database names for the installed suite services.

Platform, Orchestrator, Test Manager, Automation Hub, Automation Ops, Insights, Task Mining

sql_connection_string_template_jdbc

Full JDBC connection string where database name is set to DB_NAME_PLACEHOLDER. The installer will replace this placeholder with the default database names for the installed suite services.

AI Center

sql_connection_string_template_odbc

Full ODBC connection string where database name is set to DB_NAME_PLACEHOLDER. The installer will replace this placeholder with the default database names for the installed suite services.

Document Understanding

📘

Note:

If you set TrustServerCertificate=False, then you may have to provide an additional CA certificate for the SQL Server. This is required if the SQL Server certificate is self-signed or signed by an internal CA.

See Setting Certificates for more details.

sql_connection_string_template example
Server=tcp:sfdev1804627-c83f074b-sql.database.windows.net:1433;Initial Catalog=DB_NAME_PLACEHOLDER;Persist Security Info=False;User [email protected];Password=***;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Max Pool Size=100;
sql_connection_string_template_jdbc example
jdbc:sqlserver://sfdev1804627-c83f074b-sql.database.windows.net:1433;database=DB_NAME_PLACEHOLDER;user=testadmin;password=***;encrypt=true;trustServerCertificate=false;Connection Timeout=30;hostNameInCertificate=sfdev1804627-c83f074b-sql.database.windows.net"
sql_connection_string_template_odbc example
SERVER=sfdev1804627-c83f074b-sql.database.windows.net,1433;DATABASE=DB_NAME_PLACEHOLDER;DRIVER={ODBC Driver 17 for SQL Server};UID=testadmin;PWD=***;MultipleActiveResultSets=False;Encrypt=YES;TrustServerCertificate=NO;Connection Timeout=30;"
Default and optional DB names for Automation Suite services
{
  "orchestrator": "AutomationSuite_Orchestrator",
  "orchestrator_ta": "AutomationSuite_Orchestrator",
  "orchestrator_upd": "AutomationSuite_Platform",
  "platform": "AutomationSuite_Platform",
  "test_manager": "AutomationSuite_Test_Manager",
  "automation_ops": "AutomationSuite_Platform",
  "automation_hub": "AutomationSuite_Automation_Hub",
  "insights": "AutomationSuite_Insights",
  "insights_data": "AutomationSuite_Insights_Data",
  "task_mining": "AutomationSuite_Task_Mining",
}

📘

Note:

If you you want to override the connection string for any of the services above, set the sql_connection_str for that specific service.

You still have to manually create these databases before running the installer.

Overriding the default connection string for Orchestrator and the platform
{
  "orchestrator": {
    "sql_connection_str": "Server=tcp:sfdev1804627-c83f074b-sql.database.windows.net,1433;Initial Catalog=CustomOrchDB;Persist Security Info=False;User [email protected];Password=***;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Max Pool Size=100;"
  },
  "platform": {
    "sql_connection_str": "Server=tcp:sfdev1804627-c83f074b-sql.database.windows.net,1433;Initial Catalog=CustomIDDB;Persist Security Info=False;User [email protected];Password=***;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;Max Pool Size=100;"
  }
}

To override the database connection strings for other products, set the sql_connection_str in the corresponding product blocks. The connection string should have a format supported by the respective product.

Example for setting database connection string for AI Center

Parameter

Description

aicenter.sql_connection_str

AICenter JDBC connection string (Refer below for the JDBC format)

📘

Note:

Please check the JDBC connection string has the format in the sample below.

"aicenter": {
    "enabled": true,
    "sql_connection_str": "jdbc:sqlserver://sfdev1804627-c83f074b-sql.database.windows.net;database=aicenter;[email protected];[email protected]_euHQZJ"
}
Sample DU connection string
"documentunderstanding": {
    "enabled": true,
  {
  "datamanager": {
    "sql_connection_str": "mssql+pyodbc://testadmin:[email protected]:1433/datamanager?driver=ODBC+Driver+17+for+SQL+Server",
  }
}

Note: The data manager SQL connection string is optional only if you want to overwrite the default with your own.
Handwriting is always enabled for online installation.
The default value for max_cpu_per-pod is value, but you can adjust it according to your needs. For more information, check the Installing Document Understanding guide.

🚧

Important!

Make sure the SQL account specified in the connection strings is granted the db_owner role for all Automation Suite databases. If security restrictions do not allow the use of db_owner, then the SQL account should have the following roles and permissions on all databases:

  • db_ddladmin
  • db_datawriter
  • db_datareader
  • EXECUTE permission on dbo schema

 

Enabling High Availability Add-on for the cluster

In a multi-node setup, High Availability (HA) is enabled by default. However, the Redis-based in-memory cache used by cluster services is running on a single node and represents a single point of failure. To mitigate the impact of a cache node failure or restart, you can purchase the High Availability Add-on (HAA), which enables redundant, multi-node deployment of the cache.

📘

Note:

All installations include the HAA software with a single-node license. This license is free of cost, no purchase required.

If you wish to enable HAA across multiple nodes, then purchasing an HAA license is required. This will implement full high availability for the cluster in a multi-node setup.

HAA is based on Redis technology.

To do that, take the following steps:

  1. Purchase an HAA license. Contact UiPath for details.
  2. Update the following fields in the cluster.config.json file:
    • fabric.redis.license - enter the HAA license converted to a single base64 string. In bash you can do that using echo 'license_text_here' | base64 -w0.
    • fabric.redis.ha - use true to enable HAA and make sure to also configure the fabric.redis.license parameter. This enables HAA database replication and increases the number of HAA pods to 3. By default, fabric.redis.ha is set to false.

📘

Note:

If redis.ha is enabled, redis.license needs to be set to a license that supports more than two shards.

{
"fabric": {
    "redis": { 
        "ha": true
        "license": Base64String
    }
}
  1. Rerun the installation.

 

Insights-specific configuration


If enabling Insights, users can include SMTP server configuration that will be used to send scheduled emails/alert emails. If not provided, scheduled emails and alert emails will not function.

The insights.smtp_configuration fields details:

Parameter

Description

tls_version

Valid values are TLSv1_2, TLSv1_1, SSLv23. Omit key altogether if not using TLS.

from_email

Address that alert/scheduled emails will be sent from.

host

Hostname of the SMTP server.

port

Port of the SMTP server.

username

Username for SMTP server authentication.

password

Password for SMTP server authentication.

Click to see an example
"insights": {
    "enabled": true,
    "smtp_configuration": {
      "tls_version": "TLSv1_2",
      "from_email": "[email protected]",
      "host": "smtp.sendgrid.com",
      "port": 587,
      "username": "login",
      "password": "password123"
    }
  }

 

Monitoring configuration


To provision enough resources for monitoring (see Using the monitoring stack), you should consider the number of vCPUs in the cluster and the amount of desired metric retention. See below for how to set the following monitoring resource configurations.

The following table describes the monitoring field details:

Parameter

Description

prometheus_retention

In days.
This is the amount of days that metrics will be retained for the purpose of visualization in Grafana and manual querying via the Prometheus console.

Default value is 7.

prometheus_storage_size

In GB.
Amount of storage space to reserve per Prometheus replica.
A good rule of thumb is to set this value to:
0.65 * vCPU cores * (prometheus_retention / 7)

Example:
If you set prometheus_retention to 14 days, and your cluster has 80 cores spread across 5 machines, this becomes:
0.65 * 80 * (14 / 7)
52 * (2)
104

Default value is 45 and should not be set lower.

If Prometheus starts to run out of storage space, an alert will be triggered with specific remediation instructions. See here.

prometheus_memory_limit

In MB.
Amount of memory to limit each Prometheus replica to.
A good rule of thumb is to set this value to:
100 * vCPU cores * (prometheus_retention / 7)

Example:
If you've set prometheus_retention to 14 days, and your cluster has 80 cores spread across 5 machines, this becomes:
100 * 80 * (14 / 7)
8000 * (2)
16000

Default value is 3200 for single-node, and 6000 for multi-node clusters, and should not be set lower.

If Prometheus starts to run out of memory, an alert will be triggered with specific remediation instructions. See here.

Click to see an example
"monitoring": {
  "prometheus_retention": 14,
  "prometheus_memory_limit": 16000,
  "prometheus_storage_size": 104
}

 

Optional: Configuring the proxy server


📘

Note:

Make sure you meet the proxy server requirements before configuring the proxy server during installation.

While running the interactive installer wizard, you need to exit it and update the cluster_config.json during the advanced configuration step.

You need to add the following to the configuration file using vim or your favorite editor to the configuration file:

"proxy": {
  "enabled": "true",
  "http_proxy": "http://<PROXY-SERVER-IP>:<PROXY-PORT>",
  "https_proxy": "http://<PROXY-SERVER-IP>:<PROXY-PORT>",
  "no_proxy": "alm.<fqdn>,<fixed_rke_address>:9345,<fixed_rke_address>:6443,<named server address>,<metadata server address>,10.0.0.0/8,<private_subnet_ip>,<sql server host>,<Comma separated list of ips that should not got though proxy server>"
}

Mandatory parameters

Description

enabled

Use true or false to enable or disable proxy settings.

http_proxy

Used to route HTTP outbound requests from the cluster. This should be the proxy server FQDN and port.

https_proxy

Used to route HTTPS outbound requests from the cluster. This should be the proxy server FQDN and port.

no_proxy

Comma-separated list of hosts, IP addresses, or IP ranges in CIDR format that you do not want to route via the proxy server. This should be a private subnet range, sql server host, named server address, metadata server address: *.<fqdn>,<fixed_rke_address>:9345,<fixed_rke2_address>:6443.

fqdn - the cluster FQDN defined in cluster_config.json
fixed_rke_address - the fixed_rke_address defined in cluster_config.json
named server address - the IP address from /etc/resolv.conf
private_subnet_ip - the cluster VNet
sql server host - sql server host
metadata server address - the IP address 169.254.169.254 used to fetch machine metadata by cloud services such as Azure and AWS

 

Optional: Enabling resilience to zonal failures in a multi-node cluster

To enable resilience to zonal failures in a multi-node cluster, take the following steps:

  1. Make sure nodes are spread evenly across three availability zones. For a bare-metal server or VM provided by any vendor except for AWS, Azure, or GCP, zone metadata has to be provided via the configiratopm file at /etc/default/k8s-node-labels on every machine in following format.
NODE_REGION_LABEL=<REGION_NAME>
NODE_ZONE_LABEL=<ZONE_NAME>
cat > /etc/default/k8s-node-labels <<EOF
EXTRA_K8S_NODE_LABELS="topology.kubernetes.io/region=$NODE_REGION_LABEL,topology.kubernetes.io/zone=${NODE_ZONE_LABEL}"
EOF
  1. Update the cluster_config.json file during the advanced configuration step.

To update the cluster_config.json using the interactive installation wizard, exit at advanced configuration step and add the following to the configuration file using vim or your favorite editor:

"zone_resilience": true

Mandatory parameters

Description

zone_resilience

Use true or false to enable or disable resilience to zonal failure.

Updated about a month ago


Advanced installation experience


This page explains how to use Automation Suite's cluster_config.json configuration file.

Suggested Edits are limited on API Reference Pages

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