Installing and configuring the GitOps tool

Install and configure GitOps tool for managing Automation Suite deployments on OpenShift.

Note:

Before proceeding with the OpenShift GitOps Operator installation and configuration, you must install OpenShift Service Mesh and provide all the required permissions to the uipathadmin service account.

For the service mesh installation and configuration instructions, refer to Installing and configuring the service mesh.

For the installation permissions, refer to Granting installation permissions.

You can deploy Automation Suite using either an OpenShift GitOps Operator instance dedicated to the UiPath® applications or a shared OpenShift GitOps Operator instance, if it is already installed and available on your cluster.

We recommend using a dedicated OpenShift GitOps Operator instance to install the Automation Suite applications. This method requires minimum permissions to the other namespaces and cluster resources.

For installation and access details, refer to the following sections:

• Provisioning a dedicated GitOps instance
• Configuring a shared GitOps instance

Provisioning a dedicated GitOps instance

Note:

We recommend using a namespace that is different from <uipath> for ArgoCD.

If you use Openshift GitOps version 1.15 or higher and install a dedicated instance of ArgoCD within the <uipath> namespace, the ArgoCD UI will not be accessible due to the network policies in the <uipath> namespace added by the Service Mesh Control Plane. To address this, you must add a network policy, as shown in the following example, to allow the ingress pods to reach the ArgoCD-server pods in the <uipath> namespace.

kind: NetworkPolicy
apiVersion: networking.k8s.io/v1
metadata:
  name: allow-argocd
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: argocd-server
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              network.openshift.io/policy-group: ingress
  policyTypes:
    - Ingress

To provision a dedicated OpenShift GitOps Operator instance, take the following steps:

1. If the <argocd> namespace does not already exist, run the following commands to create it:

   oc get namespace <argocd> || oc new-project <argocd>
   oc project <argocd>
   

2. Install the OpenShift GitOps Operator by following the instructions in Installing OpenShift GitOps.

3. Create a new ArgoCD instance by following the instructions in Setting up a new ArgoCD instance.

   Note:

   In the spec section described in Enabling replicas for Argo CD server and repo server, you must add the following line:

   server.route.enabled: true
   

4. If you use OpenShift Service Mesh 2.x, patch the ArgoCD deployment so that the service mesh exposes it through an OpenShift route. Skip this step on OpenShift Service Mesh 3.x, where the maistra.io/expose-route label has no effect.

   oc -n <argocd> patch deployment argocd-server \
     -p '{"spec":{"template":{"metadata":{"labels":{"maistra.io/expose-route":"true"}}}}}'
   

5. Create a role so that ArgoCD can manage limit ranges.

   Before Automation Suite 2.2510.3, the platform Helm chart shipped a LimitRange object that assigned default resource limits in the <uipath> namespace, so the ArgoCD application controller needed permissions to create and manage it. Starting with 2.2510.3, this LimitRange object was removed from the chart, and the controller only needs the delete verb to prune the LimitRange created by an earlier version during synchronization.

   To create the role, take the following steps:

   1. Save the role configuration that matches your Automation Suite version as a YAML file:
      • Automation Suite 2.2510.3 and later (only the delete verb is required):

        kind: Role
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: limit-range-manager
          namespace: <uipath>
        rules:
          - apiGroups: [""]
            resources: ["limitranges"]
            verbs: ["delete"]
        

      • Versions before 2.2510.3:

        kind: Role
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: limit-range-manager
          namespace: <uipath>
        rules:
          - apiGroups: [""]
            resources: ["limitranges"]
            verbs: ["get", "watch", "list", "patch", "update", "create"]
        

   2. Apply the configuration by running the following command. Make sure to replace the <file_name.yaml> placeholder with the actual name of the YAML file:

      oc apply -f <file_name.yaml>
      

6. Bind the limit-range-manager role to the argocd service account:

   oc -n <uipath> create rolebinding limit-range-manager-binding --role=limit-range-manager --serviceaccount=<argocd>:argocd-argocd-application-controller
   

7. If you enabled TaaS, create a role that grants the ArgoCD application controller write verbs on the pods/log subresource. The TaaS pre-install hook creates a role that includes these verbs, and Kubernetes RBAC escalation prevention requires the controller to hold them itself before it can grant them. To create the role, take the following steps:

   1. Save the following role configuration as a YAML file:

      kind: Role
      apiVersion: rbac.authorization.k8s.io/v1
      metadata:
        name: argocd-pod-log-writer
        namespace: <uipath>
      rules:
        - apiGroups: [""]
          resources: ["pods/log"]
          verbs: ["create", "update", "patch", "delete"]
      

   2. Apply the configuration by running the following command. Make sure to replace the <file_name.yaml> placeholder with the actual name of the YAML file:

      oc apply -f <file_name.yaml>
      

   3. Bind the argocd-pod-log-writer role to the argocd service account:

      oc -n <uipath> create rolebinding argocd-pod-log-writer-binding --role=argocd-pod-log-writer --serviceaccount=<argocd>:argocd-argocd-application-controller
      

