OLS-2882: Add spec files to the projects for AI-assisted development by joshuawilson · Pull Request #1536 · openshift/lightspeed-operator

joshuawilson · 2026-04-20T03:13:23Z

Description

Initial set of spec files to enable Agentic SDLC.

Type of change

Related Tickets & Documents

Related Issue #
Closes #

Checklist before requesting a review

I have performed a self-review of my code.
PR has passed all pre-merge test jobs.
If it is a core feature, I have added thorough tests.

Testing

Please provide detailed steps to perform tests related to this code change.
How were the fix/results from this change verified? Please provide relevant screenshots or results.

Two-layer spec structure under .ai/spec/: - what/ (11 files): behavioral rules for system-overview, CRD API, reconciliation, app-server, lcore, postgres, console-ui, TLS, security, external-resources, and observability - how/ (4 files): architecture specs for project-structure, reconciliation, deployment-generation, and config-generation Specs are optimized for AI agent consumption and document the operator thoroughly enough to enable a from-scratch rewrite. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

openshift-ci-robot · 2026-04-20T03:13:27Z

openshift-ci · 2026-04-20T03:13:36Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign joshuawilson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

openshift-ci · 2026-04-20T03:24:07Z

@joshuawilson: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

JoaoFula · 2026-04-29T13:12:51Z

+3. The operator is fully event-driven. It does not use periodic/timer-based reconciliation. All changes are detected via Kubernetes watches on owned resources and annotated external resources.
+4. The operator selects between two mutually exclusive backend implementations at startup via the `--use-lcore` flag: AppServer (legacy, direct LLM proxy) or LCore (new, agent-based with Llama Stack). Both implement the same Lightspeed API surface.
+
+### Component Inventory


shouldn't we expand this to match the list of components from https://konflux-ui.apps.stone-prd-rh01.pg1f.p1.openshiftapps.com/ns/crt-nshift-lightspeed-tenant/applications/ols/components?

We can but the spec files are specific to the repo.
Could create a higher level set of specs that cover all repos and konflux.

see comment below

blublinsky · 2026-04-30T07:49:15Z

+1. The Llama Stack database name is hardcoded by the Llama Stack project and must not be changed.
+2. Llama Stack Generic mode cannot be mixed with legacy provider-specific fields (deploymentName, projectID, url, apiVersion).
+3. The Lightspeed Stack always connects to Llama Stack via localhost, even in server mode (they share a pod).
+4. Vector database IDs are sanitized from RAG image names if indexID is not explicitly provided.


This whole thing is going to be removed in this sprint

blublinsky · 2026-04-30T08:01:36Z

+|---|---|---|---|
+| `--use-lcore` | bool | `false` | Select LCore backend instead of AppServer |
+| `--lcore-server` | bool | `true` | LCore server mode (two containers) vs library mode (one container) |
+| `--namespace` | string | `WATCH_NAMESPACE` env or `openshift-lightspeed` | Operator namespace |


Lcore is going away this sprint

blublinsky · 2026-04-30T08:03:00Z

+| OLS-2322 | Streamline OLSConfig CR deployment configuration |
+| OLS-2323 | Extend OLSConfig CR to report specific deployment errors |
+| OLS-2325 | Create type-safe log-level definition in the operator CR |
+| OLS-2140 | Remove time-based operator reconciliation (completed -- now fully event-driven) |


Maybe add here “delivery map” subsection: one short table or bullet list that maps repo components → Konflux application names (or “see Konflux UI → ols app → components”) with a disclaimer: operator repo spec describes operator-managed workloads; Konflux may list additional CI/catalog components. That answers JoaoFula’s question without duplicating Konflux in every spec.

blublinsky · 2026-04-30T08:12:54Z

+
+### Operator Role
+
+1. The operator manages exactly one OLSConfig CR per cluster, named "cluster". CRs with any other name must be ignored.


OLSConfig is treated as a singleton per cluster: the operator only reconciles the cluster-scoped instance named cluster. Any other OLSConfig objects are ignored. Reconciled workloads are created in the openshift-lightspeed namespace.

blublinsky · 2026-04-30T08:14:12Z

+### Operator Role
+
+1. The operator manages exactly one OLSConfig CR per cluster, named "cluster". CRs with any other name must be ignored.
+2. The operator deploys and manages four components: an application backend (AppServer or LCore), a PostgreSQL database, a Console UI plugin, and operator-level monitoring/networking resources.


mixing external resources with the operator's own infrastructure

blublinsky · 2026-04-30T08:14:54Z

+1. The operator manages exactly one OLSConfig CR per cluster, named "cluster". CRs with any other name must be ignored.
+2. The operator deploys and manages four components: an application backend (AppServer or LCore), a PostgreSQL database, a Console UI plugin, and operator-level monitoring/networking resources.
+3. The operator is fully event-driven. It does not use periodic/timer-based reconciliation. All changes are detected via Kubernetes watches on owned resources and annotated external resources.
+4. The operator selects between two mutually exclusive backend implementations at startup via the `--use-lcore` flag: AppServer (legacy, direct LLM proxy) or LCore (new, agent-based with Llama Stack). Both implement the same Lightspeed API surface.


this is going away in this sprint

blublinsky · 2026-04-30T08:19:04Z

+6. Console UI Plugin: OpenShift console extension that provides the Lightspeed chat interface. Integrates via ConsolePlugin CR and proxies requests to the backend.
+7. AppServer backend: Python/FastAPI application that handles LLM queries, RAG retrieval, conversation management, and tool execution. Talks to LLM providers directly.
+8. LCore backend: Dual-container deployment (Llama Stack + Lightspeed Stack) that provides the same API but routes through Llama Stack for LLM communication, enabling agent-based tool use and provider abstraction.
+9. Operator-level resources: ServiceMonitor for operator metrics, NetworkPolicy restricting operator pod access.


I would suggest separating external with operator-level resources (observability support), and also add a cross-reference here to the specific docs

joshuawilson and others added 2 commits April 19, 2026 23:30

update agents to include PR workflow

c931045

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Apr 20, 2026

openshift-ci Bot requested review from blublinsky and bparees April 20, 2026 03:13

JoaoFula reviewed Apr 29, 2026

View reviewed changes

blublinsky reviewed Apr 30, 2026

View reviewed changes


		### Operator Role

		1. The operator manages exactly one OLSConfig CR per cluster, named "cluster". CRs with any other name must be ignored.

Conversation

joshuawilson commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Related Tickets & Documents

Checklist before requesting a review

Testing

Uh oh!

openshift-ci-robot commented Apr 20, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Related Tickets & Documents

Checklist before requesting a review

Testing

Uh oh!

openshift-ci Bot commented Apr 20, 2026

Uh oh!

openshift-ci Bot commented Apr 20, 2026

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!

blublinsky Apr 30, 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!

blublinsky Apr 30, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joshuawilson commented Apr 20, 2026 •

edited

Loading

openshift-ci-robot commented Apr 20, 2026 •

edited by openshift-ci Bot

Loading

blublinsky Apr 30, 2026 •

edited

Loading

blublinsky Apr 30, 2026 •

edited

Loading