Skip to content

orchestrator.md

Latest commit

 

History

History
245 lines (191 loc) · 13 KB

orchestrator.md

File metadata and controls

245 lines (191 loc) · 13 KB

Orchestrator installation and configuration

Prerequisites for Orchestrator Plugin Installation on OpenShift

To install the Orchestrator plugin on OpenShift, the following components are required to be pre-installed:

  • OpenShift Serverless Operator
  • Knative Serving
  • Knative Eventing
  • OpenShift Serverless Logic Operator Optionally:
  • OpenShift Pipelines Operator (Tekton)
  • OpenShift GitOps Operator (ArgoCD)

Methods to Install required infrastructural components

There are three methods to install the required components for the Orchestrator plugin on OpenShift:

Manual Installation

This method is recommended for production environments, especially when specific versions of the required components are installed (e.g., when OpenShift Serverless is already in use by other applications).

Version Compatibility

This recommendation is based on OpenShift Serverless version 1.37. Refer to the Orchestrator plugin compatibility documentation to ensure the correct version of OpenShift Serverless is supported for your Orchestrator plugin version.

Steps

Go to the OpenShift Serverless documentation for installation instructions and follow these steps:

  1. Preparing to install OpenShift Serverless.
  2. Installing the OpenShift Serverless Operator.
  3. Installing Knative Serving.
  4. Installing Knative Eventing.
  5. Installing the OpenShift Serverless Logic Operator.

Optionally: 6. Installing the OpenShift Pipelines Operator (Tekton) 7. Installing the OpenShift GitOps Operator (ArgoCD)

RHDH helper script

This script provides a quick way to install the OpenShift Serverless infrastructure for the Orchestrator plugin. It is safe to use in empty clusters but should be used with caution in production clusters. Note: Current Subscriptions configuration uses Automatic install plan (spec.installPlanApproval: Automatic), consider to change it to Manual if you want to control the installation of the operators (see Operator Installation with OLM for more details).

Steps
  1. Download the plugin-infra.sh script: 
    curl -sSLO https://raw.githubusercontent.com/redhat-developer/rhdh-operator/refs/heads/release-1.7/config/profile/rhdh/plugin-infra/plugin-infra.sh

You can specify the RHDH version in the URL (/release-X.Y/, e.g., 1.7 in this example) or use main. 2. Run the script:

bash plugin-infra.sh [--with-cicd] [delete] [--branch <branch>]

Flags:

  • --with-cicd flag will also install the OpenShift Pipelines Operator (Tekton) and OpenShift GitOps Operator (ArgoCD) in addition to the required components for the Orchestrator plugin. To continue the configuration for CICD, please follow this guide.
  • delete will delete the installed components instead of installing them.
  • --branch <branch> flag allows to specify the branch of the RHDH Operator repository where the configuration yaml files will be taken (ignored if you have local yaml files). If not specified, it defaults to the main branch.

The script is checking if the directory where plugin-infra.sh is located contains the corresponding configuration files, e.g., serverless.yaml, knative.yaml, serverless-logic.yaml... (see plugin-infra directory for the complete list). If the files are not found, it will download them from the specified branch of the RHDH Operator repository.

RHDH Orchestrator Infra Helm Chart

This method has similar usage and cautions as the RHDH Helper Utility.

Steps
  1. Install the required components using the Orchestrator Infra Helm chart as described in the README

Installing the Orchestrator Plugin

The orchestrator plugin (as of v1.8.2) consists of four dynamic plugins:

  • orchestrator-backend
  • orchestrator-frontend
  • orchestrator-scaffolder-backend-module
  • orchestrator-form-widgets

As for RHDH 1.7 all of these plugins are included in the default dynamic-plugins.yaml file of install-dynamic-plugins container but disabled by default. To enable the orchestrator plugin, you should refer the dynamic plugins ConfigMap with following data in your Backstage Custom Resource (CR):

    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator:{{inherit}}'
        disabled: false
      - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-backend:{{inherit}}'
        disabled: false
        dependencies:
          - ref: sonataflow
      - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-scaffolder-backend-module-orchestrator:{{inherit}}'
        disabled: false
      - package: 'oci://registry.access.redhat.com/rhdh/red-hat-developer-hub-backstage-plugin-orchestrator-form-widgets:{{inherit}}'
        disabled: false

See example for a complete configuration of the orchestrator plugin. Ensure to add a secret with the BACKEND_SECRET key/value and update the secret name in the Backstage CR under the extraEnvs field.

For more information about configuring dynamic plugins, please refer to the Configuration documentation. For more information about dynamic plugins dependencies, please refer to the Dynamic Plugins Dependencies documentation.

Plugin registry

As for RHDH 1.7 the orchestrator plugin packages are located in npm.registry.redhat.com NPM registry, which is preconfigured in rhdh default-config.

Plugin dependencies

The orchestrator plugin instance requires the following dependencies to be installed:

  • A SonataflowPlatform custom resource - created in the namespace of the Backstage CR.
  • A set of NetworkPolicies to allow traffic between infra resources (knative and serverless logic operator) created in the namespace of Backstage CR, traffic for monitoring, and intra-namespace traffic.
  • A PostgreSQL database to store the orchestrator workflows data.

