Orchestrator on OpenShift

7 minute read

Installing the Orchestrator is facilitated through a Helm chart that is responsible for installing all of the Orchestrator components. The Orchestrator is based on the SonataFlow and the Serverless Workflow technologies to design and manage the workflows. The Orchestrator plugins are deployed on Red Hat Developer Hub instance, serves as the frontend. To utilize Backstage capabilities, the Orchestrator imports software templates designed to ease the development of new workflows and offers an opinionated method for managing their lifecycle by including CI/CD resources as part of the template.

Orchestrator Helm Chart

Deploy the Orchestrator solution suite using this Helm chart.
The chart installs the following components onto the target OpenShift cluster:

RHDH (Red Hat Developer Hub) Backstage
OpenShift Serverless Logic Operator (with Data-Index and Job Service)
OpenShift Serverless Operator
- Knative Eventing
- Knative Serving
ArgoCD orchestrator project (optional: disabled by default)
Tekton tasks and build pipeline (optional: disabled by default)

Important Note for ARM64 Architecture Users

Note that as of November 6, 2023, OpenShift Serverless Operator is based on RHEL 8 images which are not supported on the ARM64 architecture. Consequently, deployment of this helm chart on an OpenShift Local cluster on MacBook laptops with M1/M2 chips is not supported.

Prerequisites

Logged in to a Red Hat OpenShift Container Platform (version 4.13+) cluster as a cluster administrator.
OpenShift CLI (oc) is installed.
Operator Lifecycle Manager (OLM) has been installed in your cluster.
Your cluster has a default storage class provisioned.
Helm v3.9+ is installed.
PostgreSQL database is available with credentials to manage the tablespace (optional).
- A reference implementation is provided for your convenience.
A GitHub API Token - to import items into the catalog, ensure you have a GITHUB_TOKEN with the necessary permissions as detailed here.
- For classic token, include the following permissions:
  - repo (all)
  - admin:org (read:org)
  - user (read:user, user:email)
  - workflow (all) - required for using the software templates for creating workflows in GitHub
- For Fine grained token:
  - Repository permissions: Read access to metadata, Read and Write access to actions, actions variables, administration, code, codespaces, commit statuses, environments, issues, pull requests, repository hooks, secrets, security events, and workflows.
  - Organization permissions: Read access to members, Read and Write access to organization administration, organization hooks, organization projects, and organization secrets.

Installation

Get the Helm chart from one of the following options
- Pre-Packaged Helm Chart
  If you choose to install the Helm chart from the Helm repository, you’ll be leveraging the pre-packaged version provided by the chart maintainer. This method is convenient and ensures that you’re using a stable, tested version of the chart. Add the repository:
```
helm repo add orchestrator https://parodos-dev.github.io/orchestrator-helm-chart
```
  Expect result:
```
"orchestrator" has been added to your repositories
```
  Verify the repository is shown:
```
helm repo list
```
  Expect result:
```
NAME        	URL
orchestrator	https://parodos-dev.github.io/orchestrator-helm-chart
```
- Manual Chart Deployment
  By cloning the repository and navigating to the charts directory, you’ll have access to the raw chart files and can customize them to fit your specific requirements.
```
git clone git@github.com:parodos-dev/orchestrator-helm-chart.git
cd orchestrator-helm-chart/charts
```
Create a namespace for the Orchestrator solution:
```
oc new-project orchestrator
```
Set GITHUB_TOKEN environment variable
```
export GITHUB_TOKEN=<github token>
```
Deploy PostgreSQL reference implementation following these instructions

…without GitOps

Install the orchestrator Helm chart:

helm upgrade -i orchestrator orchestrator/orchestrator --set rhdhOperator.github.token=$GITHUB_TOKEN

Run the commands prompted at the end of the previous step to wait until the services are ready.

… with GitOps

