Add Konflux plugin #1826

rrosatti · 2025-11-19T14:39:50Z

Add Konflux Plugin for Backstage

Overview

This PR is adding a Backstage integration plugin for Konflux (Red Hat's application delivery platform). The plugin aggregates and displays Kubernetes resources (Applications, Components, PipelineRuns, Releases) from multiple clusters and namespaces, providing a unified view of Konflux resources within Backstage.

Alpha Testing Phase

Once this plugin is merged and integrated into RHDH, it will enter an "alpha testing phase" on the InScope Backstage instance. During this period, we'll gather feedback from early users and iterate on improvements. The plugin is being developed in rhdh-plugins repo (rather than backstage/community-plugins) to enable faster iteration cycles during this testing period. Once alpha testing is complete and we've gathered sufficient feedback, we plan to polish the plugin and make it generally available.

Fixes

The main Epic ticket has several smaller tickets to help tracking the work :)

Fixes https://issues.redhat.com/browse/KFLUXUI-791
Fixes https://issues.redhat.com/browse/KFLUXUI-815
Fixes https://issues.redhat.com/browse/KFLUXUI-816
Fixes https://issues.redhat.com/browse/KFLUXUI-817
Fixes https://issues.redhat.com/browse/KFLUXUI-836
Fixes https://issues.redhat.com/browse/KFLUXUI-837
Fixes https://issues.redhat.com/browse/KFLUXUI-840
Fixes https://issues.redhat.com/browse/KFLUXUI-841

For a broader feature description see https://issues.redhat.com/browse/KONFLUX-8254

Architecture

The plugin consists of three packages:

konflux-common: shared types, models, and utilities (PipelineRun, Application, Component, Release types, configuration parsing, pagination utilities)
konflux-backend: backend service that fetches and aggregates resources from Kubernetes clusters via the Kubernetes API and Kubearchive
konflux: frontend React components (KonfluxPage, KonfluxCIPage, KonfluxStatus, LatestReleases)

Key Features

multi-cluster aggregation: fetches resources from multiple Kubernetes clusters in parallel
Kubearchive integration: falls back to archived resources when the Kubernetes API is exhausted
pagination: handles pagination across multiple sources with continuation tokens
application filtering: filters resources by Application name
error handling: tracks errors per cluster/namespace
Subcomponent support: aggregates resources across all subcomponents with fallback to main entity

How It Works

configuration: combines cluster configuration from app-config.yaml with entity-specific configuration from catalog annotations (konflux-ci.dev/clusters)
resource fetching: backend aggregates resources across configured clusters/namespaces, falling back to Kubearchive when needed
display: frontend components display resources in dedicated tabs (Konflux, CI/CD) or entity overview cards, controlled by entity annotations (konflux-ci.dev/overview, konflux-ci.dev/konflux, konflux-ci.dev/ci)

Visual References

Demo Video

This is a short demo video that goes through all the components available with the Konflux plugin, including navigation between tabs and demonstration of filtering/pagination features.

short-demo.mp4

Screenshots

Entity Overview with Konflux Components (KonfluxStatus and KonfluxLatestReleases)
![Entity Overview tab showing KonfluxStatus and KonfluxLatestReleases components integrated into the standard Backstage entity overview]

Konflux Tab - Applications and Components
![KonfluxPage displaying ApplicationsList and ComponentsList with filtering and pagination controls]

CI/CD Tab - Pipeline Runs and Commits
![KonfluxCIPage showing PipelineRunsList and CommitsList with filtering and pagination controls]

Configuration

The plugin requires configuration in two places: app-config.yaml for cluster configuration and entity annotations for feature enablement and resource mapping.

app Configuration (`app-config.yaml`)

Configure clusters and authentication in the backend configuration:

konflux:
  authProvider: serviceAccount # serviceAccount | oidc | impersonationHeaders
  clusters:
    cluster-name-1:
      apiUrl: https://api.cluster1.example.com
      uiUrl: https://konflux-ui.cluster1.example.com
      kubearchiveApiUrl: https://kubearchive-api.cluster1.example.com  # optional
      serviceAccountToken: <token>  # required for serviceAccount or impersonationHeaders
    cluster-name-2:
      apiUrl: https://api.cluster2.example.com
      uiUrl: https://konflux-ui.cluster2.example.com
      serviceAccountToken: <token>

