automation-suite
2024.10
true
UiPath logo, featuring letters U and I in white
Automation Suite on Linux Installation Guide
Last updated Nov 21, 2024

Configuring the OCI-compliant registry for offline installations

In offline installations, you need a registry compliant with OCI (Open Container Initiative) to store the container images and deployment Helm charts. If you perform an online installation, skip this step.

Make sure to run the scripts present in the target installer /opt/UiPathAutomationSuite/latest/installer.
Note:

You must choose one of the following options to set up the OCI-compliant registry:

Uploading the Automation Suite artifacts to the external OCI-compliant registry

There are two ways to upload the Automation Suite artifacts to the external OCI-compliant registry:

The following table compares the two options to upload the artifacts to the registry so that you can choose the one that suits your needs:

Option A: Mirroring the registry

Option B: Hydrating the registry

Copies the artifacts from the UiPath® registry to any target registry.

Uses the offline tarball to untar and upload the artifacts to the target registry.

Requires Docker and Helm tools.

Requires Podman and Helm tools.

Requires internet access to copy the artifacts from the UiPath® registry to the target registry.

Requires internet access only to download the offline tarball to the jump server. Uploading the tarball does not require internet access.

Requires a temporary space to cache the images during the copying method. This space is usually configured during the Docker installation. The default location is /var/lib/docker.

Requires a temporary space to extract the tarball and a temporary space for Podman to load the images.

The location of the tarball extraction must be provided during the hydration step. The Podman location can be /var/tmp, which must have adequate storage available.
The required storage capacity for the /var/lib/docker directory is around 128 GiB.
The required storage capacity for the extraction is around 200 GiB, and /var/tmp must be 256 GiB.
Note: It is recommended to perform the mirroring or hydration operation from the management machine or jump box, instead of using the server nodes.

Option A: Mirroring the UiPath® registry to your registry

This method requires internet access on the jump machine from which you upload the Automation Suite artifacts onto your OCI-compliant registry.

Prerequisites for mirroring the UiPath® registry

To mirror the UiPath® registry, you need the following:

  • a VM running a Linux distribution (recommended) or a laptop (not recommended);

  • a Docker client authenticated with the private registry;

  • Helm 3.8 or newer authenticated with the private registry;

  • as-images.txt;
  • as-helm-charts.txt;
  • mirror-registry.sh;
  • outbound connectivity to registry.uipath.com;
  • 128 GiB of free disk space for Docker under the /var/lib/docker partition on the machine from which you upload the container images and charts.
Installing Docker and Helm

You must have Docker and Helm installed and authenticated on the machine from which you plan to upload the Automation Suite container images and charts to your registry.

  • To download the Docker binaries, see the official documentation.

  • To authenticate the Docker registry, see the official documentation. Alternatively, you can use the following command by replacing the sample credentials with your actual registry credentials: 

    docker login my.registry.io:443 --username "admin" --password "secret"docker login my.registry.io:443 --username "admin" --password "secret"

  • To download the Helm binaries, see the official documentation.

  • To authenticate the Helm registry, see the official documentation. Alternatively, you can use the following command by replacing the sample credentials with your actual registry credentials: 

    helm registry login my.registry.io:443 --username "admin" --password "secret"helm registry login my.registry.io:443 --username "admin" --password "secret"
Downloading as-images.txt
To download as-images.txt, see Downloading installation bundles.
Downloading as-helm-charts.txt
To download as-helm-charts.txt, see Downloading installation bundles.
Downloading the optional Document Understanding bundles

To download the optional Document Understanding bundles, see Document Understanding documentation.

Downloading mirror-registry.sh
To download the mirror-registry.sh script, see Downloading the installation packages.

Uploading the Automation Suite images to your registry

The mirror-registry.sh script requires outbound connectivity to the source (default registry.uipath.com) and target registries.
Note:
The mirror-registry.sh script does not perform authentication to the registry. It is assumed that you have already authenticated to the registry.

Flag

Environment variable

Description

--images-manifest

IMAGES_MANIFEST

Mandatory. Path to the image manifest file.

--helm-charts-manifest

HELM_CHARTS_MANIFEST

Mandatory. Path to the Helm chart manifest file.

--target-registry-url

TARGET_REGISTRY_URL

Mandatory. Pass the URL for the target registry.

--source-registry-url

SOURCE_REGISTRY_URL
Optional. Pass the URL for the source registry; the default is registry.uipath.com.
To upload the Automation Suite images to your registry:

  1. Ensure that you have the necessary permissions to execute the shell script, by running the following command:

    chmod +x mirror-registry.shchmod +x mirror-registry.sh
  2. Upload the Automation Suite images to your registry, by running the following command:
    ./mirror-registry.sh --target-registry-url my.registry.io:443 --source-registry-url registry.uipath.com --images-manifest /home/myuser/as-images.txt --helm-charts-manifest /home/myuser/as-helm-charts.txt./mirror-registry.sh --target-registry-url my.registry.io:443 --source-registry-url registry.uipath.com --images-manifest /home/myuser/as-images.txt --helm-charts-manifest /home/myuser/as-helm-charts.txt
    Note: For registries, such as Harbor, which require using a project, make sure you append the project name to the target registry URL you include in the command, as shown in the following example: 
    ./mirror-registry.sh --target-registry-url my.registry.io:443/myproject --source-registry-url registry.uipath.com --images-manifest /home/myuser/as-images.txt --helm-charts-manifest /home/myuser/as-helm-charts.txt./mirror-registry.sh --target-registry-url my.registry.io:443/myproject --source-registry-url registry.uipath.com --images-manifest /home/myuser/as-images.txt --helm-charts-manifest /home/myuser/as-helm-charts.txt