The orchestrator-backend plugin uses the service sonataflow-platform-data-index-service, which is created by the SonataFlowPlatform CR. This service is used to communicate with the SonataFlow platform.

Note: Upgrading an existing OpenShift Serverless Logic Operator subscription to v1.37 requires deleting the previous logic-operator-rhel8 subscription before installing the new one. That being said, the related SonataflowPlatform operands should not be deleted. See OpenShift Serverless Logic Operator documentation for more details on the recently released OpenShift Serverless Logic Operator versions and upgrade process.

Important: The sonataflowplatform CR contains dataIndex service that requires PostgreSQL database.

      persistence:
        postgresql:
          secretRef:
            name: backstage-psql-secret-{{backstage-name}}
            userKey: POSTGRES_USER
            passwordKey: POSTGRES_PASSWORD
          serviceRef:
            name: backstage-psql-{{backstage-name}}
            namespace: {{backstage-ns}}
            databaseName: backstage_plugin_orchestrator

Where {{backstage-name}} is the name of the Backstage Custom Resource (CR) and {{backstage-ns}} is the namespace where the Backstage CR is created.

Current default implementation of the orchestrator plugin dependencies uses:

  • the Secret created by Backstage operator for the PostgreSQL with POSTGRES_USER and POSTGRES_PASSWORD keys as the database credentials in the Backstage CR namespace.
  • the Service created by Backstage operator for the PostgreSQL database with the name backstage-psql-{{backstage-name}} in the Backstage CR namespace.
  • the PostgreSQL database to store the orchestrator workflows data named backstage_plugin_orchestrator

See profile/rhdh/plugin-deps for a complete configuration of the orchestrator plugin dependencies.

Note: Currently, RHDH Orchestrator workflow is configured and setup to run within the same namespace as RHDH instance (CR). However, to enable and configure the deployment of workflows in a separated namespace, please follow the steps in this section.

RBAC

To enable the Backstage operator to work with the SonataFlow platform, its ServiceAccount must be granted the appropriate permissions. This is done by the Backstage operator automatically when the SonataFlowPlatform CR is created in the namespace of the Backstage CR by the appropriate Role and RoleBinding resource in the profile/rhdh/plugin-rbac directory.

Troubleshooting database migration issues

After installing and configuring the Orchestrator plugin, you can deploy Serverless Workflows to RHDH and run them through the plugin.
For more information, see the OpenShift Serverless Logic documentation.

If your workflow uses persistence, database migration issues might occur when building or running new workflows.
To resolve this, ensure the following property is set in the workflow’s SonataFlow custom resource (CR) or in the application.properties file associated with the workflow:

kie.flyway.enabled=true

For more details, refer to the Flyway configuration section in the Openshift Serverless Logic documentation.

Optional: Enable GitOps/Pipelines for Orchestrator Workflows

To enable CI/CD for RHDH Orchestrator workflows, please follow this guide.

Optional: Enabling workflow in a different namespace

To enable workflow deployment in another namespace other than where RHDH Orchestrator infrastructure are deployed and configured, please follow these steps below.

Note: The $RHDH_NAMESPACE is the namespace where RHDH instance (CR) is deployed. Please ensure to update this value as needed.

  1. Add SonataFlowClusterPlatform Custom Resource:
oc create -f - <<EOF
apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowClusterPlatform
metadata:
  name: cluster-platform
spec:
  platformRef:
    name: sonataflow-platform
    namespace: $RHDH_NAMESPACE
EOF

  1. Add Network Policies: To allow communication between RHDH namespace and the workflow namespace, two network policies need to be added.

    Allow Traffic from the Workflow Namespace:

    To allow RHDH services to accept traffic from workflows, create an additional network policy within the RHDH instance namespace.

    oc create -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-external-workflows-to-rhdh
  # Namespace where network policies are deployed
  namespace: $RHDH_NAMESPACE
spec:
  podSelector: {}
  ingress:
    - from:
      - namespaceSelector:
          matchLabels:
            # Allow SonataFlow services to communicate with new/additional workflow namespace.
            kubernetes.io/metadata.name: $ADDITIONAL_WORKFLOW_NAMESPACE
EOF
    Allow traffic from RHDH and Knative namespaces:

    To allow traffic from RHDH, SonataFlow and Knative, create a network policy within the new/additional workflow namespace.

    oc create -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-rhdh-and-knative-to-workflows
  namespace: $ADDITIONAL_WORKFLOW_NAMESPACE
spec:
  podSelector: {}
  ingress:
    - from:
      - namespaceSelector:
          matchLabels:
            # Allows traffic from pods in the RHDH namespace.
            kubernetes.io/metadata.name: $RHDH_NAMESPACE
      - namespaceSelector:
          matchLabels:
            # Allows traffic from pods in the Knative Eventing namespace.
            kubernetes.io/metadata.name: knative-eventing
      - namespaceSelector:
          matchLabels:
            # Allows traffic from pods in the Knative Serving namespace.
            kubernetes.io/metadata.name: knative-serving
EOF
⚡