8. If you enabled Automation Suite Robots, you must enable cluster-wide mode for ArgoCD by taking the following steps:

   Important:

   Cluster-wide mode is required because, by default, the Automation Suite Robots chart deploys a ClusterRole and ClusterRoleBinding that a namespaced ArgoCD instance cannot manage. If you are installing with namespace-scoped permissions only, you can skip this step by setting an explicit asrobots.concurrency_limit in input.json; the chart then deploys no cluster-scoped resources. For details, refer to Granting installation permissions without cluster roles.

   1. In <openshift-gitops>, edit the openshift-gitops-operator subscription resource to include the following environment variable:

      ARGOCD_CLUSTER_CONFIG_NAMESPACES: <argocd>
      

   2. Follow the instructions in Using an Argo CD instance to manage cluster-scoped resources.

9. You must ensure that the ArgoCD instance can manage the <uipath> namespace if the <uipath> namespace is not the same as the <argocd> namespace:

   oc label namespace <uipath> argocd.argoproj.io/managed-by=<argocd>
   

   In this command, <argocd> is the name of the namespace where you deployed the dedicated ArgoCD instance.

   After you apply the configuration, restart the ArgoCD application-controler (statefulset) and server (deployment).

10. You must perform the following steps only if the <uipath> namespace is not the same as the <argocd> namespace. Create a role to manage the applications in the <argocd> namespace. To create the role, take the following steps:

    1. Save the following role configuration as a YAML file:

       apiVersion: rbac.authorization.k8s.io/v1
       kind: Role
       metadata:
         name: uipath-application-manager
         namespace: <argocd>
       rules:
       - apiGroups:
         - argoproj.io
         resources:
         - applications
         verbs: ["get", "watch", "list", "patch", "update", "create", "delete"]
       

    2. Apply the configuration by running the following command. Make sure to replace the <file_name.yaml> placeholder with the actual name of the YAML file:

       oc apply -f <file_name.yaml>
       

11. Bind the uipath-application-manager role to the uipathadmin service account:

    oc project <argocd>
    oc create rolebinding uipath-application-manager \
      --role=uipath-application-manager --serviceaccount=<uipath>:uipathadmin
    

12. As a cluster administrator, create the helm-credentials repository secret in the <argocd> namespace. This is an ArgoCD repository secret that holds the Helm registry connection details, and ArgoCD reads it to pull the Automation Suite charts.

    Important:

    How this secret is managed depends on your Automation Suite version:

    • Automation Suite 2.2510.4 and later: the secret is owned by you. uipathctl does not manage it and requires no access to it or to the <argocd> namespace — the uipathadmin service account needs no permissions at all there apart from managing ArgoCD applications, which you granted in the previous step. Skip the next step.
    • Automation Suite 2.2510.3: you create the secret, but uipathctl still updates it on every run, so uipathadmin needs get, update, and patch on it. Complete the next step with the 2.2510.3 role.
    • Versions before 2.2510.3: uipathctl creates and manages the secret itself, so you can skip creating it. Complete the next step with the role for versions before 2.2510.3.

    Whenever you created the secret, you must also keep it up to date: if the Helm registry credentials change, update the secret yourself, otherwise ArgoCD stops being able to pull the charts.

    apiVersion: v1
    kind: Secret
    metadata:
      name: helm-credentials
      namespace: <argocd>
      labels:
        argocd.argoproj.io/secret-type: repository
    type: Opaque
    stringData:
      name: uipath-helm
      url: <helm-registry-url>
      type: helm
      enableOCI: "true"
      username: <registry-username>
      password: <registry-password>
    

    The stringData values are provided in plain text. For an open registry such as registry.uipath.com, omit the username and password keys so that ArgoCD connects anonymously. Leaving them blank makes ArgoCD attempt a login and fail with a 401 error. Alternatively, create the same secret with the CLI:

    oc -n <argocd> create secret generic helm-credentials \
      --from-literal=name=uipath-helm \
      --from-literal=url=<helm-registry-url> \
      --from-literal=type=helm \
      --from-literal=enableOCI=true \
      --from-literal=username=<registry-username> \
      --from-literal=password=<registry-password>
    oc -n <argocd> label --overwrite secret helm-credentials argocd.argoproj.io/secret-type=repository
    