Entity Configuration (`catalog-info.yaml`)

Entities can enable Konflux features via annotations:

Feature Control Annotations:

konflux-ci.dev/overview: 'true' - shows Konflux components in Overview tab
konflux-ci.dev/konflux: 'true' - enables Konflux tab
konflux-ci.dev/ci: 'true' - enables CI/CD tab

Cluster Configuration Annotation:

konflux-ci.dev/clusters - cluster/namespace/applications configuration (YAML format)

Example Entity Configuration:

---
kind: Component
apiVersion: backstage.io/v1alpha1
metadata:
  name: amazing-component
  annotations:
    konflux-ci.dev/overview: 'true'
    konflux-ci.dev/konflux: 'true'
    konflux-ci.dev/ci: 'true'
spec:
  type: service
  lifecycle: experimental
  owner: user:guest

---
kind: Component
apiVersion: backstage.io/v1alpha1
metadata:
  name: amazing-component-subcomponent-a
  annotations:
    konflux-ci.dev/overview: 'true'
    konflux-ci.dev/konflux: 'true'
    konflux-ci.dev/ci: 'true'
    konflux-ci.dev/clusters: |
      - cluster: cluster-name-1
        namespace: namespace-a
        applications:
          - application-a
          - application-b
spec:
  subcomponentOf: amazing-component
  type: service
  lifecycle: experimental
  owner: user:guest

Note: when subcomponents exist, only their cluster configurations are used. If no subcomponents exist, the main entity's configuration is used as a fallback.

Testing

✅ all plugins build successfully
✅ linting passes
✅ workspace includes example entities and configuration
✅ app starts and integrates with Backstage
⚠️ OIDC authentication: code implemented and follows Backstage patterns, but not tested due to our OCP clusters not having the required version to support authentication with external OIDC providers.

Note: this PR adds the complete konflux plugin workspace including all three packages, configuration, and documentation ☕️

✔️ Checklist

A changeset describing the change and affected packages. (more info)
Added or Updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)

rhdh-gh-app · 2025-11-19T14:40:16Z

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
app	workspaces/konflux/packages/app	none	`v0.0.0`
backend	workspaces/konflux/packages/backend	none	`v0.0.0`
@red-hat-developer-hub/backstage-plugin-konflux-backend	workspaces/konflux/plugins/konflux-backend	none	`v1.0.0`
@red-hat-developer-hub/backstage-plugin-konflux-common	workspaces/konflux/plugins/konflux-common	none	`v0.1.0`
@red-hat-developer-hub/backstage-plugin-konflux	workspaces/konflux/plugins/konflux	none	`v0.1.0`

rrosatti · 2025-11-19T14:43:52Z

workspaces/konflux/plugins/konflux-common/src/entities.ts

+export function getSubcomponentsWithFallback(
+  relatedEntities: Entity[] | null | undefined,
+  mainEntity: Entity,
+): Entity[] {
+  if (!relatedEntities?.length) {
+    return [mainEntity];
+  }
+
+  const filtered = relatedEntities.filter(
+    e =>
+      e.metadata.name !== 'guest' &&
+      e.relations?.some(rel => rel?.type === 'partOf'),
+  );
+
+  // fallback to main entity if no valid subcomponents found
+  if (!filtered.length) {
+    return [mainEntity];
+  }
+
+  return filtered;
+}


note: when subcomponents exist, we only use their cluster configs and ignore the main entity's config. falls back to main entity only if no subcomponents are found.

rrosatti · 2025-11-19T14:49:22Z

workspaces/konflux/plugins/konflux-backend/src/services/resource-fetcher.ts

