> For the complete documentation index, see [llms.txt](https://docs.trilio.io/kubernetes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilio.io/kubernetes/appendix/integrations/openshift-lightspeed-integration.md).

# OpenShift Lightspeed Integration

* [Prerequisites](#prerequisites)
* [How It Works](#how-it-works)
* [Automatic Enablement](#automatic-enablement)
* [Verify the Integration](#verify-the-integration)
* [Disable Automatic Integration](#disable-automatic-integration)
* [Manual Installation](#manual-installation)
* [Disconnected / Air-Gapped Clusters](#disconnected--air-gapped-clusters)
* [Install Ordering and Troubleshooting](#install-ordering-and-troubleshooting)
* [Limitations](#limitations)
* [Related Documentation](#related-documentation)

Trilio for Kubernetes (TVK) integrates with [OpenShift Lightspeed](https://docs.openshift.com/lightspeed/) (OLS) so that TVK documentation is available inside the Lightspeed AI assistant. When the TVK operator is installed on an OpenShift cluster that has the OpenShift Lightspeed operator running, TVK documentation is wired into Lightspeed automatically through a RAG (Retrieval-Augmented Generation) container image.

Cluster admins can ask TVK-related questions directly in the Lightspeed console — for example, *"How do I create a TVK backup policy?"* — and receive answers grounded in TVK documentation.

## Prerequisites

* An **OpenShift** cluster. This integration is OpenShift-only; it is not available on upstream or vanilla Kubernetes installs.
* The **OpenShift Lightspeed operator** installed and configured on the cluster.
* The **Trilio for Kubernetes operator** installed via OLM (Red Hat Marketplace or a custom catalog).
* A **TrilioVaultManager (TVM)** custom resource created so the TVK stack is running.

TVK does **not** install or manage the OpenShift Lightspeed operator. OLS must be installed separately.

## How It Works

The TVK operator reconciles `OLSConfig` resources managed by the OpenShift Lightspeed operator. When integration is enabled, the operator ensures that `spec.ols.rag[]` on **each** `OLSConfig` resource contains a TVK entry:

```yaml
- image: registry.redhat.io/triliovault-for-kubernetes/tvk-lightspeed-rag-content-rhel9@sha256:<digest>
  indexID: tvk_rag_index
  indexPath: /rag/vector_db
```

Key behaviors:

* Entries are matched by `indexID: tvk_rag_index`, never by array position. Other RAG entries in `spec.ols.rag[]` are not modified.
* The RAG image reference is pinned to the TVK operator release via `spec.relatedImages` in the operator's ClusterServiceVersion.
* On TVK operator upgrade, the image reference in `OLSConfig` is updated automatically when the digest changes.
* When integration is disabled or no active TVM exists, the TVK entry is removed from `OLSConfig`.

```mermaid
flowchart LR
    subgraph admin [Admin]
        TVM["TrilioVaultManager CR\nmanageOLSConfig: true"]
    end
    subgraph tvkOp [TVK Operator]
        SyncOLS["SyncOLS"]
    end
    subgraph ols [OpenShift Lightspeed]
        OLSConfig["OLSConfig\nspec.ols.rag[]"]
        RAGImage["tvk-lightspeed-rag-content image"]
        LightspeedUI["Lightspeed Console"]
    end
    TVM --> SyncOLS
    SyncOLS -->|"inject tvk_rag_index entry"| OLSConfig
    OLSConfig --> RAGImage
    RAGImage --> LightspeedUI
```

## Automatic Enablement

No manual configuration is required in the common case. Integration is **enabled by default**:

* `spec.openshiftLightspeed.manageOLSConfig` defaults to `true` in the TVM CRD schema.
* If the `openshiftLightspeed` block is omitted entirely, the operator treats integration as enabled.

When both the TVK and OpenShift Lightspeed operators are installed and at least one active TVM exists:

1. The TVK operator detects the `olsconfigs.ols.openshift.io` CRD.
2. It injects the TVK RAG entry into `spec.ols.rag[]` on each `OLSConfig` resource.
3. On TVK operator upgrade, the image reference is updated to match the new operator release.
4. When the last active TVM is removed, the TVK RAG entry is cleaned up from `OLSConfig`.

If the OpenShift Lightspeed operator is not installed, the TVK operator runs normally. The integration controller idles without error.

## Verify the Integration

Confirm the TVK RAG entry is present:

```bash
oc get olsconfig -o yaml
```

Look for an entry with `indexID: tvk_rag_index` under `spec.ols.rag[]`.

Inspect the TVM spec field:

```bash
oc explain triliovaultmanager.spec.openshiftLightspeed
```

Ask a TVK-related question in the OpenShift Lightspeed console and confirm the answer references TVK documentation.

## Disable Automatic Integration

To disable automatic RAG injection, set `spec.openshiftLightspeed.manageOLSConfig` to `false` on your TVM CR:

```yaml
apiVersion: triliovault.trilio.io/v1
kind: TrilioVaultManager
metadata:
  name: triliovault-manager
spec:
  applicationScope: Cluster
  openshiftLightspeed:
    manageOLSConfig: false
```

Or apply the change imperatively:

```bash
oc patch triliovaultmanager triliovault-manager \
  --type=merge \
  -p '{"spec":{"openshiftLightspeed":{"manageOLSConfig":false}}}'
```

When disabled, the operator:

* Removes the TVK RAG entry (`indexID: tvk_rag_index`) from each `OLSConfig` resource.
* Does not modify any other entries in `spec.ols.rag[]`.
* Stops managing `OLSConfig` until `manageOLSConfig` is set back to `true`.

Setting `manageOLSConfig` back to `true` re-injects the TVK RAG entry.

## Manual Installation

For administrators who disable automatic injection but still want TVK documentation in Lightspeed, add the following entry manually to `spec.ols.rag[]` on your `OLSConfig` resource:

```yaml
apiVersion: ols.openshift.io/v1alpha1
kind: OLSConfig
metadata:
  name: cluster
spec:
  ols:
    rag:
      - image: registry.redhat.io/triliovault-for-kubernetes/tvk-lightspeed-rag-content-rhel9@sha256:<digest>
        indexID: tvk_rag_index
        indexPath: /rag/vector_db
```

Replace `<digest>` with the digest of the TVK RAG image shipped with your installed TVK operator version. To find the digest, inspect `spec.relatedImages` in the installed operator's ClusterServiceVersion:

```bash
oc get csv -n <operator-namespace> \
  -l operators.coreos.com/k8s-triliovault.<operator-namespace>= \
  -o jsonpath='{range .items[0].spec.relatedImages[*]}{.name}{"\t"}{.image}{"\n"}{end}' \
  | grep tvk-lightspeed-rag-content
```

## Disconnected / Air-Gapped Clusters

The TVK RAG image is listed in `spec.relatedImages` of the operator's ClusterServiceVersion. When administrators mirror the TVK operator catalog for a disconnected cluster using `oc mirror`, the RAG image is included alongside the operator images.

No additional configuration is needed for disconnected OpenShift installs that use OLM catalog mirroring. The mirrored image reference is resolved automatically by OLM.

This integration applies only to OpenShift clusters that use OLM mirroring. The TVK air-gapped image bundle used for upstream Kubernetes distributions does not include this RAG image, because OpenShift Lightspeed is not available on those platforms.

## Install Ordering and Troubleshooting

### OLS not installed

TVK installs and runs normally. The integration controller detects that the `OLSConfig` CRD is absent and skips RAG sync. No action is required unless you later install OpenShift Lightspeed.

### TVK installed before OpenShift Lightspeed

If TVK is installed before the OpenShift Lightspeed operator:

1. Install the OpenShift Lightspeed operator and create an `OLSConfig` resource.
2. Trigger a TVM reconcile by patching the TVM CR, or restart the TVK operator pod.

The TVK operator registers its `OLSConfig` watch only when the OLS CRD is present **at operator pod startup**. If OLS is installed after TVK, restart the TVK operator pod (or roll the deployment) so that external changes to `spec.ols.rag[]` are watched and the initial RAG entry is injected promptly.

### No OLSConfig resources yet

If the OLS CRD exists but no `OLSConfig` resources have been created, the integration waits. TVK continues to run normally. Create an `OLSConfig` resource (typically named `cluster`) and trigger a TVM reconcile or restart the TVK operator pod.

### All TVMs deleted

When no active TVM instances remain, the TVK operator removes the `tvk_rag_index` entry from each `OLSConfig` resource.

### TVK RAG entry removed externally

If `manageOLSConfig` is `true` and an active TVM exists, the operator re-injects the TVK RAG entry on the next reconcile when it detects the entry is missing.

### Multiple TVM instances

If any active TVM has `manageOLSConfig: false`, automatic injection is disabled cluster-wide. TVMs that are terminating (deletion in progress) are ignored when evaluating the opt-out setting.

## Limitations

* TVK does not install, upgrade, or manage the OpenShift Lightspeed operator.
* The `OLSConfig` watch is registered only when the OLS CRD exists at TVK operator startup. Restart the TVK operator pod after installing OLS if TVK was installed first.
* RAG content is version-locked to the TVK operator release (embedded at image build time). Updating documentation requires a new RAG image build and TVK operator upgrade.
* This feature is available on OpenShift only.

## Related Documentation

* [Installing Trilio for Kubernetes on Red Hat OpenShift (OCP)](/kubernetes/installation/platforms/red-hat-openshift.md)
* [Custom CatalogSource in a restricted environment](/kubernetes/appendix/platform-guides/operatorhub-custom-catalogsource/restricted-network-installation-for-tvk-on-ocp-openshift.md)
* [OpenShift Lightspeed documentation](https://docs.openshift.com/lightspeed/)