13. Automation Suite 2.2510.3 and earlier only. These versions write to the helm-credentials secret and look the <argocd> namespace up, so uipathadmin needs access to both. Skip this step on 2.2510.4 and later.

    1. Save the role configuration that matches your Automation Suite version as a YAML file:
       • Automation Suite 2.2510.3, scoped to the secret you created in the previous step:

         apiVersion: rbac.authorization.k8s.io/v1
         kind: Role
         metadata:
           name: argo-secret-role
           namespace: <argocd>
         rules:
           - apiGroups: [""]
             resources: ["secrets"]
             resourceNames: ["helm-credentials"]
             verbs: ["get", "update", "patch"]
         

       • Versions before 2.2510.3:

         apiVersion: rbac.authorization.k8s.io/v1
         kind: Role
         metadata:
           name: argo-secret-role
           namespace: <argocd>
         rules:
           - apiGroups: ["rbac.authorization.k8s.io"]
             resources: ["roles", "rolebindings"]
             verbs: ["get", "watch", "list", "patch", "update", "create"]
           - apiGroups: [""]
             resources: ["secrets"]
             verbs: ["get", "watch", "list", "patch", "update", "create"]
         

    2. Apply the configuration by running the following command. Make sure to replace the <file_name.yaml> placeholder with the actual name of the YAML file:

       oc apply -f <file_name.yaml>
       

    3. Bind the argo-secret-role role and the namespace-reader role to the uipathadmin service account:

       oc project <argocd>
       oc create rolebinding secret-binding \
         --role=argo-secret-role --serviceaccount=<uipath>:uipathadmin
       oc create rolebinding namespace-reader-rolebinding \
         --clusterrole=namespace-reader-clusterrole --serviceaccount=<uipath>:uipathadmin
       

Accessing the dedicated ArgoCD instance

To access ArgoCD, take the following steps:

1. Get the host URL:

   oc get routes argocd-server -n <argocd> -o jsonpath={.spec.host}; echo
   

2. To log in, use admin as the username and run the following command to get the password:

   oc -n <argocd> get secrets argocd-cluster \
     -o "jsonpath={.data['admin\.password']}" | base64 -d; echo
   

Configuring the private Helm repository and certificates in ArgoCD

To configure the Helm repository in ArgoCD, take the following steps:

1. Log in to ArgoCD.
2. Navigate to Settings > Repositories > +CONNECT REPO.
3. Use VIA HTTPS for the connection method.
4. Select Helm as the type.
5. Provide a name.
6. Choose default as the project.
7. Provide the repository URL, username, password, and certificate info.
   Important:

   When adding the TLS client certificate on the +CONNECT REPO page, the TLS client certificate key becomes a mandatory field. To configure the registry certificate without the TLS client certificate key, take the following steps:

   1. Navigate to Settings > Repository certificates and known hosts > +ADD TLS CERTIFICATE.
   2. Add the repository name and TLS certificate in PEM format.
8. Enable the OCI checkbox.
9. Select Connect.
10. Make sure that the connection status is Successful.

Configuring a shared GitOps instance

If your platform team has not already provisioned the shared OpenShift GitOps Operator instance, take the following installation and configuration steps:

1. Create the <uipath> namespace:

   oc get namespace <uipath> || oc new-project <uipath>
   oc project <uipath>
   

2. Install the OpenShift GitOps Operator by following the instructions in Installing OpenShift GitOps. This installation comes with the default ArgoCD instance, named openshift-gitops, in the <openshift-gitops> namespace.

3. Enable cluster-wide mode for ArgoCD by taking the following steps:

   1. In <openshift-gitops>, edit the openshift-gitops-operator subscription resource to include the following environment variable:

      ARGOCD_CLUSTER_CONFIG_NAMESPACES: <openshift-gitops>
      

   2. Follow the instructions in Using an ArgoCD instance to manage cluster-scoped resources.

4. Make sure that the openshift-gitops ArgoCD instance can manage the <uipath> namespace:

   oc label namespace <uipath> argocd.argoproj.io/managed-by=openshift-gitops
   

   After you apply the configuration, restart the ArgoCD openshift-gitops-application-controller (statefulset) and openshift-gitops-server (deployment).

5. If you use OpenShift Service Mesh 2.x, patch the ArgoCD deployment so that the service mesh exposes it through an OpenShift route. Skip this step on OpenShift Service Mesh 3.x, where the maistra.io/expose-route label has no effect.

   oc -n <uipath> patch deployment argocd-server \
     -p '{"spec":{"template":{"metadata":{"labels":{"maistra.io/expose-route":"true"}}}}}'
   

