Procedure

1. Clone the project as shown in the following example:

   git clone git@github.com:rhdhorchestrator/orchestrator-demo.git
   cd orchestrator-demo

2. Check the help menu of the script:

   ./scripts/build.sh --help

3. Run the build.sh script, providing the required flags, for instance, the image path (-i), workflow source directory (-w), and manifests output directory (-m).

   Important

   You must specify the full target image path with a tag as shown in the following example:

   ./scripts/build.sh --image=quay.io/orchestrator/demo-basic:test -w 01_basic/ -m 01_basic/manifests

Procedure

1. Use the kubectl create command specifying the target namespace to apply the Kubernetes manifests as shown in the following example:

   kubectl create -n <your_namespace> -f ./01_basic/manifests/.

2. After deployment, monitor the status of the workflow pods as shown in the following example:

   kubectl get pods -n <your_namespace> -l app=basic

   The pod may initially appear in an Error state because of missing or incomplete configuration in the Secret or ConfigMap.

3. Inspect the Pod logs as shown in the following example:

   oc logs -n <your_namespace> basic-f7c6ff455-vwl56

   The following code is an example of the output:

   SRCFG00040: The config property quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token is defined as the empty String ("") which the following Converter considered to be null: io.smallrye.config.Converters$BuiltInConverter
   java.lang.RuntimeException: Failed to start quarkus
   ...
   Caused by: io.quarkus.runtime.configuration.ConfigurationException: Failed to read configuration properties

   The error indicates a missing property: quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token.

4. In such a case where the logs show the ConfigurationException: Failed to read configuration properties error or indicate a missing value, retrieve the ConfigMap as shown in the following example:

   oc get -n <your_namespace> configmaps basic-props -o yaml

   The following code is an example of the sample output:

   apiVersion: v1
   data:
     application.properties: |
       # Backstage notifications service
       quarkus.rest-client.notifications.url=${BACKSTAGE_NOTIFICATIONS_URL}
       quarkus.openapi-generator.notifications.auth.BearerToken.bearer-token=${NOTIFICATIONS_BEARER_TOKEN}
   ...

   Resolve the placeholders using values provided using a Secret.

5. You must edit the corresponding Secret and provide appropriate base64-encoded values to resolve the placeholders in application.properties as shown in the following example:

   kubectl edit secrets -n <your_namespace> basic-secrets

6. Restart the workflow Pod for Secret changes to take effect in OpenShift Serverless Logic v1.36.

Verification

1. Verify the deployment status by checking the Pods again as shown in the following example:

   oc get pods -n <your_namespace> -l app=basic

   The expected status for a successfully deployed workflow Pod is as shown in the following example:

   NAME                    READY   STATUS    RESTARTS   AGE
   basic-f7c6ff455-grkxd   1/1     Running   0          47s

2. Once the Pod is in the Running state, the workflow now appears in the Orchestrator plugin inside the Red Hat Developer Hub.

Procedure

1. To enable the Orchestrator plugin with default settings, set disabled: false for the package. For example, package: "@redhat/backstage-plugin-orchestrator@<plugin_version> is set to disabled: false:

   - package: "@redhat/backstage-plugin-orchestrator@<plugin_version>"
     disabled: false

   Example: Complete configuration of the Orchestrator plugin

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: orchestrator-plugin
   data:
       dynamic-plugins.yaml: |
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - package: "@redhat/backstage-plugin-orchestrator@1.7.1"
             disabled: false
             pluginConfig:
               dynamicPlugins:
                   frontend:
                     red-hat-developer-hub.backstage-plugin-orchestrator:
                       appIcons:
                         - importName: OrchestratorIcon
                           name: orchestratorIcon
                       dynamicRoutes:
                         - importName: OrchestratorPage
                           menuItem:
                             icon: orchestratorIcon
                             text: Orchestrator
                           path: /orchestrator
                       entityTabs:
                         - path: /workflows
                           title: Workflows
                           mountPoint: entity.page.workflows
                       mountPoints:
                         - mountPoint: entity.page.workflows/cards
                         importName: OrchestratorCatalogTab
                         config:
                           layout:
                             gridColumn: '1 / -1'
                             if:
                               anyOf:
                                 - IsOrchestratorCatalogTabAvailable
           - package: "@redhat/backstage-plugin-orchestrator-backend-dynamic@1.7.1"
             disabled: false
             pluginConfig:
               orchestrator:
                 dataIndexService:
                   url: http://sonataflow-platform-data-index-service
             dependencies:
               - ref: sonataflow
           - package: "@redhat/backstage-plugin-scaffolder-backend-module-orchestrator-dynamic@1.7.1"
             disabled: false
             pluginConfig:
               orchestrator:
                 dataIndexService:
                   url: http://sonataflow-platform-data-index-service
           - package: "@redhat/backstage-plugin-orchestrator-form-widgets@1.7.1"
             disabled: false
             pluginConfig:
               dynamicPlugins:
                 frontend:
                   red-hat-developer-hub.backstage-plugin-orchestrator-form-widgets: { }
   ---
   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: orchestrator
   spec:
     application:
       appConfig:
         configMaps:
           - name: app-config-rhdh
       dynamicPluginsConfigMapName: orchestrator-plugin

