Merge pull request #1731 from onmete/okp-adoption-specs

OLS-2607 update specs for OKP adoption

Author: openshift-merge-bot[bot]

.ai/spec/how/config-generation.md

@@ -68,15 +68,21 @@ ols_config:
   tls_config:
     tls_certificate_path: /etc/certs/lightspeed-tls/tls.crt
     tls_key_path: /etc/certs/lightspeed-tls/tls.key
-  reference_content:
+  reference_content:                          # only when spec.ols.rag is configured (BYOK)
     indexes:
-      - path: /app-root/rag/rag-0          # BYOK first (one per spec.ols.rag entry)
+      - path: /app-root/rag/rag-0            # one per spec.ols.rag entry
         index_id: <rag.IndexID>
         origin: <rag.Image>
-      - path: /app-root/vector_db/ocp_product_docs/<major>.<minor>  # OCP docs (unless byokRAGOnly)
-        index_id: ocp-product-docs-<major>_<minor>
-        origin: "Red Hat OpenShift <major>.<minor> documentation"
     embeddings_model_path: /app-root/embeddings_model
+  # OCP docs FAISS index entry removed — OCP docs are served by OKP via the RHOKP sidecar.
+
+  solr_hybrid:                                # always present unless byokRAGOnly
+    solr_http_base: "http://localhost:8080"
+    max_results: 10
+    hybrid_vector_boost: 8.0
+    hybrid_pool_docs: 100
+    hybrid_score_threshold: 0.0
+    hybrid_solr_timeout_s: 60
   user_data_collection:
     feedback_disabled: <computed: CRvalue || !dataCollectorEnabled>
     feedback_storage: /app-root/ols-user-data/feedback
@@ -201,8 +207,8 @@ These schemas are created by the bootstrap script.
 | Log level | CR `spec.ols.logLevel` | Enum: DEBUG, INFO, WARNING, ERROR, CRITICAL. Default: INFO |
 | PostgreSQL connection | `utils/constants.go` | Host built from service name + namespace + ".svc" |
 | TLS certs | Service-ca operator or user-provided secret | Path: `/etc/certs/lightspeed-tls/` |
-| RAG indexes | CR `spec.ols.rag[]` | File paths in config YAML |
-| OpenShift version | Reconciler options | Used for OCP docs RAG index path |
+| BYOK RAG indexes | CR `spec.ols.rag[]` | File paths in config YAML (BYOK only) |
+| RHOKP image | `--rhokp-image` flag | Image for RHOKP sidecar container |
 | MCP servers | CR `spec.mcpServers[]` + `spec.ols.introspectionEnabled` | Feature gated by `MCPServer` gate |
 | Tool filtering | CR `spec.ols.toolFilteringConfig` | Feature gated by `ToolFiltering` gate; requires MCP servers |
 | Proxy config | CR `spec.ols.proxyConfig` | Proxy URL + optional CA cert configmap |

.ai/spec/how/deployment-generation.md

@@ -39,6 +39,11 @@ GenerateOLSDeployment(r, cr)
   18. Set owner reference to OLSConfig CR
   19. Conditionally add data collector sidecar container ("lightspeed-to-dataverse-exporter")
   20. Conditionally add OpenShift MCP server sidecar container ("openshift-mcp-server")
+  21. Conditionally add RHOKP sidecar container ("rhokp") — always added unless byokRAGOnly is true.
+      Container: image from r.GetRHOKPImage(), port 8080, resources 2 CPU / 2 GiB RAM / 75 GiB ephemeral,
+      startup script disables Apache Listen 0.0.0.0:8443 to avoid port conflict.
+      Optional ACCESS_KEY env from rhokp-access-key secret.
+      Writable root filesystem (Solr data).
 ```
 
 ### Change Detection Pattern
@@ -63,6 +68,7 @@ Default resources by container:
 | AppServer `lightspeed-service-api` | 500m | - | 1Gi | 4Gi |
 | Data collector | 50m | - | 64Mi | 200Mi |
 | MCP server | 50m | - | 64Mi | 200Mi |
+| RHOKP `rhokp` | 2000m | 2000m | 2Gi | 2Gi |
 
 ### Volume/Mount Construction
 Volumes and mounts are built as slices and conditionally appended using inline append patterns.
@@ -100,6 +106,7 @@ Both must be true. The service ID is `"ols"` unless the CR has `openstack.org/li
 | Volume configmaps | Generated ConfigMaps | OLS config, nginx config, MCP server config |
 | Proxy env vars | `utils.GetProxyEnvVars()` | HTTP_PROXY, HTTPS_PROXY, NO_PROXY from cluster |
 | RAG images | CR `spec.ols.rag[].image` | Container images for init containers |