6. Create an ArgoCD project for the UiPath® application:

   apiVersion: argoproj.io/v1alpha1
   kind: AppProject
   metadata:
     name: uipath
     namespace: <openshift-gitops>
   spec:
     description: Appproject to managed and deploy uipath applications
     clusterResourceWhitelist:
       - group: '*'
         kind: '*'
     destinations:
       - namespace: <uipath>
         server: https://kubernetes.default.svc
       - namespace: <istio-system>
         server: https://kubernetes.default.svc
     sourceNamespaces:
       - <openshift-gitops>
     sourceRepos:
       - '*'
   

7. Create a role so that ArgoCD can manage limit ranges.

   Before Automation Suite 2.2510.3, the platform Helm chart shipped a LimitRange object that assigned default resource limits in the <uipath> namespace, so the ArgoCD application controller needed permissions to create and manage it. Starting with 2.2510.3, this LimitRange object was removed from the chart, and the controller only needs the delete verb to prune the LimitRange created by an earlier version during synchronization.

   To create the role, take the following steps:

   1. Save the role configuration that matches your Automation Suite version as a YAML file:
      • Automation Suite 2.2510.3 and later (only the delete verb is required):

        kind: Role
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: limit-range-manager
          namespace: <uipath>
        rules:
          - apiGroups: [""]
            resources: ["limitranges"]
            verbs: ["delete"]
        

      • Versions before 2.2510.3:

        kind: Role
        apiVersion: rbac.authorization.k8s.io/v1
        metadata:
          name: limit-range-manager
          namespace: <uipath>
        rules:
          - apiGroups: [""]
            resources: ["limitranges"]
            verbs: ["get", "watch", "list", "patch", "update", "create"]
        

   2. Apply the configuration by running the following command. Make sure to replace the <file_name.yaml> placeholder with the actual name of the YAML file:

      oc apply -f <file_name.yaml>
      

8. Bind the limit-range-manager role to the argocd service account:

   oc -n <uipath> create rolebinding limit-range-manager-binding --role=limit-range-manager --serviceaccount=<openshift-gitops>:openshift-gitops-argocd-application-controller
   

9. Create a role to manage the applications in the <openshift-gitops> namespace:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: uipath-application-manager
     namespace: <openshift-gitops>
   rules:
   - apiGroups:
     - argoproj.io
     resources:
     - applications
     verbs: ["get", "watch", "list", "patch", "update", "create"]
   

10. Bind the uipath-application-manager role to the uipathadmin service account:

    oc project <openshift-gitops>
    oc create rolebinding uipath-application-manager \
      --role=uipath-application-manager --serviceaccount=<uipath>:uipathadmin
    

11. As a cluster administrator, create the helm-credentials repository secret in the <openshift-gitops> namespace. This is an ArgoCD repository secret that holds the Helm registry connection details, and ArgoCD reads it to pull the Automation Suite charts.

    Important:

    How this secret is managed depends on your Automation Suite version:

    • Automation Suite 2.2510.4 and later: the secret is owned by you. uipathctl does not manage it and requires no access to it or to the <openshift-gitops> namespace — the uipathadmin service account needs no permissions at all there apart from managing ArgoCD applications, which you granted in the previous step. Skip the next step.
    • Automation Suite 2.2510.3: you create the secret, but uipathctl still updates it on every run, so uipathadmin needs get, update, and patch on it. Complete the next step with the 2.2510.3 role.
    • Versions before 2.2510.3: uipathctl creates and manages the secret itself, so you can skip creating it. Complete the next step with the role for versions before 2.2510.3.

    Whenever you created the secret, you must also keep it up to date: if the Helm registry credentials change, update the secret yourself, otherwise ArgoCD stops being able to pull the charts.

    apiVersion: v1
    kind: Secret
    metadata:
      name: helm-credentials
      namespace: <openshift-gitops>
      labels:
        argocd.argoproj.io/secret-type: repository
    type: Opaque
    stringData:
      name: uipath-helm
      url: <helm-registry-url>
      type: helm
      enableOCI: "true"
      username: <registry-username>
      password: <registry-password>
    

    The stringData values are provided in plain text. For an open registry such as registry.uipath.com, omit the username and password keys so that ArgoCD connects anonymously. Leaving them blank makes ArgoCD attempt a login and fail with a 401 error. Alternatively, create the same secret with the CLI:

    oc -n <openshift-gitops> create secret generic helm-credentials \
      --from-literal=name=uipath-helm \
      --from-literal=url=<helm-registry-url> \
      --from-literal=type=helm \
      --from-literal=enableOCI=true \
      --from-literal=username=<registry-username> \
      --from-literal=password=<registry-password>
    oc -n <openshift-gitops> label --overwrite secret helm-credentials argocd.argoproj.io/secret-type=repository
    