Option B: Hydrating the registry with the offline bundle

This method only requires internet access on the jump machine to download the offline bundle. Once the bundle is available, you can upload to your OCI-compliant registry without an internet connection.

Note:

This method may also require additional space on the machine to un-tar and upload to your registry. In addition, this method may take longer than the mirroring approach.

Prerequisites for hydrating the registry

To hydrate the registry, you need the following:

  • a VM running a Linux distribution is preferred over running the script on a laptop;
  • ability to download and copy or somehow propagate the offline bundle to the VM;
  • Helm 3.8 or newer authenticated with the private registry;
  • Podman installed, configured, and authenticated with the private registry;
  • 150 GiB of free disk space for Podman under /var/lib/containers for loading the containers locally before pushing them to the remote registry. You can change the default path by updating the location of the graphRoot path in the output of the podman info command.
  • Set the TMP_DIR environment variable as described in the official Podman documentation.
  • as.tar.gz
Installing Podman and Helm

You must ensure you have Podman and Helm installed and authenticated on the machine from which you plan to upload the Automation Suite container images and charts to your registry.

  • To download the Podman binaries, see the official documentation.
  • To authenticate to the Podman registry, see the official documentation. Alternatively, you can use the following command by replacing the sample credentials with your actual registry credentials:
    podman login my.registry.io:443 --username "admin" --password "secret"podman login my.registry.io:443 --username "admin" --password "secret"
  • To download the Helm binaries, see the official documentation.
  • To authenticate the Helm registry, see the official documentation. Alternatively, you can use the following command by replacing the sample credentials with your actual registry credentials:
    helm registry login my.registry.io:443 --username "admin" --password "secret"helm registry login my.registry.io:443 --username "admin" --password "secret"
Downloading as.tar.gz
To download as.tar.gz, see Downloading installation bundles.
Downloading the optional Document Understanding bundles

To download optional Document Understanding bundles, see Document Understanding documentation.

Downloading hydrate-registry.sh
To download the hydrate-registry.sh script, see Downloading the installation packages.

Uploading the Automation Suite images to the registry

To upload the Automation Suite images to the registry, use the hydrate-registry.sh script.
The hydrate-registry.sh script does not require outbound connectivity except with the target registries.
Note:
The hydrate-registry.sh script does not perform authentication to the registry. It is assumed that you have already authenticated to the registry.

Flag

Description

--offline-bundle-path

Mandatory. Path to the offline bundle.

--target-registry-url

Mandatory. Pass the URL for the target registry.

--extract-path
The location to be used to untar the offline bundle. It can be either /var/lib/containers or a custom location. Ensure you have a minimum of 100 GiB of storage. It is recommended to have 256 GiB of storage.
To upload the Automation Suite images to the registry:

  1. Ensure that we have the necessary permissions to execute the shell script, by running the following command:

    chmod +x hydrate-registry.shchmod +x hydrate-registry.sh

  2. Upload the Automation Suite images to your registry by running the following command:

    ./hydrate-registry.sh --target-registry-url my.registry.io:443 --offline-bundle-path ./as.tar.gz --extract-path /extract/to/path./hydrate-registry.sh --target-registry-url my.registry.io:443 --offline-bundle-path ./as.tar.gz --extract-path /extract/to/path
Note: For registries, such as Harbor, which require using a project, make sure you append the project name to the target registry URL you include in the command, as shown in the following example: 
./hydrate-registry.sh --target-registry-url my.registry.io:443/myproject --offline-bundle-path ./as.tar.gz --extract-path /extract/to/path./hydrate-registry.sh --target-registry-url my.registry.io:443/myproject --offline-bundle-path ./as.tar.gz --extract-path /extract/to/path
For Document Understanding offline bundles, make sure to include --extract-path in the command, as shown in the following example:
./hydrate-registry.sh  --target-registry-url my.registry.io:443 --optional-bundle-path ./dusemistructured-2023.10.0.tar.gz --extract-path /tmp./hydrate-registry.sh  --target-registry-url my.registry.io:443 --optional-bundle-path ./dusemistructured-2023.10.0.tar.gz --extract-path /tmp

Configuring the certificate for the external OCI-compliant registry

To properly configure your external OCI-compliant registry, you must update the trust store of all the machines on which you plan to install Automation Suite. For instructions on how to perform this step post-installation, see Managing certificates.

To do that, take the following steps:

  1. Add the CA file to the /etc/pki/ca-trust/source/anchors/ location.
  2. Run update-ca-trust to update the trust store of the operating system. Once the trust store is updated, the extracted certificate file is merged in /etc/pki/ca-trust/extracted/ca-bundle.trust.crt.