+    );
+
+    // case 1: continue from Kubearchive (k8s already exhausted)
+    if (kubearchiveToken && !k8sToken && hasKubearchive) {


kubearchive fallback: if K8s is exhausted, automatically continue from Kubearchive. So, frontend only sees continuation tokens and doesn't need to know which source is used

rrosatti · 2025-11-19T14:54:18Z

workspaces/konflux/plugins/konflux-backend/src/services/konflux-service.ts

+    // decode continuation token to get pagination state for each source
+    let paginationState: PaginationState = {};
+    const isLoadMoreRequest = !!validatedFilters?.continuationToken;
+
+    const userId = userEntityRef || userEmail || 'unknown';
+
+    if (validatedFilters?.continuationToken) {
+      try {
+        paginationState = decodeContinuationToken(
+          validatedFilters.continuationToken,
+          userId,
+        );
+      } catch (error) {
+        this.konfluxLogger.error('Failed to decode continuation token', error, {
+          userId,
+          entityRef,
+          resource,
+        });
+        throw error instanceof Error
+          ? error
+          : new Error('Invalid continuation token');
+      }
+    }


each source (cluster:namespace) maintains separate pagination state with tokens for both K8s API and karchive

rrosatti · 2025-11-19T14:55:32Z

workspaces/konflux/plugins/konflux-backend/src/services/konflux-service.ts

+      const sourceState = paginationState[sourceKey] || {};
+      const hasAnyToken = sourceState.k8sToken || sourceState.kubearchiveToken;
+
+      if (isLoadMoreRequest && !hasAnyToken) {


skip exhausted sources (no tokens) in "Load More" requests to avoid unnecessary API calls

rrosatti · 2025-11-19T14:57:42Z

workspaces/konflux/plugins/konflux-backend/src/helpers/config.ts

+  }
+};
+
+export const determineClusterNamespaceCombinations = async (


combines app-config.yaml cluster configs with entity annotations. Groups by subcomponent+cluster+namespace and merges applications lists when multiple subcomponents reference the same cluster:namespace

rrosatti · 2025-11-19T14:59:59Z

workspaces/konflux/packages/app/package.json

@@ -0,0 +1,79 @@
+{


for those unfamiliar with Backstage framework/architecture: the packages/ directory contains a "local development environment" (app + backend) for building and testing the plugin. This is standard Backstage workspace structure and not part of the plugin itself - it's only used for local development/testing :)

github-actions · 2025-12-17T18:09:51Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

testcara · 2026-01-13T11:33:31Z

workspaces/konflux/app-config.yaml

+    cluster1:
+      apiUrl: https://api.cluster1.example.com
+      uiUrl: https://ui.cluster1.example.com
+      kubearchiveApiUrl: https://archive.cluster1.example.com


How about we use something like ${SA_TOKEN_CLUSTER_NAME} to keep consistent usage with github_token?
We have several parameters here. For me, i create a .env and set all the variables then 'set -a; source .env; set +a'. then start the app.

also i checked some other plugins, in their gitignore files, they ignore '.env'. i guess they recommend this way.

updated the code to use "env vars" naming to keep it consistent!

testcara · 2026-01-13T11:39:33Z

workspaces/konflux/plugins/konflux-backend/src/services/kubearchive-service.ts

+  options?: {
+    pageSize?: number;
+    pageToken?: string;
+    filter?: string; // TODO: handle filter


Whether the // TODO comments are valid?

yes. I left this TODO for a future improvement :)

testcara · 2026-01-13T11:44:24Z

workspaces/konflux/plugins/konflux/README.md

+
+- **serviceAccount**: Uses service account tokens
+- **impersonationHeaders**: Uses Kubernetes impersonation headers (validates userEmail)
+- **[UNSTABLE / NOT TESTED]** **oidc**: Uses OIDC tokens from the frontend (passed via X-OIDC-Token header)


is it possible to test this?

unfortunately, I don't think so 😕 it requires upgrading to OCP 4.19. That's a message from Gal in a discussion on Slack:

"we currently use user impersonation for the Konflux UI but we are going to stop doing it after upgrading to OCP 4.19 which allows to integrate with external OIDC providers. With this approach the same token would be recognized by both Konflux proxy and the api server."

For dev/stage we can use serviceAccount and impersonationHeaders. But, for production, we'll have to wait for upgrading to OCP 4.19, so we can use OIDC auth.

If you have some ideas on how we could test this oidc provider approach in a dev/local environment, pls let me know :)

testcara · 2026-01-13T11:49:12Z

workspaces/konflux/plugins/konflux-backend/src/services/konflux-service.ts

+      }),
+    );
+
+    const results = await Promise.all(fetchPromises);