12. Automation Suite 2.2510.3 and earlier only. These versions write to the helm-credentials secret and look the <openshift-gitops> namespace up, so uipathadmin needs access to both. Skip this step on 2.2510.4 and later.

    1. Save the role configuration that matches your Automation Suite version as a YAML file:
       • Automation Suite 2.2510.3, scoped to the secret you created in the previous step:

         apiVersion: rbac.authorization.k8s.io/v1
         kind: Role
         metadata:
           name: argo-secret-role
           namespace: <openshift-gitops>
         rules:
           - apiGroups: [""]
             resources: ["secrets"]
             resourceNames: ["helm-credentials"]
             verbs: ["get", "update", "patch"]
         

       • Versions before 2.2510.3:

         apiVersion: rbac.authorization.k8s.io/v1
         kind: Role
         metadata:
           name: argo-secret-role
           namespace: <openshift-gitops>
         rules:
           - apiGroups: ["rbac.authorization.k8s.io"]
             resources: ["roles", "rolebindings"]
             verbs: ["get", "watch", "list", "patch", "update", "create"]
           - apiGroups: [""]
             resources: ["secrets"]
             verbs: ["get", "watch", "list", "patch", "update", "create"]
         

    2. Apply the configuration by running the following command. Make sure to replace the <file_name.yaml> placeholder with the actual name of the YAML file:

       oc apply -f <file_name.yaml>
       

    3. Bind the argo-secret-role role and the namespace-reader role to the uipathadmin service account:

       oc project <openshift-gitops>
       oc create rolebinding secret-binding \
         --role=argo-secret-role --serviceaccount=<uipath>:uipathadmin
       oc create rolebinding namespace-reader-rolebinding \
         --clusterrole=namespace-reader-clusterrole --serviceaccount=<uipath>:uipathadmin
       

In addition to completing the steps to configure the shared ArgoCD instance for the Automation Suite installation, you must add the following parameters to the input.json file:

  "argocd": {
    "project": "<uipath>"
  },

Accessing the shared ArgoCD instance

To access ArgoCD, take the following steps:

1. Get the host URL by running the following commands:

   oc get routes openshift-gitops-server -n <openshift-gitops> -o jsonpath={.spec.host}; echo
   

2. To log in, use admin as the username and run the following command to get the password:

   oc -n <openshift-gitops> get secrets openshift-gitops-cluster \
     -o "jsonpath={.data['admin\.password']}" | base64 -d; echo
   

Configuring the private Helm repository and certificates in ArgoCD

To configure the Helm repository in ArgoCD, take the following steps:

1. Log in to ArgoCD.
2. Navigate to Settings > Repositories > +CONNECT REPO.
3. Use VIA HTTPS for the connection method.
4. Select Helm as the type.
5. Provide a name.
6. Choose uipath as the project. uipath is the name of the ArgoCD project you created for the UiPath® application.
7. Provide the repository URL, username, password, and certificate info.
   Important:

   When adding the TLS client certificate on the +CONNECT REPO page, the TLS client certificate key becomes a mandatory field. To configure the registry certificate without the TLS client certificate key, take the following steps:

   1. Navigate to Settings > Repository certificates and known hosts > +ADD TLS CERTIFICATE.
   2. Add the repository name and TLS certificate in PEM format.
8. Enable the OCI checkbox.
9. Select Connect.
10. Make sure that the connection status is Successful.

Configuring ArgoCD for multiple installations in a single cluster

To configure ArgoCD for multiple Automation Suite installations in a single OpenShift cluster, follow these steps:

1. Check if all the services of ArgoCD are up and running. You can run the following command to monitor all the pods:

   oc get pods -n <argocd>
   

2. Once all services are up and running, you can use the following command sequentially to patch ArgoCD's permissions. This allows ArgoCD to manage different application namespaces where Automation Suite is installed:

   oc patch appprojects.argoproj.io default -n <argocd> --type='merge' -p '{"spec": {"sourceNamespaces": ["*"]}}'
   oc patch configmaps argocd-cmd-params-cm -n <argocd> --type='merge' -p '{"data": {"application.namespaces": "*"}}'
   oc rollout restart -n <argocd> deployment argocd-server
   oc rollout restart -n <argocd> statefulset argocd-application-controller