feat (intelligent-assistant): add optional OKP flavour for Intelligent Assistant [RHIDP-16103]

[maysunfaisal]

Description

Add Offline Knowledge Portal (OKP) as an optional add-on flavour for Intelligent Assistant, building on the generic flavour templating and plugin-dependency infrastructure introduced by #3477.

• Keep the default intelligent-assistant experience unchanged and enabled without OKP.
• Add an explicit intelligent-assistant-okp flavour that:
  • adds the okp dependency to the Intelligent Assistant backend plugin;
  • creates the OKP Deployment and Service;
  • selects the OKP-enabled LCORE configuration; and
  • adds the LCORE NetworkPolicy required for HTTP access to OKP.
• On OpenShift, create an edge-terminated OKP Route and automatically configure OKP_SERVICE_URL with its HTTP URL.
• On Kubernetes, leave registry authentication, Ingress, TLS, and the public OKP_SERVICE_URL to the user because the Operator does not manage Ingress.
• Apply unmentioned default flavours first and explicitly configured flavours in CR declaration order, ensuring add-on patches deterministically override their base flavour.
• Use the intelligent-assistant-okp-* resource prefix consistently for the OKP Deployment, Service, and Route.
• Document OpenShift and Kubernetes enablement, including optional HTTPS with a private CA.
• Regenerate the RHDH bundle and installer manifests and add integration coverage for both IA-only and IA-with-OKP configurations.

OKP remains disabled by default. The OKP image is large, so explicitly enabling it can make the first installation significantly slower while the image is downloaded.

Which issue(s) does this PR fix or relate to

https://redhat.atlassian.net/browse/RHIDP-16103

PR acceptance criteria

• Tests
• Documentation

How to test changes / Special notes to the reviewer

Intelligent Assistant without OKP

Deploy a Backstage CR with only the base flavour:

spec:
  flavours:
    - name: intelligent-assistant
      enabled: true

Verify that RHDH and LCORE become ready and that no intelligent-assistant-okp-* resources, OKP_SERVICE_URL, or OKP RAG configuration are present.

OpenShift with OKP

Enable both flavours:

spec:
  flavours:
    - name: intelligent-assistant
      enabled: true
    - name: intelligent-assistant-okp
      enabled: true

Verify:

oc get deployments,services,routes -n <namespace> | grep intelligent-assistant-okp
oc get deployment backstage-<backstage-name> -n <namespace> \
  -o jsonpath='{.spec.template.spec.containers[?(@.name=="lightspeed-core")].env}'

Confirm that the OKP Deployment, Service, and Route are ready, OKP_SERVICE_URL uses the generated HTTP Route, LCORE is ready, and Intelligent Assistant returns clickable OKP citations.

Optional HTTPS configuration for a private OpenShift router CA is documented in docs/intelligent-assistant-okp-openshift.md.

Kubernetes with OKP

Enable both flavours, configure registry.redhat.io authentication, create an Ingress, and inject its public URL as OKP_SERVICE_URL. Follow docs/intelligent-assistant-okp-kubernetes.md for the complete HTTP or HTTPS setup.

Confirm that the OKP Deployment and Service are ready, LCORE can reach the configured Ingress, and citation links are reachable from the browser.

Validation performed

• make lint
• make local-dynamic-plugins && make test
• make integration-test ARGS='--focus "create default rhdh"'
• make gosec
• make bundles build-installers
• OpenShift: IA-only, OKP over HTTP, and OKP over HTTPS with a private router CA
• Kind on AMD64 Linux: IA-only and OKP with user-managed HTTP and HTTPS Ingress

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.15%. Comparing base (ea4d171) to head (cbdf95b).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3370      +/-   ##
==========================================
+ Coverage   59.56%   60.15%   +0.59%     
==========================================
  Files          49       51       +2     
  Lines        3507     3574      +67     
==========================================
+ Hits         2089     2150      +61     
- Misses       1226     1230       +4     
- Partials      192      194       +2     