promise all? whether we have potential performance problems here?

I believe it should be fine to use Promise.all() here. I'd propose to keep it this way and once we have this in alpha testing, we can gather more info regarding if it's causing issues and could be improved. wdyt? :)

testcara

generally LGTM, i just left few tiny comments. Thank you for the great patch.

testcara

generally lgtm, according to testing, the function works well.
For me, it is ready for user testing as we plan.

* add workspace package.json * add tsconfig.json * add app-config.yaml template * create plugins/ directory structure

- add konflux cluster configuration to app-config.yaml - add example entities and org data - add config.d.ts file with konflux configuration type definition

- add common types (PipelineRun, Application, Component, Release) - add configuration parsing utilities - add pagination constants and utilities - add entity processing utilities - add subcomponent utilities - add README

…tion - add KonfluxService for aggregating resources across clusters - add ResourceFetcherService for Kubernetes API and Kubearchive integration - add KubearchiveService for "archived resource fallback" - add router with /entity/:entityRef/resource/:resource endpoint - add configuration helpers and validation - add error extraction and logging utilities - support multiple auth methods (serviceAccount, impersonationHeaders) - IMPORTANT: OIDC still not tested - add README

- add KonfluxPage component for Applications and Components resources - add KonfluxCIPage component for Commits and PipelineRuns resources - add KonfluxStatus component for status display - add LatestReleases component - add resource hooks (useApplications, useComponents, usePipelineruns, useReleases) - add filtering and pagination utilities - add table components with PatternFly styling - add main README.md

…space - add app package with Backstage app setup - add backend package with backend server configuration - configure app routes and entity pages - set up authentication providers - add dependencies on konflux plugins - integrate konflux plugin into Backstage app

Add owners to konflux workspace.

…ux workspace

…integration

Fix dependencies dedupe issues.

sonarqubecloud · 2026-01-16T12:44:44Z

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.3% Duplication on New Code

See analysis details on SonarQube Cloud

hopehadfield

Sorry for the delay in reviewing. Overall very nice work on the plugin, I just left a few comments to address before we can go ahead and merge 😄🚀

hopehadfield · 2026-01-15T21:07:46Z

workspaces/konflux/bcp.json

This file isn't necessary for this repository, only for the backstage/community-plugins repo.

hopehadfield · 2026-01-15T21:14:57Z

workspaces/konflux/config.d.ts

This should instead exist within the plugin packages themselves, either in workspaces/konflux/plugins/konflux-common or in both the frontend and backend package. Also, the visibility annotations should be double-checked (i.e. serviceAccountToken should probably be @visibility secret)

hopehadfield · 2026-01-16T16:09:14Z

workspaces/konflux/packages/backend/package.json

+  "backstage": {
+    "role": "backend"
+  },


Suggested change

"backstage": {

"role": "backend"

},

"backstage": {

"role": "backend-plugin",

"pluginId": "konflux",

"pluginPackage": "@red-hat-developer-hub/backstage-plugin-konflux-backend",

"pluginPackages": [

"@red-hat-developer-hub/backstage-plugin-konflux",

"@red-hat-developer-hub/backstage-plugin-konflux-backend",

"@red-hat-developer-hub/backstage-plugin-konflux-common"

]

},

hopehadfield · 2026-01-16T16:51:03Z

workspaces/konflux/package.json

