Automation Suite on OpenShift installation guide

Step 1: Installing the service mesh​

• Installing OpenShift Service Mesh 2.x
• Installing OpenShift Service Mesh 3.x

Installing OpenShift Service Mesh 2.x​

1. Install the new instance of the service mesh control plane in the <istio-system> namespace.

2. Use ClusterWide mode for the service mesh control plane. For MultiTenant mode, refer to point 3 on this page. The following block must be present under the spec section of the ServiceMeshControlPlane resource:

   assignment

   gateways:
     enabled: true
     openshiftRoute:
       enabled: true
   mode: ClusterWide
   gateways:
     enabled: true
     openshiftRoute:
       enabled: true
   mode: ClusterWide
   

   To disable the OpenShift route, refer to point 4 on this page.

3. You can use MultiTenant mode for the service mesh control plane. This scenario requires you to explicitly create a service mesh member roll, as shown in the following sample:

   assignment

   apiVersion: maistra.io/v1
   kind: ServiceMeshMemberRoll
   metadata:
     name: default
     namespace: <istio-system>
   spec:
     members:
       - <uipath>
   apiVersion: maistra.io/v1
   kind: ServiceMeshMemberRoll
   metadata:
     name: default
     namespace: <istio-system>
   spec:
     members:
       - <uipath>
   

4. You also have the option to disable the OpenShift route. However, this choice comes with the additional responsibility of manually creating a route for the FQDN. For manual route creation, see the following sample:

   assignment

   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     name: uipath-route
     namespace: <istio-system>
     labels:
       app: istio-ingressgateway
       app.kubernetes.io/part-of: istio
       app.kubernetes.io/instance: <istio-system>
       maistra.io/owner-name: basic
       release: istio
       app.kubernetes.io/version: 2.6.1-1-1
       app.kubernetes.io/component: istio-ingress
       maistra-version: 2.6.1
       istio: ingressgateway
       app.kubernetes.io/managed-by: maistra-istio-operator
       maistra.io/owner: <istio-system>
       istio.io/rev: basic
       app.kubernetes.io/name: istio-ingress
   spec:
     to:
       kind: Service
       name: istio-ingressgateway
     tls:
       termination: passthrough
       insecureEdgeTerminationPolicy: Redirect
     host: <fqdn>
     port:
       targetPort: https
     alternateBackends: []
   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     name: uipath-route
     namespace: <istio-system>
     labels:
       app: istio-ingressgateway
       app.kubernetes.io/part-of: istio
       app.kubernetes.io/instance: <istio-system>
       maistra.io/owner-name: basic
       release: istio
       app.kubernetes.io/version: 2.6.1-1-1
       app.kubernetes.io/component: istio-ingress
       maistra-version: 2.6.1
       istio: ingressgateway
       app.kubernetes.io/managed-by: maistra-istio-operator
       maistra.io/owner: <istio-system>
       istio.io/rev: basic
       app.kubernetes.io/name: istio-ingress
   spec:
     to:
       kind: Service
       name: istio-ingressgateway
     tls:
       termination: passthrough
       insecureEdgeTerminationPolicy: Redirect
     host: <fqdn>
     port:
       targetPort: https
     alternateBackends: []
   

   Warning:

   Disabling the OpenShift route will lead to the following error when running the prerequisite checks:

   assignment

   ❌ [ISTIO_SERVICEMESH_VALIDATION_URL_ACCESS] error accessing the url. unexpected status code: 503
   ❌ [ISTIO_SERVICEMESH_VALIDATION_URL_ACCESS] error accessing the url. unexpected status code: 503
   

Installing a specific version of OpenShift Service Mesh​

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: servicemeshoperator
  namespace: openshift-operators
spec:
  channel: stable
  installPlanApproval: Manual
  name: servicemeshoperator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
  startingCSV: servicemeshoperator.v2.4.5
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: servicemeshoperator
  namespace: openshift-operators
spec:
  channel: stable
  installPlanApproval: Manual
  name: servicemeshoperator
  source: redhat-operators
  sourceNamespace: openshift-marketplace
  startingCSV: servicemeshoperator.v2.4.5

oc apply -f <yaml>
oc apply -f <yaml>

Installing OpenShift Service Mesh 3.x​

• You have installed or upgraded to a supported Automation Suite version. For details, refer to the Compatibily matrix.
• You have OpenShift cluster administrator permissions.
• You can access the OpenShift web console.
• You have the domain name (FQDN) used for Automation Suite routing.
• You have the OpenShift CLI (oc) installed on your workstation.

