Prerequisite checks

Run uipathctl prereq run to validate the infrastructure prerequisites for Automation Suite on OpenShift, including the namespace-scoped flow.

It is recommended to run the prerequisite checks to ensure that you properly configured the cloud infrastructure and to validate input.json before starting the Automation Suite installation.

This page covers:

• Running the prerequisite checks
• What the prerequisite checks validate
• Running prerequisite checks without cluster roles
• Validating the excluded checks manually

Running the prerequisite checks

Run the prerequisite checks with a kubeconfig that has cluster-scoped access. If uipathadmin is namespace-scoped only, follow Running prerequisite checks without cluster roles instead.

To check the prerequisites based on the inputs you configured in the input.json, run the following command from a machine with access to the cluster's Kubernetes API:

uipathctl prereq run input.json --versions versions.json

For details on the flags that you can use with the uipathctl prereq run command, refer to uipathctl prereq run.

By default, the uipathctl prereq command checks all the prerequisites. Alternatively, the command also allows you to run strictly the checks that are relevant to you, as follows:

• If you want to exclude components from the execution, use the --excluded flag. For example, if you do not want to check the database connection strings, run uipathctl prereq --excluded SQL. The command runs all the prerequisite checks except for the SQL-related one.
• If you want to include only certain components in the execution, use the --included flag. For example, if you only want to check the DNS and objectstore, run uipathctl prereq --included DNS,OBJECTSTORAGE.
• If you want to access the detailed prerequisites check output, use the --verbose flag. You can skip this flag for a more concise and simplified output.

Note:

You can find the names of the components you can include or exclude from the prerequisite checks in the prerequisite check output. In the example, the first word on each outdented line represents the component name. For example: SQL, OBJECTSTORE, DNS, etc.

The prerequisite and health checks/tests run in the <uipath> namespace. You must either grant the uipathctl tool the necessary permissions to allow the creation of the <uipath> namespace or create it yourself before running the checks/tests. Additionally, some checks/tests require that you enable the use of hostNetwork.

To run the tests related to the host network, you must allow the tool to run with cluster admin privileges. Otherwise, the following warning is displayed in the prerequisite check output:

Ran CONNECTIVITY checks...
     ⚠  [CONNECTIVITY]
        ⚠  [NETWORK_TEST_SETUP] Failed to create the network test infrastructure: failed to create echo-host-role role: error creating role: roles.rbac.authorization.k8s.io "network-prereq-6c5mt-echo-host-role" is forbidden: user "system:serviceaccount:uipath:uipathadmin" (groups=["system:serviceaccounts" "system:serviceaccounts:uipath" "system:authenticated"]) is attempting to grant RBAC permissions not currently held:
{APIGroups:["security.openshift.io"], Resources:["securitycontextconstraints"], ResourceNames:["hostnetwork-v2"], Verbs:["use"]}

What the prerequisite checks validate

The checks in the following table are run on each node:

Check	Description
SQL Connection	Validates that Automation Suite can successfully connect to the SQL server for UiPath® products and shared services (such as Identity, Portal, Org Management, etc.) using the SQL connection strings provided in the input.json file. This is mandatory for a successful installation.
SQL DB roles	Validates the necessary roles and permissions required by UiPath® products. This is mandatory for a successful installation.
SQL DB compatibility	Validates SQL DB compatibility requirements.
FQDN resolution	Validates that the FQDN and the sub-domains are successfully resolvable.
Object Storage API	Validates that objectstore APIs are accessible based on access information provided in the input.json file. This is mandatory for a successful installation of the UiPath® services.
Cache / Redis	Validates the connection to Redis. This is mandatory for a successful installation.
Capacity	Validates you have minimum CPU and RAM capacity on the worker nodes based on the products enabled in the input.json file.
Storage Class	Validates that the storage classes for File Storage are configured as required for Automation Suite Robots.
Optional Components	Validates that your cluster has components that you chose to exclude from the Automation Suite installation.
Ingress	Validates that the cluster ingress is configured correctly and the FQDN URL requests can reach UiPath® products.
Network Policies	Checks if the network policies configured in Automation Suite are compatible with the cluster.
Registry	Validates that Automation Suite can access the UiPath® docker registry. This is mandatory for a successful installation.
Cluster Connectivity	Validates whether the cluster communication is configured properly: - Between two random pods completed - Between pod and a multinode ClusterIP - Between pod and a multinode ClusterIP without a clusterIP - Between pod and a multinode ClusterIP using HostNetwork - Between pod and a multinode ClusterIP without a clusterIP set using HostNetwork - Between two pods colocated on the same node via ClusterIP Connectivity checks can fail on OpenShift 4.16–4.18 control-plane nodes due to port conflicts. To address the issue, refer to the Troubleshooting section.

Running prerequisite checks without cluster roles

Note:

This section applies only if you granted the Automation Suite installer service account (uipathadmin) namespace-scoped permissions only, without any cluster-scoped permissions. For details, refer to Granting installation permissions without cluster roles.

If uipathadmin has the cluster-scoped permissions, run the prerequisite checks as described in Running the prerequisite checks instead.