+      "prettier --write"
+    ]
+  },
+  "dependencies": {


I would consider cleaning these up, most of these likely belong in or are already in the individual plugin packages.

openshift-ci bot added the do-not-merge/work-in-progress label Nov 19, 2025

rrosatti force-pushed the konflux-plugin branch from d84218f to ca32561 Compare November 19, 2025 14:40

rrosatti commented Nov 19, 2025

View reviewed changes

rrosatti force-pushed the konflux-plugin branch from a65d96c to fcd689a Compare November 28, 2025 08:05

rrosatti marked this pull request as ready for review December 3, 2025 12:32

rrosatti requested review from a team as code owners December 3, 2025 12:32

github-actions bot added the stale label Dec 17, 2025

rrosatti force-pushed the konflux-plugin branch from 0fdfd06 to bbab9e3 Compare December 18, 2025 07:58

rrosatti changed the title ~~[WIP] Add Konflux plugin~~ Add Konflux plugin Dec 18, 2025

openshift-ci bot removed the do-not-merge/work-in-progress label Dec 18, 2025

github-actions bot removed the stale label Dec 18, 2025

rrosatti force-pushed the konflux-plugin branch 2 times, most recently from 09c22ee to 453afd9 Compare December 22, 2025 09:29

testcara reviewed Jan 13, 2026

View reviewed changes

testcara approved these changes Jan 14, 2026

View reviewed changes

rrosatti added 8 commits January 16, 2026 09:15

feat(workspaces): add konflux workspace structure

ef16784

* add workspace package.json * add tsconfig.json * add app-config.yaml template * create plugins/ directory structure

chore(konflux/app): add konflux config

6e6fbba

- add konflux cluster configuration to app-config.yaml - add example entities and org data - add config.d.ts file with konflux configuration type definition

feat(plugins/konflux-common): add shared types and utilities

66ee4c0

- add common types (PipelineRun, Application, Component, Release) - add configuration parsing utilities - add pagination constants and utilities - add entity processing utilities - add subcomponent utilities - add README

chore(CODEOWNERS): add owners for konflux workspace

753b6fe

Add owners to konflux workspace.

fixup! feat(plugins/konflux): add frontend plugin for Konflux resources

2fe153a

rrosatti added 11 commits January 16, 2026 09:15

fixup! feat(plugins/konflux-common): add shared types and utilities

e20afcc

fixup! feat(konflux/packages): add app and backend packages for konfl…

1121e44

…ux workspace

fixup! feat(plugins/konflux): add frontend plugin for Konflux resources

a0fbc34

fixup! feat(plugins/konflux): add frontend plugin for Konflux resources

95a072a

fixup! feat(plugins/konflux-common): add shared types and utilities

325af7d

fixup! feat(plugins/konflux-backend): add backend plugin for Konflux …

8b3bb26

…integration

fixup! feat(plugins/konflux): add frontend plugin for Konflux resources

f3d6fef

fixup! chore(konflux/app): add konflux config

9f59958

fixup! feat(plugins/konflux-backend): add backend plugin for Konflux …

de7097d

…integration

fixup! feat(plugins/konflux): add frontend plugin for Konflux resources

7649bae

chore(konflux): fix dependencies dedupe issues

25c02b2

Fix dependencies dedupe issues.

rrosatti force-pushed the konflux-plugin branch from 95f39f1 to 25c02b2 Compare January 16, 2026 12:42

hopehadfield requested changes Jan 16, 2026

View reviewed changes

-  "backstage": {
-    "role": "backend"
-  },
+  "backstage": {
+    "role": "backend-plugin",
+    "pluginId": "konflux",
+    "pluginPackage": "@red-hat-developer-hub/backstage-plugin-konflux-backend",
+    "pluginPackages": [
+      "@red-hat-developer-hub/backstage-plugin-konflux",
+      "@red-hat-developer-hub/backstage-plugin-konflux-backend",
+      "@red-hat-developer-hub/backstage-plugin-konflux-common"
+    ]
+  },

Add Konflux plugin #1826

Are you sure you want to change the base?

Add Konflux plugin #1826

Conversation

rrosatti commented Nov 19, 2025

Add Konflux Plugin for Backstage

Overview

Alpha Testing Phase

Fixes

Architecture

Key Features

How It Works

Visual References

Demo Video

Screenshots

Configuration

app Configuration (app-config.yaml)

Entity Configuration (catalog-info.yaml)

Testing

✔️ Checklist

Uh oh!

rhdh-gh-app bot commented Nov 19, 2025

Changed Packages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 17, 2025

Uh oh!

testcara Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

testcara left a comment

Choose a reason for hiding this comment

Uh oh!

testcara left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Jan 16, 2026

Quality Gate passed

Uh oh!

hopehadfield left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

app Configuration (`app-config.yaml`)

Entity Configuration (`catalog-info.yaml`)

testcara Jan 13, 2026 •

edited

Loading