Installing and configuring the service mesh

Install and configure Istio service mesh or OpenShift Service Mesh for Automation Suite networking.

Important:

If you grant the Automation Suite installer cluster-admin privileges - or the required write permissions together with the required cluster roles - the installer configures Istio and installs the WASM plugin for routing automatically. In that case, you can skip Step 2: Configuring Istio and installing the WASM plugin for routing and Step 3: Configuring Istio for multiple installations in a single cluster. Perform these steps manually only if you cannot grant the installer those privileges.

Automation Suite requires the Istio service mesh for ingress and networking.

Red Hat provides OpenShift Service Mesh, which relies on Istio internally.

The service mesh installation and configuration is a multi-step process. Which of the steps you must perform depends on whether or not you can grant the Automation Suite installer admin privileges over your cluster. For details, refer to the following table:

Step	Admin privileges	No admin privileges
Step 1: Installing the service mesh	Required	Required
Step 2: Configuring Istio and installing the WASM plugin for routing	Not required	Required
Step 3: Configuring Istio for multiple installations in a single cluster	Not required	Required

Step 1: Installing the service mesh

Note:

Before selecting an installation procedure, review the OpenShift Service Mesh compatibility matrix to confirm which OSSM versions are supported for your Automation Suite on OpenShift version.

To install OpenShift Service Mesh, refer to the procedure that applies to the version you use:

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

Note:

Automation Suite does not require applications such as Kiali and Jaeger. However, you can use them at your discretion.

UiPath® has no opinion on configuring the Service Mesh Operator to run on any node.

Installing OpenShift Service Mesh 2.x

To install OpenShift Service Mesh 2.x, follow the instructions in the OpenShift Service Mesh documentation.

To create the OpenShift Service Mesh Control Plane, follow the instructions in the OpenShift Service Mesh Control Plane documentation. Make sure that you also take the following steps:

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:

    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:

   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, refer to the following sample:

   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:

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

Installing a specific version of OpenShift Service Mesh

Use a YAML file to install a specific version of OpenShift Service Mesh (OSSM). The following example file installs OSSM version 2.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

If you plan to install a different OSSM version, replace servicemeshoperator.v2.4.5 with the correct value for your version in the YAML file. For example, to install OSSM version 2.5.0, enter servicemeshoperator.v2.5.0.

To install OSSM, run the following command:

oc apply -f <yaml>

Replace the <yaml> placeholder in the sample command with the name of your YAML file.

Important:

After you install OSSM, you must manually approve the installation.

In the OpenShift console, go to Operators > Installed Operators > Servicemeshoperator > 1 requires approval > Preview Install Plan > Approve.

Installing OpenShift Service Mesh 3.x

Before you install OpenShift Service Mesh 3.x, make sure that:

• Your OpenShift Service Mesh and Automation Suite versions are compatible. For the supported combinations, refer to the Compatibility 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.

A complete OpenShift Service Mesh 3.x setup for Automation Suite relies on the following components. The Service Mesh Operator does not provision all of them automatically, so make sure each one is present in the cluster before you install Automation Suite:

• Service Mesh Operator - Manages the lifecycle of the service mesh. You install it from OperatorHub.
• Istio control plane - Provides the core control plane and data plane functionality. The operator provisions it after you create the Istio resource.
• Istio CNI plugin - Configures and enforces mesh networking rules. The operator provisions it after you create the IstioCNI resource.
• Ingress gateway - Exposes Automation Suite applications to external traffic. You must deploy it yourself; the operator does not create it automatically.
• Routes - Provide entry points for Automation Suite components and the validation endpoint. You must create these OpenShift Route objects yourself, as described in the steps below.

To install OpenShift Service Mesh 3.x, follow the instructions for installing the operator from OperatorHub by using the OpenShift web console. For details, refer to the OpenShift Service Mesh documentation.

Make sure that you also take the following steps:

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:

   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:

     ---
     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:

     ---
     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:

     ---
     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:

     ---
     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:

   oc apply -f routes.yaml
   

