Plugins

• 1: Notifications Plugin
• 2: Orchestrator Plugin

1 - Notifications Plugin

The Backstage Notifications System provides a way for plugins and external services to send notifications to Backstage users.

These notifications are displayed in the dedicated page of the Backstage frontend UI or by frontend plugins per specific scenarios.

Additionally, notifications can be sent to external channels (like email) via “processors” implemented within plugins.

Upstream documentation can be found in:

• Notifications and Signals
• Backend email plugin

Frontend

Notifications are messages sent to either individual users or groups. They are not intended for inter-process communication of any kind.

To list and manage, choose Notifications from the left-side menu item.

There are two basic types of notifications:

• Broadcast: Messages sent to all users of Backstage.
• Entity: Messages delivered to specific listed entities from the Catalog, such as Users or Groups.

Backend

The backend plugin provides the backend application for reading and writing notifications.

Authentication

The Notifications are primarily meant to be sent by backend plugins. In such flow, the authentication is shared among them.

To let external systems (like a Workflow) create new notifications by sending POST requests to the Notification REST API, authentication needs to be properly configured via setting the backend.auth.externalAccess property of the app-config .

Refer to the service-to-service auth documentation for more details, focusing on the Static Tokens section as the simplest setup option.

Creating a notification by external services

An example request for creating a broadcast notification can look like:

curl -X POST https://[BACKSTAGE_BACKEND]/api/notifications -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_BASE64_SHARED_KEY_TOKEN" -d '{"recipients":{"type":"broadcast"},"payload": {"title": "Title of broadcast message","link": "http://foo.com/bar","severity": "high","topic": "The topic"}}'

Configuration

Configuration of the dynamic plugins is in the dynamic-plugins-rhdh ConfigMap created by the Helm chart during installation.

Frontend configuration

Usually there is no need to change the defaults but little tweaks can be done on the props section:

            frontend:
              redhat.plugin-notifications:
                dynamicRoutes:
                  - importName: NotificationsPage
                    menuItem:
                      config:
                        props:
                          titleCounterEnabled: true
                          webNotificationsEnabled: false
                      importName: NotificationsSidebarItem
                    path: /notifications

Backend configuration

Except setting authentication for external callers, there is no special plugin configuration needed.

Forward to Email

It is possible to forward notification content to email address. In order to do that you must add the Email Processor Module to your Backstage backend.

Configuration

Configuration options can be found in plugin’s documentation.

Example configuration:

      pluginConfig:
        notifications:
          processors:
            email:
              filter:
                minSeverity: low
                maxSeverity: critical
                excludedTopics: []
              broadcastConfig:
                receiver: config # or none or users
                receiverEmails:
                  - foo@company.com
                  - bar@company.com
              cache:
                ttl:
                  days: 1
              concurrencyLimit: 10
              replyTo: email@company.com
              sender: email@company.com
              transportConfig:
                hostname: your.smtp.host.com
                password: a-password
                username: a-smtp-username
                port: 25
                secure: false
                transport: smtp

Ignoring unwanted notifications

The configuration of the module explains how to configure filters. Filters are used to ignore notifications that should not be forwarded to email. The supported filters include minimum/maximum severity and list of excluded topics.

User notifications

Each user notification has a list of recipients. The recipient is an entity in Backstage catalog. The notification will be sent to the email addresses of the recipients.

Broadcast notifications

In broadcast notifications we do not have recipients, the notifications are delivered to all users.

The module’s configuration supports a few options for broadcast notifications:

• Ignoring broadcast notifications to be forwarded
• Sending to predefined address list only
• Sending to all users whose catalog entity has an email

2 - Orchestrator Plugin

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.