• Service Mesh Operator - Manages the lifecycle of the service mesh.
• Istio Control Plane - Provides the core data plane and control plane functionality.
• Istio CNI Plugin - Configures and enforces mesh networking rules.
• Ingress Gateway - Exposes Automation Suite applications to external traffic.
• Routes - Provide entry points for Automation Suite components and validation endpoints.

1. Install Service Mesh Operator from OperatorHub by following the instructions provided in the OpenShift Service Mesh documentation.

2. Ensure that the ingress gateway includes the correct labels. The labels must match the values that you pass as the gateway selector in the input.json file. To verify the ingress gateway label, run:

   assignment

   oc get pods -l istio=ingressgateway -n <istio-system>
   oc get pods -l istio=ingressgateway -n <istio-system>
   

3. Create the required routes by using a YAML file. The YAML file must define routes for the main Automation Suite endpoint, the apps endpoint, the insights endpoint, and the validation endpoint. For details, refer to the following examples:

   • Automation Suite endpoint:
     assignment

     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: uipath-route-https
       namespace: <istio-system>
     spec:
       host: <FQDN>
       to:
         kind: Service
         name: istio-ingressgateway # Istio Ingress gateway Service
       port:
         targetPort: https
       tls:
         termination: passthrough
         insecureEdgeTerminationPolicy: Redirect
     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: uipath-route-https
       namespace: <istio-system>
     spec:
       host: <FQDN>
       to:
         kind: Service
         name: istio-ingressgateway # Istio Ingress gateway Service
       port:
         targetPort: https
       tls:
         termination: passthrough
         insecureEdgeTerminationPolicy: Redirect
     

   • Apps endpoint:
     assignment

     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: uipath-route-apps
       namespace: <istio-system>
     spec:
       host: apps.<FQDN>
       to:
         kind: Service
         name: istio-ingressgateway # Istio Ingress gateway Service
       port:
         targetPort: https
       tls:
         termination: passthrough
         insecureEdgeTerminationPolicy: Redirect
     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: uipath-route-apps
       namespace: <istio-system>
     spec:
       host: apps.<FQDN>
       to:
         kind: Service
         name: istio-ingressgateway # Istio Ingress gateway Service
       port:
         targetPort: https
       tls:
         termination: passthrough
         insecureEdgeTerminationPolicy: Redirect
     

   • Insights endpoint:
     assignment

     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: uipath-route-insights
       namespace: <istio-system>
     spec:
       host: insights.<FQDN>
       to:
         kind: Service
         name: istio-ingressgateway # Istio Ingress gateway Service
       port:
         targetPort: https
       tls:
         termination: passthrough
         insecureEdgeTerminationPolicy: Redirect
     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: uipath-route-insights
       namespace: <istio-system>
     spec:
       host: insights.<FQDN>
       to:
         kind: Service
         name: istio-ingressgateway # Istio Ingress gateway Service
       port:
         targetPort: https
       tls:
         termination: passthrough
         insecureEdgeTerminationPolicy: Redirect
     

   • validation endpoint:
     assignment

     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: istio-validation-route
       namespace: <istio-system>
     spec:
       host: istio-validation.<FQDN> # Istio Ingress gateway Service
       to:
         kind: Service
         name: istio-ingressgateway
       port:
         targetPort: http2
     ---
     kind: Route
     apiVersion: route.openshift.io/v1
     metadata:
       name: istio-validation-route
       namespace: <istio-system>
     spec:
       host: istio-validation.<FQDN> # Istio Ingress gateway Service
       to:
         kind: Service
         name: istio-ingressgateway
       port:
         targetPort: http2
     

   This route is required for the PreReq Run. If missing, OpenShift may return the following error:

   ❌ [ISTIO_SERVICEMESH_VALIDATION_URL_ACCESS] error accessing the url. unexpected status code: 503

4. Apply the route definitions:

   assignment

   oc apply -f routes.yaml
   oc apply -f routes.yaml
   

5. Verify that the routes were created successfully:

   assignment

   oc get routes -n <istio-system>
   oc get routes -n <istio-system>
   

   You should see the following routes:

   • uipath-route-https
   • uipath-route-apps
   • uipath-route-insights
   • istio-validation-route

❌ [ISTIO_SERVICEMESH_VALIDATION_URL_ACCESS] error accessing the url. unexpected status code: 503
❌ [ISTIO_SERVICEMESH_VALIDATION_URL_ACCESS] error accessing the url. unexpected status code: 503

Providing the Istio configuration​