5. Verify that the routes were created successfully:

   oc get routes -n <istio-system>
   

   You should see the following routes:

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

6. If your Istio CR configures meshConfig.discoverySelectors, label every Automation Suite namespace to match the selector value. For example, if the selector is istio-discovery=enabled:

   oc label namespace <uipath> istio-discovery=enabled --overwrite
   

   Without this label, istiod cannot recognize the namespace as a mesh member or write the istio-ca-root-cert ConfigMap into it. Repeat for <uipath>-installer, <uipath>-check, <uipath>-argocd, and any other Automation Suite namespaces.

Warning:

The validation route is required. If the route is missing, the prerequisite checks fail with:

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

Migrating from OpenShift Service Mesh 2.x to 3.x

Before starting the migration process, make sure you have installed or upgraded to a supported Automation Suite version. For details, refer to the Compatibily matrix.

To migrate from OpenShift Service Mesh 2.x to 3.x, follow the steps provided in the official Red Hat migration guide.

After completing the migration, review the OpenShift Service Mesh 3.x installation procedure to ensure that all required configuration steps, such as gateway labeling, route creation, and validation endpoint setup, are in place.

Providing the Istio configuration

To provide the Istio configuration, you must set the following parameters in the input.json file:

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

The following table describes the Istio configuration parameters:

Parameter	Value
ingress.gateway_selector.istio	This is the default label used internally by Automation Suite. However, your environment may use a different label for the Istio ingress gateway depending on how the cluster was configured. The default value is ingressgateway.
ingress.ingress_gateway_secret	The name of the secret that contains the certificate files. The default value is istio-ingressgateway-certs.
ingress.namespace	The namespace where you have installed the service mesh.
ingress.istio_gateway_service_name*	The name of the Istio ingress gateway service. The default value is istio-ingressgateway.

* Available starting from Automation Suite 2.2510.2.

To check the label used by your Istio ingress gateway, run the following command:

oc -n <istio-system> get deploy istio-ingressgateway -o jsonpath="{.spec.selector.matchLabels.istio}"; echo

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

Overview

Important:

This step requires admin privileges for installation in the Istio namespace.

There are two ways to perform the installation:

• 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

Before you configure Istio and install the WASM plugin for routing, you must meet the following 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, refer to 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, refer to 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:

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

Configuration and installation

To configure Istio and install the WASM plugin for routing, take the following steps:

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:

   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. Create the certificate Secret in the <istio-system> namespace. The Secret name must match the value of ingress.ingress_gateway_secret in your input.json (the default is istio-ingressgateway-certs), and it must contain three keys: tls.crt, tls.key, and ca.crt. The ca.crt key is required when your TLS certificate is signed by a private or self-signed Certificate Authority.

   The corresponding ingress block in input.json is passed as follows:

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

   Create the Secret using one of the following methods. Replace the placeholder certificate paths and values with your own.

   • Using oc (from certificate files):

     oc create secret generic istio-ingressgateway-certs \
       --namespace <istio-system> \
       --from-file=tls.crt=<path-to-tls.crt> \
       --from-file=tls.key=<path-to-tls.key> \
       --from-file=ca.crt=<path-to-ca.crt>
     

   • Using a YAML manifest (the values are base64-encoded):

     apiVersion: v1
     kind: Secret
     metadata:
       name: istio-ingressgateway-certs
       namespace: <istio-system>
     type: Opaque
     data:
       tls.crt: <base64-encoded-tls.crt>
       tls.key: <base64-encoded-tls.key>
       ca.crt: <base64-encoded-ca.crt>
     

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>, <pullsecret>, <registry>, and <uipath_namespace> placeholders with appropriate values:

   fqdn: <fqdn>    #the FQDN of the Automation Suite
   gateway:
     selector:
       istio: ingressgateway
   global:
     cluster_type: openshift    # REQUIRED
     kubernetesDistribution: openshift  # REQUIRED
     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
   istioGatewayServiceName: "istio-ingressgateway"
   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 directly from the OCI registry, using Helm. In the following command, replace the <docker-registry> placeholder with your registry, <istio-configure-version> with the chart version, <istio_namespace> with the namespace where Istio is installed, and <path_to_the_values.yaml> with the location of the parameter values file:

   helm upgrade --debug --install --wait custom-istio-configure \
     oci://<docker-registry>/helm/istio-configure --version <istio-configure-version> \
     --namespace <istio_namespace> -f <path_to_the_values.yaml>
   

   Set <istio-configure-version> to the version that matches your Automation Suite release. The available versions are 2.2510.0, 2.2510.1, 2.2510.2, and 2.2510.3. You can also find the exact value in the versions.json file included with your downloaded installation packages (the istio-configure entry).

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:

   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. For details, refer to Configuring input.json.