Flag	Coverage Δ
nightly	?
unittests	60.15% <100.00%> (+0.59%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
pkg/model/flavour.go	80.88% <100.00%> (+4.95%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[maysunfaisal]

Corresponding rhdh-chart PR redhat-developer/rhdh-chart#500

[rm3l]

/build-images

[github-actions]

❌ Image build failed

See workflow run for details: https://github.com/redhat-developer/rhdh-operator/actions/runs/32705736214

Triggered by @rm3l

[rm3l]

/build-images

[github-actions]

❌ Image build failed

See workflow run for details: https://github.com/redhat-developer/rhdh-operator/actions/runs/32705962118

Triggered by @rm3l

[maysunfaisal]

/build-images

[github-actions]

✅ PR images built successfully!

Images are available for testing:

1. Operator: quay.io/rhdh-community/operator:2.0.0-pr-3370-9726670
2. Bundle: quay.io/rhdh-community/operator-bundle:2.0.0-pr-3370-9726670
3. Catalog: quay.io/rhdh-community/operator-catalog:2.0.0-pr-3370-9726670

Also available with PR number tag:

• quay.io/rhdh-community/operator:2.0.0-pr-3370
• quay.io/rhdh-community/operator-bundle:2.0.0-pr-3370
• quay.io/rhdh-community/operator-catalog:2.0.0-pr-3370

_{Triggered by @maysunfaisal}

[Jdubrick]

Just a general question as well: will OKP get cleaned up if someone disables the lightspeed flavour?

[rm3l]

/cc @gazarenkov

[maysunfaisal]

/build-images

[github-actions]

✅ PR images built successfully!

Images are available for testing:

1. Operator: quay.io/rhdh-community/operator:2.0.0-pr-3370-ec0b6e3
2. Bundle: quay.io/rhdh-community/operator-bundle:2.0.0-pr-3370-ec0b6e3
3. Catalog: quay.io/rhdh-community/operator-catalog:2.0.0-pr-3370-ec0b6e3

Also available with PR number tag:

• quay.io/rhdh-community/operator:2.0.0-pr-3370
• quay.io/rhdh-community/operator-bundle:2.0.0-pr-3370
• quay.io/rhdh-community/operator-catalog:2.0.0-pr-3370

_{Triggered by @maysunfaisal}

[gazarenkov]

To add the additional resources needed for your plugin please use Plugin dependencies feature instead.

You can see how it implemented in orchestrator flavour as well (it uses sonataflow dependencies).

[maysunfaisal]

To add the additional resources needed for your plugin please use Plugin dependencies feature instead.

You can see how it implemented in orchestrator flavour as well (it uses sonataflow dependencies).

Thanks @gazarenkov, looked into plugin-deps for OKP. Our manifests are already declarative YAML, not imperative Go:

config/profile/rhdh/default-config/flavours/lightspeed/
  okp-deployment.yaml
  okp-service.yaml
  okp-route.yaml

The Go wrappers (pkg/model/okp-*.go) only add metadata + platform gating. okp.go creates nothing and it just handles two things plugin-deps can't:

1. OpenShift gating — OKP uses a Route, which doesn't exist on vanilla K8s. LCORE also crashes if rag/okp config is present but Solr is unreachable, so the operator must strip those config sections on non-OpenShift. Plugin-deps applies unconditionally.

2. OKP_SERVICE_URL injection — LCORE needs to know where OKP lives. The URL is built at runtime from the CR name + cluster ingress domain (e.g. http://lightspeed-okp-<name>-<ns>.<domain>), then injected into the LCORE container env. Plugin-deps only creates standalone resources — it can't modify another container's env.

	plugin-deps	OKP needs
Platform gating	No	Skip all 3 resources on vanilla K8s
Env injection into another container	No	OKP_SERVICE_URL → LCORE
Config swap by platform	No	Strip rag/okp on K8s

Orchestrator's sonataflow deps are standalone resources, no cross-container wiring or platform gating needed. OKP needs both.

Open to discussion if there's a path to extend plugin-deps for these cases!

[gazarenkov]

Thanks for explanations, @maysunfaisal

I think I understand your point and it tells me that we probably would need a bit improve the framework to:

• have platform gating in plugin-deps
• make it possible to inject env vars and mount files using not only static resources name but templating it like "my-service-<cr-name>"

But before going to it, I would like to understand why it is important in this concrete case. Please correct me if I am wrong:

• As I can see The OKP container (Solr + httpd) is "standard" and should work on any K8s.

• The service provided by this container should be accessible internally, especially since in LCORE container is in the same namespace.

• So, we create Deployment, Service and send via env var the URL to LCORE. Why do we need Openshift Route?

• Question: Do we need OKP instance (Deployment, Service) per RHDH instance or it can be shared inside namespace? (just to understand how important is it, in practice several RHDH instances per workspace hardly needed in absolutely most cases)

[maysunfaisal]

Thanks for explanations, @maysunfaisal

[.. truncated ..]

• Question: Do we need OKP instance (Deployment, Service) per RHDH instance or it can be shared inside namespace? (just to understand how important is it, in practice several RHDH instances per workspace hardly needed in absolutely most cases)

Thanks @gazarenkov, great questions. Let me address each (with Agentic help as it was used for rhdh-operator and rhdh-chart):

Why the Route?

OKP isn't just a backend for LCORE — it also serves the RAG reference pages that users click in the chat UI. When the Intelligent Assistant/Lightspeed chatbot returns grounded answers, the response includes clickable reference_urls (e.g. RHDH product docs). Those links point to OKP's httpd, which serves the indexed content. The user's browser needs to reach OKP to render those pages.

A ClusterIP Service is only reachable from within the cluster. The browser is outside — so without a Route (or Ingress), the reference links are dead.

Why OpenShift-only gating?

Two reasons:

1. The OKP image (registry.redhat.io/offline-knowledge-portal/rhokp-rhel9) requires Red Hat registry auth. On OpenShift, the global pull secret handles this automatically. On vanilla K8s, users would need to manually configure imagePullSecrets — the chart supports this as an opt-in (okp.imagePullSecrets), but it's not a seamless default experience. On rhdh-local for example, users would need to podman login. (As to why RHOKP does not support a public image, you can read their justification here and it was brought up to them how this is not ideal. Mainly because of licenses and OKP image have RH Knowledge Base..)

2. The operator currently has no Ingress support (tracked as RHDHPLAN-423 / RHIDP-2176). Without Ingress, there's no way to expose OKP externally on vanilla K8s. So OpenShift (Route) is the only viable path in the operator today.

On the chart side redhat-developer/rhdh-chart#500, we do support vanilla K8s as an opt-in — users set okp.ingress.host and it renders an Ingress instead of a Route.

One OKP per RHDH instance — temporary

Yes, currently each RHDH install provisions its own OKP Deployment. We've raised this with the OKP team and they have an epic for standalone installation: RHOKP-1632 with child stories for Helm (RHOKP-1690) and Operator (RHOKP-1691) deployment. Once those land, OKP can be independently installed and shared. We have had discussions about this in meeting with the RHOKP team and how it is not a great UX.

[gazarenkov]

@maysunfaisal
Thanks for info

Route

Curious how UX of K8s vs Openshift end-users differs?

What if we provide Route based automation for Openshift users only and for K8s instruct that for this feature they have to configure the networking (ingress, loadbalancer etc) and provide it's URL manually?
This way Deployment and Service are functional in any platform but external assess requires additional actions in k8s

I see why we need this conditional deployment (at least for Route), let me think how to implement it better with plugin-deps (it should not be that complex I think)

OKP instances

I understand, deploying it independently makes sense in prod (however self-created instance is useful for quick start scenario). This way the only thing the plugin needed is URL (or 2 URLs: internal and external), no additional resources to create.

So, as the per-RHDH is not the point we can consider per-namespace (which in most cases the same), right?

[maysunfaisal]

@gazarenkov

Route

Yes, that's exactly how it works today in this PR. On OpenShift, the operator creates a Route automatically. On vanilla K8s, the operator does not create any networking resource because there is no Ingress support; the user would need to configure Ingress/LoadBalancer themselves and provide the URL. The Helm chart takes a similar approach where it auto-detects OpenShift for Route creation, and offers opt-in Ingress on K8s.

Regarding enhancing plugin-deps with platform gating and templated env injection, happy to refactor to use that once it's available, but I'd prefer not to block this PR on that future work unless the turn around time is 1 day or so. We are currently blocking on other 2.1 Feature work for Intelligent Assistant (this repo as @Jdubrick is putting some changes in + midstream Gitlab rhdh repo for pinning OKP digest image and removing the old RHDH RAG from Lightspeed) due to these PRs and we have one Sprint before 2.1 FF.

OKP instances

Per-CR is intentional as it keeps lifecycle simple since each CR owns its OKP and cleans it up on delete (at the cost of fist time quick start and resource consumption).

Per-namespace is possible without any bundle or midstream impact (the OKP resources stay in the flavour ConfigMap either way), but it adds reconciliation complexity: multiple Backstage CRs would race on the same OKP Deployment, and we'd need to coordinate who owns it and when to delete it.

If the goal is a shared, independently-managed OKP, the OKP team is working on that under RHOKP-1632, they also have OKP as MCP for Q4 on their agenda, so I am not trying to over-engineer how OKP is deployed right now, for what may seem to be temporary.

(This is also consistent with redhat-developer/rhdh-chart#500 where we have one RHDH/LCORE deployment and OKP deployment per helm release).

What are your thoughts?

[gazarenkov]

@maysunfaisal
thanks for info

Based on our conversation I've identified the following framework enhancements we could implement:

1. Templating support for default-config - make it possible to reference internal services per-instance, e.g. URL=http://okp-{{.Backstage.Name}}
2. Plugin dependencies platform gating, can make it with dedicated annotation like rhdh.redhat.com/platform= to apply resources only on specific platforms

The only question I have for the time: where do we need to inject the Route-related URL to be used in frontend? My understanding it should be backstage container but as I can see you inject it to Lcore container. Thoughts?

but I'd prefer not to block this PR on that future work unless the turn around time is 1 day or so. We are currently blocking on other 2.1 Feature work for Intelligent Assistant

I am sorry to not to know about this approach earlier, the problem is that it introduces plugin-specific logic directly into the operator model, which isn't the direction we want to take, it is hardly supportable way. The operator should remain plugin-agnostic and provide generic mechanisms that any plugin can leverage.
To help to implement it ASAP I've created the Feature to track: https://redhat.atlassian.net/browse/RHDHPLAN-1763
I spent some time on it and think I can make a POC shortly and share to test with your config and see.

Thanks

[maysunfaisal]

@gazarenkov

The only question I have for the time: where do we need to inject the Route-related URL to be used in frontend? My understanding it should be backstage container but as I can see you inject it to Lcore container. Thoughts?

The ENV injection is happening to the LCORE container here in my changes https://github.com/redhat-developer/rhdh-operator/pull/3370/changes#diff-f16bc2e3b21ea94fe1e0cb23af92be4335ce36540bcef4c07d420c97067aeb6dR26 (internal/controller/okp.go - prepareOkpEnvVar())

This is relatively easy on rhdh-chart due to helm templating magic but i had to do this for Go operator.

The OKP deployment is separate from the RHDH/LCORE deployment; so we had to use the above approach to get the OKP Route endpoint and set it to OKP_SERVICE_URL into the lightspeed-core container (LCORE) because LCORE service needs to connect to OKP Service for RAG to work. Check out the gist for the Container Spec from when I had RHDH pod running from a redhat-developer/rhdh-chart#500 test i did earlier today with Armel reviews. Let me know if you have further questions about OKP_SERVICE_URL. Here are all the resources from the same rhdh-chart test for reference (it is similar for this PR):

$ oc get po,deploy,svc,route,secret -n rhdh-test
NAME                                                    READY   STATUS    RESTARTS   AGE
pod/rhdh-postgresql-0                                   1/1     Running   0          99m
pod/rhdh-redhat-developer-hub-5cc69f5c74-dz6xq          2/2     Running   0          41m
pod/rhdh-redhat-developer-hub-ia-okp-7fd8c74879-xxpmm   1/1     Running   0          99m

NAME                                               READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/rhdh-redhat-developer-hub          1/1     1            1           99m
deployment.apps/rhdh-redhat-developer-hub-ia-okp   1/1     1            1           99m

NAME                                       TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
service/rhdh-postgresql                    ClusterIP   172.30.202.197   <none>        5432/TCP            99m
service/rhdh-postgresql-hl                 ClusterIP   None             <none>        5432/TCP            99m
service/rhdh-redhat-developer-hub          ClusterIP   172.30.64.162    <none>        7007/TCP,9464/TCP   99m
service/rhdh-redhat-developer-hub-ia-okp   ClusterIP   172.30.67.118    <none>        8080/TCP            99m

NAME                                                        HOST/PORT                                                                                   PATH   SERVICES                           PORT           TERMINATION     WILDCARD
route.route.openshift.io/rhdh-redhat-developer-hub          rhdh-redhat-developer-hub-rhdh-test.apps.mfaisal-sep032026.rhdh-pai.devfile-ci.com          /      rhdh-redhat-developer-hub          http-backend   edge/Redirect   None
route.route.openshift.io/rhdh-redhat-developer-hub-ia-okp   rhdh-redhat-developer-hub-ia-okp-rhdh-test.apps.mfaisal-sep032026.rhdh-pai.devfile-ci.com          rhdh-redhat-developer-hub-ia-okp   httpd          edge/Allow      None

So, the RHDH plugin Intelligent Assistant frontend just renders what LCORE returns - OKP links pointing to RHDH docs in OKP Service. User is able to click them on the browser and see the RHDH docs from OKP service.

LCORE needs the OKP Route URL to construct the citation links on LCORE server-side.

I am sorry to not to know about this approach earlier, the problem is that it introduces plugin-specific logic directly into the operator model, which isn't the direction we want to take, it is hardly supportable way. The operator should remain plugin-agnostic and provide generic mechanisms that any plugin can leverage.

I understand the sentiment but Intelligent Assistant (IA, formerly Lightspeed) is now included by default OOTB as a flavor with upstream RHDH. Previously, Lightspeed used initContainers and volume mounts directly to RHDH deployment to set up RAG but that is now taken away and replaced by a standalone OKP Deployment/Svc/Route. From my POV, I was just plugging out and plugging in how RAG is set up. OKP resources are just dependencies of a default config Lightspeed/IA.

Maybe standalone OKP resources and platform gating is a deal breaker? But let me know how you feel about this and also about your progress on https://redhat.atlassian.net/browse/RHDHPLAN-1763 because I may have to react differently based on that decision like whether I can make OKP changes to upstream and midstream before FF 🤔

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[github-actions]

✅ PR images built and pushed successfully!

Images are available for testing (expires in 7 days):

Image	Full tag	PR tag
Operator	quay.io/rhdh-community/operator:2.0.0-pr-3370-cbdf95b	quay.io/rhdh-community/operator:2.0.0-pr-3370
Bundle	quay.io/rhdh-community/operator-bundle:2.0.0-pr-3370-cbdf95b	quay.io/rhdh-community/operator-bundle:2.0.0-pr-3370
Catalog	quay.io/rhdh-community/operator-catalog:2.0.0-pr-3370-cbdf95b	quay.io/rhdh-community/operator-catalog:2.0.0-pr-3370

[maysunfaisal]

@gazarenkov

I updated #3370 on top of your merged #3477:

• IA without OKP remains the default.
• New intelligent-assistant-okp add-on flavour enables OKP.
• OpenShift setup is automatic; Kubernetes Ingress/TLS is documented.
• Tested IA-only and OKP HTTP/HTTPS on OpenShift and K8s (K8s Kind on EC2 instance).

Pls take a look, the previous diff and several older comments are now outdated.

[maysunfaisal]

/build-images