"ingress": {
  "gateway_selector": {
    "istio": "ingressgateway"
  },
  "ingress_gateway_secret": "istio-ingressgateway-certs",
  "namespace": "<istio-system>"
},
"ingress": {
  "gateway_selector": {
    "istio": "ingressgateway"
  },
  "ingress_gateway_secret": "istio-ingressgateway-certs",
  "namespace": "<istio-system>"
},

   oc -n <istio-system> get deploy istio-ingressgateway -o jsonpath="{.metadata.labels.istio}"; echo
   

   oc -n <istio-system> get deploy istio-ingressgateway -o jsonpath="{.metadata.labels.istio}"; echo
   

Step 2: Configuring Istio and installing the WASM plugin for routing​

Overview​

• Option A: If you cannot provide the permissions that the Automation Suite installer requires, then you must perform this step before the Automation Suite installation.
• Option B: During the Automation Suite installation. This method requires the Kubeconfig file that you use during the Automation Suite installation to have the necessary permissions. To review the permissions, refer to the Granting installation permissions section. If you can provide all the necessary permissions, then skip this step.

Prerequisites​

• Use a Linux, Windows, or macOS machine with access to the OpenShift Kubernetes API server.

• Install the OpenShift CLI client on your machine. For details, see Openshift CLI (oc).

• Install Helm 3.14 or newer on the machine from which you plan to install the WASM plugin and authenticate Helm to your private registry. To install and authenticate Helm, take the following steps:

  1. Download and install the Helm binaries on your machine. For details, see the Helm documentation.

  2. Authenticate Helm to your registry by following the instructions in the Helm documentation. Alternatively, use the following command, replacing the sample values with your actual registry URL and credentials:

     assignment

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

Configuration and installation​

1. Create an imagepullsecret in the namespace where you installed the service mesh. To create the imagepullsecret, use your typical workflow or take the following steps:

   assignment

   registry= <registry_url> #provide the registry where the UiPath images are hosted
   username= <user_name> #provide the username which will be used for the authentication
   password= <password> #provide the password which will be used for the authentication
   namespace= <namespace> #namespace where you want to create a secret
   
   oc create secret docker-registry uipathpullsecret --namespace=${namespace} \
     --docker-server=${registry} --docker-username=${username} \
     --docker-password=${password} --dry-run=client -o yaml \
     | oc apply -f -
   registry= <registry_url> #provide the registry where the UiPath images are hosted
   username= <user_name> #provide the username which will be used for the authentication
   password= <password> #provide the password which will be used for the authentication
   namespace= <namespace> #namespace where you want to create a secret
   
   oc create secret docker-registry uipathpullsecret --namespace=${namespace} \
     --docker-server=${registry} --docker-username=${username} \
     --docker-password=${password} --dry-run=client -o yaml \
     | oc apply -f -
   

2. Pull the helm chart to a local directory, <uipath-istio-configure>:

   assignment

   helm pull oci://<docker-registry>/helm/istio-configure --version <istio-configure-version> \
   --untar --untardir <uipath-istio-configure>
   helm pull oci://<docker-registry>/helm/istio-configure --version <istio-configure-version> \
   --untar --untardir <uipath-istio-configure>
   

   The following example shows the command after you replace the placeholders with actual values:

   assignment

   helm pull oci://registry.mycompany.com/helm/istio-configure --version 2024.10.0 \
   --untar --untardir uipath-istio-configure
   helm pull oci://registry.mycompany.com/helm/istio-configure --version 2024.10.0 \
   --untar --untardir uipath-istio-configure
   

3. Create a parameter values file to apply during the Helm installation of istio-configure. Use the following sample as a template for the file and the replace the <fqdn>, <cluster_type>, <pullsecret>, <registry>, and <uipath_namespace> placeholders with appropriate values:

   assignment

   fqdn: <fqdn>    #the FQDN of the Automation Suite
   gateway:
     selector:
       istio: ingressgateway
   global:
     cluster_type: <cluster_type>    # REQUIRED. Example: eks, aks, openshift
     kubernetesDistribution: <cluster_type>  # REQUIRED. Example: eks, aks, openshift
     imagePullSecret:
       name: <pullsecret>    #name of pull secret which you had create earlier
   minProtocolVersion: TLSV1_2   #TLS versions
   uipath:
     registry: <registry>    #registry url without the protocol 
   uipathServiceNamespace: <uipath_namespace>   #namespace where the uipath application is deployed
   patchIstioService: false
   wasm:
     image:
       pullSecret: <pullsecret>    #name of pull secret which you had create earlier
       registry: oci://<registry>   #registry url without the protocol
   fqdn: <fqdn>    #the FQDN of the Automation Suite
   gateway:
     selector:
       istio: ingressgateway
   global:
     cluster_type: <cluster_type>    # REQUIRED. Example: eks, aks, openshift
     kubernetesDistribution: <cluster_type>  # REQUIRED. Example: eks, aks, openshift
     imagePullSecret:
       name: <pullsecret>    #name of pull secret which you had create earlier
   minProtocolVersion: TLSV1_2   #TLS versions
   uipath:
     registry: <registry>    #registry url without the protocol 
   uipathServiceNamespace: <uipath_namespace>   #namespace where the uipath application is deployed
   patchIstioService: false
   wasm:
     image:
       pullSecret: <pullsecret>    #name of pull secret which you had create earlier
       registry: oci://<registry>   #registry url without the protocol
   