2. Create a secret containing the BACKEND_SECRET value as shown in the following example:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: app-config-rhdh
   data:
     app-config-rhdh.yaml: |-
       auth:
         environment: development
         providers:
           guest:
             # using the guest user to query the '/api/dynamic-plugins-info/loaded-plugins' endpoint.
             dangerouslyAllowOutsideDevelopment: true
       backend:
         auth:
           externalAccess:
             - type: static
               options:
                 token: ${BACKEND_SECRET}
                 subject: orchestrator
   ---
   apiVersion: v1
   kind: Secret
   metadata:
     name: backend-auth-secret
   stringData:
     # generated with the command below (from https://backstage.io/docs/auth/service-to-service-auth/#setup):
     # node -p 'require("crypto").randomBytes(24).toString("base64")'
     # notsecret
     BACKEND_SECRET: "R2FxRVNrcmwzYzhhN3l0V1VRcnQ3L1pLT09WaVhDNUEK"

3. Configure your Backstage CR to update the secret name in the extraEnvs field as shown in the following example:

   apiVersion: rhdh.redhat.com/v1alpha4
   kind: Backstage
   metadata:
     name: orchestrator
   spec:
     application:
       appConfig:
         configMaps:
           - name: app-config-rhdh
       dynamicPluginsConfigMapName: orchestrator-plugin
       extraEnvs:
         secrets:
             # secret that contains the BACKEND_SECRET key
           - name: backend-auth-secret

Procedure

1. As an administrator, install relevant cluster-wide resources.

   helm repo add openshift-helm-charts https://charts.openshift.io/
   helm install <release_name> openshift-helm-charts/redhat-developer-hub-orchestrator-infra

   Important

   You must be an administrator to install the redhat-developer-hub-orchestrator-infra Helm chart because it deploys additional cluster-scoped OpenShift Serverless and OpenShift Serverless Logic Operators. As an administrator, you must manually approve the install plans for OpenShift Serverless and Serverless Logic Operators.

2. Install the Backstage chart with the orchestrator enabled as shown in the following example:

   $ helm install <release_name> openshift-helm-charts/redhat-developer-hub --version 1.7.1 \
     --set orchestrator.enabled=true

3. (Optional) Enable Notifications and Signals plugins by adding them to the global.dynamic.plugins list in your values.yaml file as shown in the following example:

   global:
     dynamic:
       plugins:
         - disabled: false
           package: "./dynamic-plugins/dist/backstage-plugin-notifications"
         - disabled: false
           package: "./dynamic-plugins/dist/backstage-plugin-signals"
         - disabled: false
           package: "./dynamic-plugins/dist/backstage-plugin-notifications-backend-dynamic"
         - disabled: false
           package: "./dynamic-plugins/dist/backstage-plugin-signals-backend-dynamic"

4. (Optional) You can disable the Serverless Logic and Serverless Operators individually or together by setting their values to false, as shown in the following example:

   helm install <release_name> openshift-helm-charts/redhat-developer-hub \
     --version 1.7.1 \
     --set orchestrator.enabled=true \
     --set orchestrator.serverlessOperator=false \
     --set orchestrator.serverlessLogicOperator=false

5. (Optional) If you are using an external database, add the following configuration under orchestrator.sonataflowPlatform in your values.yaml file:

   orchestrator:
     sonataflowPlatform:
       externalDBsecretRef: "<cred-secret>"
       externalDBName: "<database_name>" # The name of the user-configured existing database (Not the database that the orchestrator and sonataflow resources use).
       externalDBHost: "<database_host>"
       externalDBPort: "<database_port>"

   Note

   This step only configures the Orchestrators use of an external database. To configure Red Hat Developer Hub to use an external PostgreSQL instance, follow the steps in Configuring a PostgreSQL instance using Helm.

Verification

1. Verify that the Orchestrator plugin is visible in the Red Hat Developer Hub UI.
2. Create and run sample workflows to confirm the orchestration is functioning correctly.

Procedure

1. In the OpenShift Container Platform web console, go to the Helm Charts and verify that the Red Hat Developer Hub Helm chart repository is available.

2. Search for the Orchestrator infrastructure for Red Hat Developer Hub and select Install.

   Important

   You must be an administrator to install the Orchestrator Infrastructure for Red Hat Developer Hub Helm chart because it deploys cluster-scoped resources. As an administrator, you must manually approve the install plans for OpenShift Serverless and Serverless Logic Operators.

   As a regular user, search for the Red Hat Developer Hub chart and install it by setting the value of orchestrator.enabled to true. Otherwise, the Orchestrator will not be deployed.

3. Wait until they are successfully deployed.
4. Monitor the deployment status by navigating to Pods or releases.

1. Default resource limits

1. You can override these values in any of the following ways:

   • With values.yaml
   • With --set flags

2. Override defaults with values.yaml as shown in the following example:

   orchestrator:
     enabled: true
     sonataflowPlatform:
     resources:
         limits:
           cpu: "500m"
           memory: "1Gi"

3. Override with --set as shown in the following example:

   helm upgrade --install <release_name>  openshift-helm-charts/redhat-developer-hub \
     --set orchestrator.enabled=true \
     --set orchestrator.sonataflowPlatform.resources.requests.cpu=500m \
     --set orchestrator.sonataflowPlatform.resources.requests.memory=128Mi \
     --set orchestrator.sonataflowPlatform.resources.limits.cpu=1 \
     --set orchestrator.sonataflowPlatform.resources.limits.memory=2Gi

   Note

   The --set setting is applicable only when orchestrator.enabled is true. By default, it is set to false.