Orchestrator Plugin for Backstage

The Orchestrator for Backstage is designed to enable self-service flows. It serves as a vital component that enhances and augments the existing scaffolder functionality of Backstage with a more flexible and powerful set of features including long-running and asynchronous flows.

The Backstage Orchestrator plugin aims to provide a better option to Scaffolder, based on workflows to have a more flexible and powerful tool that addresses the need by streamlining and automating processes, allowing developers to focus more on coding and innovation.

It utilizes SonataFlow, a powerful tool for building cloud-native workflow applications.

Architecture Overview

The architecture adheres to standard Backstage plugin guidelines and requires the following plugins to be installed for proper functionality:

1. backstage-plugin-orchestrator

   • Provides the frontend interface.

2. backstage-plugin-orchestrator-backend

   • Serves as a backend proxy between Backstage and SonataFlow.

These plugins farther import following isolated plugins:

1. backstage-plugin-orchestrator-swf-editor-envelope

   • Hosts the workflow viewer.

2. backstage-plugin-orchestrator-common

   • Contains the backend OpenAPI specification along with autogenerated API documentation and client libraries.

3. backstage-plugin-orchestrator-form

   • Provides the workflow execution form.

4. backstage-plugin-orchestrator-form-api

   • Defines the API for extending the workflow execution form.
   • For more details, see the Extensible Form Documentation.

For more details about architecture, see the Architecture page.

Install as a static plugin

Follows these instructions to install the orchestrator plugin in a backstage environment. These instructions assume the code structure has the standard backstage app structure.

Setting up the Orchestrator backend package

1. Install the Orchestrator backend plugin using the following command:

   yarn workspace backend add @red-hat-developer-hub/backstage-plugin-orchestrator-backend
   

2. Add the following code to the packages/backend/src/index.ts file:

   const backend = createBackend();
   
   /* highlight-add-next-line */
   backend.add(
     import('@red-hat-developer-hub/backstage-plugin-orchestrator-backend'),
   );
   
   backend.start();
   

Setting up the Orchestrator frontend package

1. Install the Orchestrator frontend plugin using the following command:

   yarn workspace app add @red-hat-developer-hub/backstage-plugin-orchestrator
   

2. Add a route to the OrchestratorPage and the customized template card component to Backstage App (packages/app/src/App.tsx):

   /* highlight-add-next-line */
   import { OrchestratorPage } from '@red-hat-developer-hub/backstage-plugin-orchestrator';
   
   const routes = (
     <FlatRoutes>
       {/* ... */}
       {/* highlight-add-next-line */}
       <Route path="/orchestrator" element={<OrchestratorPage />} />
     </FlatRoutes>
   );
   

3. Add the Orchestrator to Backstage sidebar (packages/app/src/components/Root/Root.tsx):

   /* highlight-add-next-line */
   import { OrchestratorIcon } from '@red-hat-developer-hub/backstage-plugin-orchestrator';
   
   export const Root = ({ children }: PropsWithChildren<{}>) => (
     <SidebarPage>
       <Sidebar>
         <SidebarGroup label="Menu" icon={<MenuIcon />}>
           {/* ... */}
           {/* highlight-add-start */}
           <SidebarItem
             icon={OrchestratorIcon}
             to="orchestrator"
             text="Orchestrator"
           />
           {/* highlight-add-end */}
         </SidebarGroup>
         {/* ... */}
       </Sidebar>
       {children}
     </SidebarPage>
   );
   

Install as a dynamic plugin in Red Hat Developer Hub

Follow these guidelines to install the orchestrator operator and configure the orchestrator as a dynamic plugin in Red Hat Developer Hub.

Configuration

Devmode local configuration

This configuration serves for running the application locally for development purposes.

Prerequisites

• Docker up and running

backend:
  csp:
    frame-ancestors: ['http://localhost:3000', 'http://localhost:7007']
    script-src: ["'self'", "'unsafe-inline'", "'unsafe-eval'"]
    script-src-elem: ["'self'", "'unsafe-inline'", "'unsafe-eval'"]
    connect-src: ["'self'", 'http:', 'https:', 'data:']
orchestrator:
  sonataFlowService:
    baseUrl: http://localhost
    port: 8899
    autoStart: true
    workflowsSource:
      gitRepositoryUrl: https://github.com/rhdhorchestrator/backstage-orchestrator-workflows
      localPath: /tmp/orchestrator/repository
  dataIndexService:
    url: http://localhost:8899

This configuration will trigger the following:

1. Cloning https://github.com/rhdhorchestrator/backstage-orchestrator-workflows to /tmp/orchestrator/repository.
2. Running the SonataFlow devmode container configured to load the workflows located in /tmp/orchestrator/repository.

Note: /tmp/orchestrator needs to be accessible to docker.

Production configuration

backend:
  csp:
    script-src: ["'self'", "'unsafe-inline'", "'unsafe-eval'"]
    script-src-elem: ["'self'", "'unsafe-inline'", "'unsafe-eval'"]
    connect-src: ["'self'", 'http:', 'https:', 'data:']
orchestrator:
  dataIndexService:
    url: <url to SonataFlow data index>

The csp headers are required for the Workflow viewer to load.

User interface

The user interface is accessible via the orchestrator button added in the Backstage sidebar. It provides a list of workflows and the option to run the workflows and view the results.

Permissions

The Orchestrator plugin protects its backend endpoints with the builtin permission mechanism and combines it with the RBAC plugin. The result is control over what users can see or execute. Details available here.

Orchestrator API

The backend plugin provides OpenAPI v2 endpoints definition.

The OpenAPI specification file is availabe in the openapi spec file.

Documentation is available in the autogenerated documentation

The plugin provides an auto generated typescript client that can be used to call the API. To use it include the @red-hat-developer-hub/backstage-plugin-orchestrator-common plugin in your project. You can see in the OrchestratorClient.ts how the client can be used.

Audit log

The orchestrator backend has audit logs for all incoming requests.

For more information about audit logs in RHDH, please refer to the official documentation. The official Log storage OpenShift documentation may also be of interest.

Extensible workflow execution form

The orchestrator plugin includes an extensible form for executing workflows. Details are available in the extensible form documentation.

Contributors

The orchestrator workspace is structured like a standard backstage application. To get it up and running locally run the following:

cd workspaces/orchestrator
yarn install
yarn dev

This will trigger a docker container run of devmode SonataFlow as described in Devmode local configuration.

More development guidelines available in the contributors documentation.