Configuration

Everything is configured through the OpenStackLightspeed custom resource (lightspeed.openstack.org/v1beta1). This page documents every field in its spec.

Core fields

Field	Required	Description
defaultModel	Yes	Default model alias selected for inference. Must match one of models[].name.
models	Yes	List of configured models. Must contain at least one entry.
tlsCACertBundle	No	Name of a ConfigMap containing additional CA certificates to merge into the shared trust bundle used by application components, including model connections.

Models (models[])

Each item in models[] defines one selectable model alias and the provider/backend details used to serve it.

Field	Required	Description
models[].name	Yes	Kubernetes-style model alias (used by defaultModel and request-time model).
models[].llmEndpoint	Yes	URL of the LLM endpoint (e.g. https://api.openai.com/v1). Must start with http:// or https://.
models[].llmEndpointType	Yes	Provider type. See supported providers.
models[].llmCredentials	Yes	Secret name (same namespace) with the API token under key apitoken.
models[].modelName	Yes	Provider-native model name to use at the configured endpoint.
models[].maxTokensForResponse	No	Max response tokens for this model. Minimum 1. Defaults to 2048.
models[].llmProjectID	No	Required by some providers (e.g. WatsonX).
models[].llmDeploymentName	No	Required by some providers (e.g. Azure OpenAI).
models[].llmAPIVersion	No	Required by some providers (e.g. Azure OpenAI).

See Multi-model request routing for how model aliases map to request fields (provider and model) at query time.

Supported providers

• openai — OpenAI-compatible endpoints (Ollama, vLLM, etc.)

• azure_openai — Azure OpenAI (needs models[].llmDeploymentName, models[].llmAPIVersion)

• watsonx — IBM watsonx.ai (needs models[].llmProjectID)

• rhoai_vllm — vLLM via Red Hat OpenShift AI

• rhelai_vllm — vLLM via RHEL AI

• gemini — Google Gemini

Tip

This list grows over time. Check oc explain openstacklightspeed.spec.models.llmEndpointType on your cluster for the current, authoritative list.

Logging

Field	Default	Description
ogx.logLevel	all=info	OGX container. Standard level, or component=level pairs (e.g. core=debug,providers=info).
lcore.logLevel	INFO	lightspeed-service-api container. DEBUG/INFO/WARNING/ERROR/CRITICAL.
dataverseExporter.logLevel	INFO	Feedback/transcript exporter sidecar. Same values as above.
database.logLevel	INFO	PostgreSQL container. DEBUG also logs every SQL statement.

Data collection

spec:
  dataverseExporter:
    feedback:
      enabled: true       # default: true
    transcripts:
      enabled: false      # default: false

feedback.enabled records thumbs-up/down responses. transcripts.enabled records full conversations. Both are sent by the Dataverse exporter sidecar.

Persistent storage (database)

PostgreSQL always gets a PersistentVolumeClaim — this field only overrides its size/class, it doesn’t control whether one exists:

spec:
  database:
    size: "5Gi"                # default: 1Gi
    class: "my-storage-class"  # default: cluster's default StorageClass

Container resources

Every container has a default request/limit. Setting one replaces its default entirely:

spec:
  ogx:
    resources:
      requests: {cpu: "500m", memory: "2Gi"}
      limits: {cpu: "2", memory: "8Gi"}
  lcore:
    resources:
      requests: {cpu: "250m", memory: "512Mi"}
      limits: {cpu: "1", memory: "2Gi"}
  database:
    resources:
      requests: {cpu: "30m", memory: "300Mi"}
      limits: {cpu: "500m", memory: "2Gi"}
  okp:
    resources:
      requests: {cpu: "500m", memory: "2Gi"}
      limits: {cpu: "2", memory: "4Gi"}
  console:
    resources:
      requests: {cpu: "50m", memory: "64Mi"}
      limits: {cpu: "200m", memory: "256Mi"}

The optional RHOSO MCP sidecar has default resources of 50m CPU and 300Mi memory requested, with a 500Mi memory limit. Configure it at dev.rhosMCP.resources when the rhoso_mcps feature flag is enabled.

Container images

Each managed workload can use a custom image. Set containerImage under the relevant component: rag, ogx, lcore, database, dataverseExporter, okp, or console; for the optional MCP sidecar use dev.rhosMCP.containerImage. When omitted, the operator uses its configured default image. For example, to configure LCORE container image:

spec:
  lcore:
    containerImage: quay.io/<custom-org>/<custom-image-name>:<tag>

Offline knowledge portal

Important

OKP is deployed on every install — spec.okp configures it, it doesn’t gate whether it’s deployed. Pulling its image needs the same free registry.redhat.io account described in the installation guide.

spec:
  okp: {}   # no access key: browse individual pages, full-text search doesn't work

spec:
  okp:
    accessKey: okp-access-key-secret   # Secret key: "access_key"
    offline: true                      # default: resolve documentation URLs offline

• No accessKey (default) — you can navigate directly to and read individual documentation and product lifecycle pages. The full-text search index, Solutions, and Articles are encrypted and require a key, so keyword search across the corpus doesn’t work. What upstream users run on.

• With accessKey — unlocks that search index plus the encrypted knowledgebase. Needs an active Red Hat Satellite subscription (get one) — a bonus if you already have one, not something every user needs.

By default, RAG grounding is OKP-only — the bundled community documentation is disabled unless you set dev.okpRagOnly: false (below).

Quota enforcement

Configure one or more limiters to enable token quota enforcement. The operator uses its managed PostgreSQL instance for quota storage. Omitting quotas or leaving limiters empty disables enforcement.

spec:
  quotas:
    limiters:
      - name: per-user-hourly
        type: userLimiter
        initialQuota: 1000
        quotaIncrease: 1000
        period: "1 hour"
      - name: cluster-daily
        type: clusterLimiter
        initialQuota: 100000
        quotaIncrease: 100000
        period: "1 day"
    scheduler:
      period: 10
    enableTokenHistory: true

Each entry in limiters requires these fields:

Field	Description
name	A human-readable limiter name.
type	userLimiter for a per-user quota, or clusterLimiter for one quota shared by the cluster.
initialQuota	Number of tokens granted when the limiter resets. Must be zero or greater.
quotaIncrease	Number of tokens added by the scheduler at each quota interval. Must be zero or greater.
period	Interval that controls when the limiter resets or increases, such as "30 seconds", "1 hour", "1 day", or "1 hour 30 minutes".

scheduler is optional and configures the background process that checks limiters for reset or increase and reconnects to the database after a connection failure:

• period: check interval in seconds. Default: 5.

• databaseReconnectionCount: number of database reconnection attempts. Default: 10.

• databaseReconnectionDelay: delay in seconds between reconnection attempts. Default: 1.

Set enableTokenHistory: true to record per-user, model, and provider token usage for auditing. It does not affect enforcement and defaults to false.

Developer / experimental options (dev)

Warning

Not part of the stable API — may change without notice.

spec:
  dev:
    featureFlags:
      - rhoso_mcps   # enables the read-only MCP introspection sidecar
    okpChunkFilterQuery: "product:(*openstack* OR *openshift*)"  # example override
    okpRagOnly: false  # include bundled community docs too, not just OKP
    resourcePollInterval: 60  # requeue/poll interval in seconds (default: 60)
    rhosMCP:
      config: |
        debug: true
        workers: 4
      resources:
        requests:
          cpu: "50m"
          memory: "300Mi"
        limits:
          memory: "500Mi"
      containerImage: quay.io/openstack-lightspeed/lightspeed-mcps:latest

• okpChunkFilterQuery and okpRagOnly take effect immediately, with no featureFlags entry needed — they’re independent of rhoso_mcps. If unset, okpChunkFilterQuery auto-detects your OpenShift/RHOSO versions instead of using the literal example above.

• rhoso_mcps — the one flag that does need to be set. Deploys the MCP introspection sidecar, which is read-only by default. See Usage.

• rhosMCP configures the MCP sidecar. Its config value is deep-merged on top of the operator’s defaults and can override anything they set, including the allow_write flags that keep introspection read-only. Only set it if you understand exactly what you’re overriding. resources and containerImage respectively configure the sidecar resource requirements and image.

• resourcePollInterval — requeue/poll interval in seconds when a dynamically watched CRD is missing or when rhoso_mcps is enabled (the cache-based watch only covers the operator namespace, so polling detects cross-namespace changes such as OpenStackControlPlane readiness and CA rotations). Defaults to 60.