4. Install istio-configure in the Istio namespace, using Helm. In the following command, replace the <istio_namespace> placeholder with the namespace where Istio is installed, and the <path_to_the_values_yaml> with the location of the YAML file containing the parameter values:

   assignment

   helm upgrade --debug --install --wait custom-istio-configure \
     uipath-istio-configure/istio-configure --version 2024.10.0 \
     --namespace <istio_namespace> -f <path_to_the_values.yaml>
   helm upgrade --debug --install --wait custom-istio-configure \
     uipath-istio-configure/istio-configure --version 2024.10.0 \
     --namespace <istio_namespace> -f <path_to_the_values.yaml>
   

5. If you use a registry that is not signed by a known authority, you must add the WASM_INSECURE_REGISTRIES environment variable to the istio-ingressgateway deployment, so that Istio can pull the image that the WASM plugin uses. To add the environment variable, run the following command:

   assignment

   oc -n <istio-system> patch deployment istio-ingressgateway --type="json" --patch='[{"op":"add", "path": "/spec/template/spec/containers/0/env/-", "value": {"name": "WASM_INSECURE_REGISTRIES", "value": "customer-registry.com"}}]'
   oc -n <istio-system> patch deployment istio-ingressgateway --type="json" --patch='[{"op":"add", "path": "/spec/template/spec/containers/0/env/-", "value": {"name": "WASM_INSECURE_REGISTRIES", "value": "customer-registry.com"}}]'
   

6. Add istio-configure to the exclude_components section in your input.json file.

7. Create certificate secrets using the name provided in ingress.ingress_gateway_secret within the <istio-system> namespace.

Step 3: Configuring Istio for multiple installations in a single cluster​

 fqdn: <fqdn-for-second-installation>    #the FQDN of the Automation Suite
gateway:
  selector:
    istio: ingressgateway
global:
  cluster_type: <cluster_type>    # REQUIRED. Example: eks, aks, openshift
  imagePullSecret:
    name: <pullsecret>    #name of pull secret which you had create earlier
minProtocolVersion: TLSV1_2   #TLS versions
uipath:
  registry: <registry>    #registry url without the protocol 
uipathServiceNamespace: <second-installation-namespace>   #namespace where the uipath application is deployed
patchIstioService: false
wasm:
  image:
    pullSecret: <pullsecret>    #name of pull secret which you had create earlier
    registry: oci://<registry>   #registry url without the protocol
 fqdn: <fqdn-for-second-installation>    #the FQDN of the Automation Suite
gateway:
  selector:
    istio: ingressgateway
global:
  cluster_type: <cluster_type>    # REQUIRED. Example: eks, aks, openshift
  imagePullSecret:
    name: <pullsecret>    #name of pull secret which you had create earlier
minProtocolVersion: TLSV1_2   #TLS versions
uipath:
  registry: <registry>    #registry url without the protocol 
uipathServiceNamespace: <second-installation-namespace>   #namespace where the uipath application is deployed
patchIstioService: false
wasm:
  image:
    pullSecret: <pullsecret>    #name of pull secret which you had create earlier
    registry: oci://<registry>   #registry url without the protocol

 helm upgrade --debug --install --wait <namespace>-custom-istio-configure \
  uipath-istio-configure/istio-configure --version 2024.10.0 \
  --namespace <istio_namespace> -f <path_to_the_values.yaml>
 helm upgrade --debug --install --wait <namespace>-custom-istio-configure \
  uipath-istio-configure/istio-configure --version 2024.10.0 \
  --namespace <istio_namespace> -f <path_to_the_values.yaml>