+| RHOKP image | `--rhokp-image` flag | Container image for RHOKP sidecar |
 
 ## Agentic Controller Deployment (OLM-managed)
 

.ai/spec/what/app-server.md

@@ -5,39 +5,40 @@ The App Server is the backend deployment for OpenShift Lightspeed. It runs the l
 ## Behavioral Rules
 
 ### Deployment Composition
-1. The deployment contains a primary API container and up to two optional sidecar containers.
+1. The deployment contains a primary API container and up to three sidecar containers.
 2. The primary container (lightspeed-service-api) runs the OLS service, listening on HTTPS.
 3. The data collector sidecar (lightspeed-to-dataverse-exporter) is added when data collection is enabled AND the telemetry pull secret exists in the openshift-config namespace with a cloud.openshift.com auth entry.
 4. The OpenShift MCP server sidecar is added when `spec.ols.introspectionEnabled` is true. It provides Kubernetes resource access via MCP protocol.
-5. A PostgreSQL wait init container always runs before the main containers to ensure database readiness.
-6. When `spec.ols.rag` is configured, additional init containers copy RAG data from container images into a shared volume.
+5. The RHOKP sidecar is always added to the deployment. It serves OKP (Offline Knowledge Portal) content via Solr HTTP on localhost:8080, providing Red Hat product documentation for tool-based retrieval. It requires ~75 GiB ephemeral storage. The RHOKP sidecar is NOT deployed when `spec.ols.byokRAGOnly` is true.
+6. A PostgreSQL wait init container always runs before the main containers to ensure database readiness.
+7. When `spec.ols.rag` is configured, additional init containers copy BYOK RAG data from container images into a shared volume.
 
 ### Configuration Mapping
-7. The operator generates an OLS config file (olsconfig.yaml) from the CR spec. This ConfigMap is the primary interface between the operator and the service.
-8. LLM provider credentials are mounted as files from their respective secrets, at a path derived from the secret name.
-9. The default credential key read from each provider's secret is "apitoken", overridable by `spec.llm.providers[].credentialKey`.
-10. PostgreSQL connection settings are hardcoded to point to the operator-managed PostgreSQL service within the same namespace.
-11. If `spec.ols.querySystemPrompt` is set, the custom prompt is written as a second key in the config ConfigMap and referenced by file path in the config.
-12. RAG reference content indexes are ordered: user-provided (BYOK) indexes first, then the OCP documentation index (unless `spec.ols.byokRAGOnly` is true).
-13. The OCP documentation RAG index path is derived from the detected OpenShift cluster version.
+8. The operator generates an OLS config file (olsconfig.yaml) from the CR spec. This ConfigMap is the primary interface between the operator and the service.
+9. LLM provider credentials are mounted as files from their respective secrets, at a path derived from the secret name.
+10. The default credential key read from each provider's secret is "apitoken", overridable by `spec.llm.providers[].credentialKey`.
+11. PostgreSQL connection settings are hardcoded to point to the operator-managed PostgreSQL service within the same namespace.
+12. If `spec.ols.querySystemPrompt` is set, the custom prompt is written as a second key in the config ConfigMap and referenced by file path in the config.
+13. BYOK reference content indexes from `spec.ols.rag` are configured when present. OCP documentation is served by OKP via the RHOKP sidecar, not via FAISS indexes.
+14. The operator always generates a `solr_hybrid` config section in `olsconfig.yaml` pointing to `http://localhost:8080` with default hybrid retrieval tuning parameters, unless `byokRAGOnly` is true.
 
 ### MCP Server Integration
