OpenShift Lightspeed Integration

Integrate Trilio for Kubernetes documentation with OpenShift Lightspeed

• Prerequisites

• How It Works

• BYOK RAG Only

• Enable TVK ingress

• Automatic Enablement

• Verify the Integration

• Disable Automatic Integration

• Manual Installation

• Disconnected / Air-Gapped Clusters

• Install Ordering and Troubleshooting

• Limitations

• Related Documentation

Trilio for Kubernetes (TVK) integrates with OpenShift 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.

• An OLSConfig custom resource with spec.ols.byokRAGOnly set to true (see BYOK RAG only).

• The Trilio for Kubernetes operator installed via OLM (Red Hat Marketplace or a custom catalog).

• A TrilioVaultManager (TVM) custom resource created with spec.ingressConfig.ingressEnabled: true so the TVK stack is running (see Enable TVK ingress).

TVK does not install or manage the OpenShift Lightspeed operator. OLS must be installed separately. Cluster admins create and maintain the OLSConfig resource, including the byokRAGOnly setting.

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:

- 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.

• TVK does not modify spec.ols.byokRAGOnly. Set that field on the OLSConfig when you create it (see BYOK RAG Only).

BYOK RAG Only

When you create the OLSConfig resource for OpenShift Lightspeed, set spec.ols.byokRAGOnly to true:

apiVersion: ols.openshift.io/v1alpha1
kind: OLSConfig
metadata:
  name: cluster
spec:
  ols:
    byokRAGOnly: true

With byokRAGOnly: true, Lightspeed uses only the RAG databases you provide (including the TVK RAG image) and does not use the default OpenShift Container Platform documentation RAG. The OpenShift Lightspeed operator also skips deploying the RHOKP sidecar.

TVK does not set or manage this field. You must set it on the OLSConfig CR when you create or update it. For more detail, see the OpenShift Lightspeed configure documentation.

Enable TVK ingress

Set spec.ingressConfig.ingressEnabled to true on the TrilioVaultManager resource:

spec:
  ingressConfig:
    ingressEnabled: true

This setting enables TVK ingress required by the Lightspeed integration. Configure it when you create or update the TVM.

Automatic Enablement

RAG injection 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.

You still need an OLSConfig with spec.ols.byokRAGOnly: true and a TVM with spec.ingressConfig.ingressEnabled: true. See BYOK RAG Only and Enable TVK ingress.

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:

oc get olsconfig -o yaml

Look for an entry with indexID: tvk_rag_index under spec.ols.rag[]. Confirm spec.ols.byokRAGOnly is true.

Inspect the TVM spec field:

oc explain triliovaultmanager.spec.openshiftLightspeed

Confirm the TVM enables ingress:

oc get triliovaultmanager -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.ingressConfig.ingressEnabled}{"\n"}{end}'

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:

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

Or apply the change imperatively:

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, set byokRAGOnly: true and add the following entry to spec.ols.rag[] on your OLSConfig resource:

apiVersion: ols.openshift.io/v1alpha1
kind: OLSConfig
metadata:
  name: cluster
spec:
  ols:
    byokRAGOnly: true
    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:

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 with spec.ols.byokRAGOnly: true.

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) with spec.ols.byokRAGOnly: true, then trigger a TVM reconcile or restart the TVK operator pod.

byokRAGOnly not set

If spec.ols.byokRAGOnly is missing or false, Lightspeed continues to use the default OpenShift documentation RAG alongside any BYOK sources. Set byokRAGOnly: true on the OLSConfig so Lightspeed relies on the RAG databases you provide, including the TVK RAG image.

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.

• TVK does not set spec.ols.byokRAGOnly on OLSConfig. Cluster admins must set this field when creating or updating the CR.

• 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)

• Custom CatalogSource in a restricted environment

• OpenShift Lightspeed documentation