7. Verify that the configuration completed successfully by checking the pods in the <istio-system> namespace:

   oc get pods -n <istio-system>
   

   The WASM plugin pods should be in the Running or Completed state.

Note:

If you update the FQDN after installation, you must reconfigure Istio and the WASM plugin, unless the Automation Suite installer has administrative privileges. To reconfigure, you must take the following steps:

1. Update the parameter values file mentioned in Step 3 with the new FQDN.
2. Repeat all the steps for configuring Istio and installing the WASM plugin for routing.

Optional: installing istio-configure with a single script

Complete steps 1 and 2 first (create the image pull secret and the certificate Secret). Then, instead of running steps 3 and 4 individually, you can fill in the variables at the top of the following script and run it. The script generates the parameter values file and installs istio-configure directly from the OCI registry in one step. After it completes, continue from step 5.

#!/usr/bin/env bash
set -euo pipefail

# ---- Fill in these values ----
REGISTRY="registry.mycompany.com"      # registry host, without protocol
ISTIO_CONFIGURE_VERSION="2.2510.0"     # available: 2.2510.0, 2.2510.1, 2.2510.2, 2.2510.3 (match your Automation Suite version)
FQDN="autosuite.mycompany.com"         # Automation Suite FQDN
PULL_SECRET="uipathpullsecret"         # pull secret created earlier
UIPATH_NAMESPACE="uipath"              # namespace where Automation Suite is deployed
ISTIO_NAMESPACE="istio-system"         # namespace where Istio is installed
# ------------------------------

cat > istio-configure-values.yaml <<EOF
fqdn: ${FQDN}
gateway:
  selector:
    istio: ingressgateway
global:
  cluster_type: openshift
  kubernetesDistribution: openshift
  imagePullSecret:
    name: ${PULL_SECRET}
minProtocolVersion: TLSV1_2
uipath:
  registry: ${REGISTRY}
uipathServiceNamespace: ${UIPATH_NAMESPACE}
patchIstioService: false
istioGatewayServiceName: "istio-ingressgateway"
wasm:
  image:
    pullSecret: ${PULL_SECRET}
    registry: oci://${REGISTRY}
EOF

helm upgrade --debug --install --wait custom-istio-configure \
  "oci://${REGISTRY}/helm/istio-configure" --version "${ISTIO_CONFIGURE_VERSION}" \
  --namespace "${ISTIO_NAMESPACE}" -f istio-configure-values.yaml

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

To configure Istio for multiple Automation Suite installations in a single OpenShift cluster, you must add multiple custom-istio-configure which contains the FQDN and resources for different Automation Suite instances. You must fill in the helm values that correspond to your second or any subsequent installation.

You must to create different istio-configure values for each installation:

 fqdn: <fqdn-for-second-installation>    #the FQDN of the Automation Suite
gateway:
  selector:
    istio: ingressgateway
global:
  cluster_type: openshift    # REQUIRED
  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

You must change the name of custom-istio-configure to <namespace>-custom-istio-configure. This must be installed on the replicated namespace where second installation is performed.

 helm upgrade --debug --install --wait <namespace>-custom-istio-configure \
  oci://<docker-registry>/helm/istio-configure --version <istio-configure-version> \
  --namespace <istio_namespace> -f <path_to_the_values.yaml>