-14. When `spec.ols.introspectionEnabled` is true, an "openshift" MCP server entry is added to the config pointing to localhost on the sidecar port.
-15. When the MCPServer feature gate is enabled, user-defined servers from `spec.mcpServers` are added to the config.
-16. MCP header values of type "secret" are mounted as files from the referenced secret. Types "kubernetes" and "client" use placeholder strings that the service resolves at runtime.
+15. When `spec.ols.introspectionEnabled` is true, an "openshift" MCP server entry is added to the config pointing to localhost on the sidecar port.
+16. When the MCPServer feature gate is enabled, user-defined servers from `spec.mcpServers` are added to the config.
+17. MCP header values of type "secret" are mounted as files from the referenced secret. Types "kubernetes" and "client" use placeholder strings that the service resolves at runtime.
 
 ### Service and Networking
-17. The service exposes HTTPS on the configured port.
-18. The network policy allows ingress from: Prometheus (openshift-monitoring), OpenShift Console (openshift-console), and ingress controllers.
-19. Egress is unrestricted (empty egress rules).
+18. The service exposes HTTPS on the configured port.
+19. The network policy allows ingress from: Prometheus (openshift-monitoring), OpenShift Console (openshift-console), and ingress controllers.
+20. Egress is unrestricted (empty egress rules).
 
 ### RBAC
-20. The service account is granted SubjectAccessReview and TokenReview permissions for user authorization.
-21. The service account can read the cluster version and the telemetry pull secret.
+21. The service account is granted SubjectAccessReview and TokenReview permissions for user authorization.
+22. The service account can read the cluster version and the telemetry pull secret.
 
 ### Change Detection
-22. Deployment updates are triggered when: the deployment spec changes, the config ConfigMap resource version changes, the MCP config ConfigMap resource version changes, or the proxy CA certificate hash changes.
-23. When any of these change, the operator forces a rolling restart by updating a pod template annotation with the current timestamp.
+23. Deployment updates are triggered when: the deployment spec changes, the config ConfigMap resource version changes, the MCP config ConfigMap resource version changes, or the proxy CA certificate hash changes.
+24. When any of these change, the operator forces a rolling restart by updating a pod template annotation with the current timestamp.
 
 ### Health Probes [CHANGED: OLS-3221]
 24. The app server deployment's liveness probe must point to the `/liveness` endpoint with `failureThreshold: 3` and `periodSeconds: 30`, giving the pod 90 seconds to self-heal via the background health-check loop before Kubernetes restarts it. These values are not currently user-configurable.
@@ -64,12 +65,12 @@ The App Server is the backend deployment for OpenShift Lightspeed. It runs the l
 | `spec.ols.logLevel` | Logging level for all service components |
 | `spec.ols.maxIterations` | Maximum agent execution iterations |
 | `spec.ols.querySystemPrompt` | Custom system prompt for LLM queries |
-| `spec.ols.byokRAGOnly` | Skip OCP documentation RAG index |
+| `spec.ols.byokRAGOnly` | Disable OKP (RHOKP sidecar not deployed, solr_hybrid config not generated). Only BYOK FAISS indexes are used. |
 | `spec.ols.introspectionEnabled` | Enable OpenShift MCP server sidecar |
 | `spec.ols.userDataCollection.feedbackDisabled` | Disable feedback collection |
 | `spec.ols.userDataCollection.transcriptsDisabled` | Disable transcript collection |
 | `spec.ols.queryFilters` | Query text pattern replacements |
-| `spec.ols.rag` | RAG database image references |
+| `spec.ols.rag` | BYOK RAG database image references |
 | `spec.ols.imagePullSecrets` | Pull secrets for RAG images |
 | `spec.ols.quotaHandlersConfig` | Token quota limiter configuration |
 | `spec.ols.toolFilteringConfig` | Tool filtering parameters (requires ToolFiltering feature gate) |
@@ -82,6 +83,7 @@ The App Server is the backend deployment for OpenShift Lightspeed. It runs the l
 2. Tool filtering requires MCP servers to be configured (either introspection or user-defined).
 3. The service always connects to PostgreSQL via the internal cluster service DNS.
 4. RAG init containers run in index order, copying data to subdirectories of the shared RAG volume.
+5. The RHOKP sidecar requires approximately 75 GiB of ephemeral storage for Solr data. This must be documented in product infrastructure requirements.
 
 ## Planned Changes