When uipathadmin is namespace-scoped only, a fixed set of uipathctl prereq run checks fail because they require cluster-scoped access - either a read on a cluster-scoped resource (such as nodes, namespaces, storageclasses, or customresourcedefinitions) or, in the case of the connectivity check, the ability to use the hostnetwork-v2 security context constraint. Use the --excluded flag to skip exactly those checks:

uipathctl prereq run input.json \
  --kubeconfig <uipathadmin.kubeconfig> \
  --versions versions.json \
  --excluded "INGRESS,NAMESPACE,OSS,StorageClass,NODE,GPU,CONNECTIVITY"

Excluding a check does not remove the underlying requirement; the property is still required for a healthy installation. The following table describes what each excluded check verifies, the cluster-scoped access it needs, and exactly what a cluster administrator must confirm out-of-band, using a kubeconfig with cluster-admin privileges.

Excluded token	Cluster-scoped access it requires	What the check verifies
INGRESS	nodes [list]	That the Automation Suite FQDN is reachable over HTTPS through the Istio ingress gateway, from within the cluster, on every node.
NAMESPACE	namespaces [get, list]	That the <argocd>, installer, and <uipath> namespaces exist, and that <uipath> carries the required injection labels.
OSS	customresourcedefinitions [list]	That bring-your-own components you excluded from the install (for example, Istio and OPA Gatekeeper) are present and at a supported version.
StorageClass	storageclasses [get], nodes [list]	That the storage class in input.json exists and can actually provision and mount a volume on your worker nodes (the check creates a test StatefulSet and waits for the volume to bind and mount).
NODE	nodes [list, get], node metrics	That each worker node meets the minimum CPU and RAM requirements and is not over-utilized on CPU, memory, or pod count.
GPU	nodes [list]	That enough GPU-labeled nodes with available GPUs exist for the enabled GPU products, with the minimum node count depending on which GPU products are enabled.
CONNECTIVITY	securitycontextconstraints use on hostnetwork-v2; roles [create] for the host-network test pods	That pods can communicate across nodes over the overlay network (by pod IP), through a ClusterIP Service, and using hostNetwork.

Validating the excluded checks manually

After you exclude the checks, a cluster administrator must validate each excluded requirement manually, using a kubeconfig with cluster-admin privileges:

• INGRESS: Confirm that all worker nodes are Ready and that the ingress routes exist:

  kubectl get nodes -o wide
  oc get routes -n <istio-system>
  curl -sko /dev/null -w "%{http_code}\n" https://<fqdn>
  

  The installer's INGRESS check probes the FQDN from inside the cluster, on every node, and treats the gateway as reachable when it responds - including with a 404, or a 503 on OpenShift - because no backend serves the FQDN before Automation Suite is installed. Do not expect a 200 at this stage. Because the curl command above runs from your workstation, it may instead print 000 when the FQDN does not yet resolve or route from your machine; that reflects client-side reachability and is not by itself a cluster problem. The signals that matter here are that the worker nodes are Ready and the ingress routes exist.

• NAMESPACE: Confirm the namespaces exist and <uipath> carries the required injection labels:

  kubectl get ns <argocd> <uipath>
  kubectl get ns <uipath> --show-labels
  

  The output must show istio-injection=enabled and uipath-injection=enabled.

• OSS: Confirm the CRDs are present, Istio is at a supported version, and the configured gateway is running:

  kubectl get crd | grep -E 'istio.io|gatekeeper'
  istioctl version
  oc get pods -l istio=ingressgateway -n <istio-system>
  

  Confirm the Istio version is 1.14.0 or higher, and that the gateway_selector in input.json matches the running gateway.

• StorageClass: Confirm the storage class exists:

  kubectl get sc <name>
  

  Then create a 1 GiB PersistentVolumeClaim against it and a pod that mounts it. Confirm the PVC reaches Bound and the pod starts on a worker node - this exercises the same zone and topology compatibility the check covers.

• NODE: Confirm allocatable capacity and utilization per node:

  kubectl get nodes -o custom-columns=NAME:.metadata.name,CPU:.status.allocatable.cpu,MEM:.status.allocatable.memory
  kubectl top nodes
  

  Each node must show at least 8 CPU and 16 Gi allocatable, with CPU and memory usage below 80%. Cross-check against the node sizing in Kubernetes cluster and nodes.

• GPU: Confirm the GPU node count meets the requirement (5 nodes for Document Understanding modern projects; otherwise no minimum) and that allocatable GPUs are available on those nodes:

  kubectl get nodes -l nvidia.com/gpu.present=true
  kubectl get nodes -o custom-columns=NAME:.metadata.name,GPU:.status.allocatable.'nvidia\.com/gpu'
  

  The second command's output must show a value greater than 0. For the GPU sizing requirements, refer to Kubernetes cluster and nodes.

• CONNECTIVITY: The most reliable option is for a cluster administrator to run only this check with an admin kubeconfig:

  uipathctl prereq run input.json --versions versions.json --included CONNECTIVITY
  

  Alternatively, schedule two pods on different worker nodes and confirm they can reach each other by pod IP and through a ClusterIP Service.

Important:

Excluding these checks does not remove the underlying requirements; the corresponding behavior is still required at runtime. Validate every property in the table above before you proceed to the installation.