Install Red Hat OpenShift Pipelines and Red Hat OpenShift GitOps operators following these instructions. The Orchestrator installs RHDH and imports software templates designed for bootstrapping workflow development. These templates are crafted to ease the development lifecycle, including a Tekton pipeline to build workflow images and generate workflow K8s custom resources. Furthermore, ArgoCD is utilized to monitor any changes made to the workflow repository and to automatically trigger the Tekton pipelines as needed. This installation process ensures that all necessary Tekton and ArgoCD resources are provisioned within the same cluster.
Download the setup script from the github repository and run it to to set up environment variables:
```
wget https://raw.githubusercontent.com/parodos-dev/orchestrator-helm-chart/stable-1.x/hack/setenv.sh -O /tmp/setenv.sh && chmod u+x /tmp/setenv.sh
```
This script generates a .env file that contains all the calculated environment variables. Run source .env to utilize these variables.
NOTE: If you don’t want to use the default values, omit the --use-default and the script will prompt you for input.
Default values are calculated as follows:
- WORKFLOW_NAMESPACE: Default value is set to sonataflow-infra.
- K8S_CLUSTER_URL: The URL of the Kubernetes cluster is obtained dynamically using oc whoami --show-server.
- K8S_CLUSTER_TOKEN: The value is obtained dynamically based on the provided namespace and service account.
- GITHUB_TOKEN: This value is prompted from the user during script execution and is not predefined.
- ARGOCD_NAMESPACE: Default value is set to orchestrator-gitops.
- ARGOCD_URL: This value is dynamically obtained based on the first ArgoCD instance available.
- ARGOCD_USERNAME: Default value is set to admin.
- ARGOCD_PASSWORD: This value is dynamically obtained based on the first ArgoCD instance available.

Install the orchestrator Helm chart:

helm upgrade -i orchestrator orchestrator/orchestrator --set rhdhOperator.github.token=$GITHUB_TOKEN \
--set rhdhOperator.k8s.clusterToken=$K8S_CLUSTER_TOKEN --set rhdhOperator.k8s.clusterUrl=$K8S_CLUSTER_URL \
--set argocd.namespace=$ARGOCD_NAMESPACE --set argocd.url=$ARGOCD_URL --set argocd.username=$ARGOCD_USERNAME \
--set argocd.password=$ARGOCD_PASSWORD --set argocd.enabled=true --set tekton.enabled=true

Run the commands prompted at the end of the previous step to wait until the services are ready.

Sample output:

NAME: orchestrator
LAST DEPLOYED: Fri Mar 29 12:34:59 2024
NAMESPACE: sonataflow-infra
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Helm Release orchestrator installed in namespace sonataflow-infra.

Components                   Installed   Namespace
====================================================================
Backstage                    YES        rhdh-operator
Postgres DB - Backstage      NO         rhdh-operator
Red Hat Serverless Operator  YES        openshift-serverless
KnativeServing               YES        knative-serving
KnativeEventing              YES        knative-eventing
SonataFlow Operator          YES        openshift-serverless-logic
SonataFlowPlatform           YES        sonataflow-infra
Data Index Service           YES        sonataflow-infra
Job Service                  YES        sonataflow-infra
Tekton pipeline              YES        orchestrator-gitops
Tekton task                  YES        orchestrator-gitops
ArgoCD project               YES        orchestrator-gitops

====================================================================
Prerequisites check:
The required CRD tekton.dev/v1beta1/Task is already installed.
The required CRD tekton.dev/v1/Pipeline is already installed.
The required CRD argoproj.io/v1alpha1/AppProject is already installed.
====================================================================