Note:
You must provide the CA certificate during the Automation Suite installation. You must provide the certificate in the registry_ca_cert parameter in the cluster_config.json file. For details, refer to External OCI-compliant registry configuration.

Configuring the temporary Docker registry

Note:

This step is needed only for offline installations that use an in-cluster registry. You can skip this step if you perform an offline installation that uses an external OCI-compliant registry, or an online installation.

You must perform this step only on one of the server nodes. You must ensure that the node has an additional capacity of 512 GiB to be used as a backend for the registry. This is usually recommended to be on /uipath mount point.

The temporary Docker registry is only required during installation or upgrade. Once the installation or upgrade is successful, the temporary registry is no longer needed and should be uninstalled.

Prerequisites for setting the temporary registry

To set up the temporary registry, you need the following:

Installing the temporary registry

To install the temporary Docker registry on one of the nodes, run the following command:

./bin/uipathctl registry install-temp-registry -i /opt/UiPathAutomationSuite/cluster_config.json./bin/uipathctl registry install-temp-registry -i /opt/UiPathAutomationSuite/cluster_config.json

Flag

Description

-i|--input
Optional. Accepts the path to the cluster_config.json. It is only required when changing the default registry port and file path.
By default, the temporary registry is installed on the machine on port 30070 and uses the /uipath/data/registry file path. You must open port 30070 on the load balancer and the node on which you install the temporary docker registry.
Note:

The load balancer backend pool must exclusively target the nodes hosting the temporary docker registry.

If you want to change the default temporary registry port and file path, you must update the cluster_config.json file as shown in the following sample: 
{
  "infra": {
    "tmp_docker_registry": {
      "node_port": "<new port number>",
      "file_path": "/uipath/data/registry"
    }
  }
}{
  "infra": {
    "tmp_docker_registry": {
      "node_port": "<new port number>",
      "file_path": "/uipath/data/registry"
    }
  }
}

Hydrating the temporary registry

Installing Podman is mandatory prior to hydrating the temporary registry. If you have already validated and installed the required RPM packages, then Podman is automatically installed. Otherwise, it is essential to manually install Podman before proceeding to the configuration of the temporary Docker registry for offline installations.

After installing the temporary registry, take the following steps:

  1. Hydrate the temporary registry with the container images and Helm charts by running the following command:

    ./configureUiPathAS.sh registry hydrate-temp-registry --offline-bundle /uipath/tmp/as-fs.tar.gz -i cluster_config.json./configureUiPathAS.sh registry hydrate-temp-registry --offline-bundle /uipath/tmp/as-fs.tar.gz -i cluster_config.json
  2. Seed the internal registry from the temporary registry by running the following command. If you apply a patch, take the steps described in the following note. 
    ./configureUiPathAS.sh registry seed-internal-registry -i cluster_config.json./configureUiPathAS.sh registry seed-internal-registry -i cluster_config.json
    Note:

    If you apply a patch to an existing Automation Suite version, take the following steps instead. This is not applicable for LTS or CU.

    For more details on how to apply an Automation Suite hotfix, see Applying a patch.

    1. Download the and files, then take the following steps:

      1. Change the directory to the installer folder:

        cd "${INSTALLER_PATH}"cd "${INSTALLER_PATH}"
      2. Create a backup of the docker-image.json and helm-charts.json files: 
        cp versions/docker-images.json versions/docker-images.json.bak
cp versions/helm-charts.json versions/helm-charts.json.bakcp versions/docker-images.json versions/docker-images.json.bak
cp versions/helm-charts.json versions/helm-charts.json.bak
      3. Copy the downloaded docker-images.json and versions.json files to the installer folder: 
        cp <PATH_OF_PATCH_VERSION_docker-images.json> versions/docker-images.json
cp <PATH_OF_PATCH_VERSION_versions.json> versions/helm-charts.jsoncp <PATH_OF_PATCH_VERSION_docker-images.json> versions/docker-images.json
cp <PATH_OF_PATCH_VERSION_versions.json> versions/helm-charts.json

    2. Seed the internal registry from the temporary registry by running the following command:

      ./configureUiPathAS.sh registry seed-internal-registry -i cluster_config.json./configureUiPathAS.sh registry seed-internal-registry -i cluster_config.json
    3. Revert the docker-image.json and helm-charts.json to the original files: 
      cp versions/docker-images.json.bak versions/docker-images.json
cp versions/helm-charts.json.bak versions/helm-charts.jsoncp versions/docker-images.json.bak versions/docker-images.json
cp versions/helm-charts.json.bak versions/helm-charts.json

Flag

Description

--offline-bundle
File path containing the location of the as-fs.tar.gz on your server node.

-i|--input
Optional. Accepts the path to the cluster_config.json file. It is only required when changing the default Docker registry port and file path.

Was this page helpful?

Support and Services
Get The Help You Need
UiPath Academy
Learning RPA - Automation Courses
UiPath Forum
UiPath Community Forum
Uipath Logo White
Trust and Security
Terms of Use
Privacy Policy
Cookies Policy
© 2005-2024 UiPath. All rights reserved.