Run the following commands to wait until the services are ready:
```console
  oc wait -n openshift-serverless deploy/knative-openshift --for=condition=Available --timeout=5m
  oc wait -n knative-eventing knativeeventing/knative-eventing --for=condition=Ready --timeout=5m
  oc wait -n knative-serving knativeserving/knative-serving --for=condition=Ready --timeout=5m
  oc wait -n openshift-serverless-logic deploy/logic-operator-rhel8-controller-manager --for=condition=Available --timeout=5m
  oc wait -n sonataflow-infra sonataflowplatform/sonataflow-platform --for=condition=Succeed --timeout=5m
  oc wait -n sonataflow-infra deploy/sonataflow-platform-data-index-service --for=condition=Available --timeout=5m
  oc wait -n sonataflow-infra deploy/sonataflow-platform-jobs-service --for=condition=Available --timeout=5m
  oc wait -n rhdh-operator backstage backstage --for=condition=Deployed=True
  oc wait -n rhdh-operator deploy/backstage-backstage --for=condition=Available --timeout=5m

During the installation process, Kubernetes jobs are created by the chart to monitor the installation progress and wait for the CRDs to be fully deployed by the operators. In case of any failure at this stage, these jobs remain active, facilitating administrators in retrieving detailed diagnostic information to identify and address the cause of the failure.

Note: that these jobs are automatically deleted after the deployment of the chart is completed.

For installing from OpenShift Developer perspective

Create the HelmChartRepository from CLI (or from OpenShift UI):

cat << EOF | oc apply -f -
apiVersion: helm.openshift.io/v1beta1
kind: HelmChartRepository
metadata:
  name: orchestrator
spec:
  connectionConfig:
    url: 'https://parodos-dev.github.io/orchestrator-helm-chart'
EOF

Follow Helm Chart installation instructions here

Additional information

GitOps environment

See the dedicated document

Prerequisites

In addition to the prerequisites mentioned earlier, it is possible to manually install the following operator:

ArgoCD/OpenShift GitOps operator
- Ensure at least one instance of ArgoCD exists in the designated namespace (referenced by ARGOCD_NAMESPACE environment variable).
- Validated API is argoproj.io/v1alpha1/AppProject
Tekton/OpenShift Pipelines operator
- Validated APIs are tekton.dev/v1beta1/Task and tekton.dev/v1/Pipeline

Deploying PostgreSQL reference implementation

See here

ArgoCD and workflow namespace

If you manually created the workflow namespaces (e.g., $WORKFLOW_NAMESPACE), run this command to add the required label that allows ArgoCD deploying instances there:

oc label ns $WORKFLOW_NAMESPACE argocd.argoproj.io/managed-by=$ARGOCD_NAMESPACE

Workflow installation

Follow Workflows Installation

Cleanup

To remove the installation from the cluster, run:

helm delete orchestrator
release "orchestrator" uninstalled

Note that the CRDs created during the installation process will remain in the cluster. To clean the rest of the resources, run:

oc get crd -o name | grep -e sonataflow -e rhdh | xargs oc delete
oc delete namespace orchestrator

Troubleshooting

Timeout or errors during `oc wait` commands

If you encounter errors or timeouts while executing oc wait commands, follow these steps to troubleshoot and resolve the issue:

Check Deployment Status: Review the output of the oc wait commands to identify which deployments met the condition and which ones encountered errors or timeouts. For example, if you see error: timed out waiting for the condition on deployments/sonataflow-platform-data-index-service, investigate further using oc describe deployment sonataflow-platform-data-index-service -n sonataflow-infra and oc logs sonataflow-platform-data-index-service -n sonataflow-infra

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified June 7, 2024: Fix type in the url for orchestrator installation pages (f1eb808)

Orchestrator on OpenShift

Orchestrator Helm Chart

Important Note for ARM64 Architecture Users

Prerequisites

Installation

…without GitOps

… with GitOps

For installing from OpenShift Developer perspective

Additional information

GitOps environment

Prerequisites

Deploying PostgreSQL reference implementation

ArgoCD and workflow namespace

Workflow installation

Cleanup

Troubleshooting

Timeout or errors during oc wait commands

Feedback

Timeout or errors during `oc wait` commands