From cf19a605a68c8b2c4e7797456aaa22078832f0a8 Mon Sep 17 00:00:00 2001 From: Omkar Joshi <103182931+omkarjoshi0304@users.noreply.github.com> Date: Wed, 19 Aug 2026 17:26:33 +0100 Subject: [PATCH 1/3] Add GitHub Pages documentation site Upstream users trying OpenStack Lightspeed have had to piece together installation, configuration, and troubleshooting steps from the README, CRD comments, and tribal knowledge, with no single published reference and no indication that this is a community-supported, upstream-only release. This adds an AsciiDoc-based documentation site under docs/, following the same tooling already used by sibling repos (watcher-operator, openstack-operator): asciidoctor + kramdown-asciidoc convert the project README and docs/*.adoc into a single rendered page, built via `make docs` locally or by the new .github/workflows/docs.yaml on push to main, which publishes to the gh-pages branch. Content covers: - Installation, including the free Red Hat Developer account and registry.redhat.io pull secret required for images not yet mirrored to quay.io, and the two current install paths (deploy from source / manual CatalogSource) until the operator's community-operators-prod submission (PRs #10781, #10782) is merged and OperatorHub search works directly. - Full OpenStackLightspeedSpec configuration reference, including the supported LLM providers, container resource overrides, persistent storage, and OKP (deployed on every install, not opt-in; the no-access-key tier is what upstream users are expected to run on). - Troubleshooting keyed off the operator's actual condition types and reconcile error messages. - Usage and an explicit statement that support for this release is upstream-only, via GitHub Issues. Every factual claim was checked against the current controller code (api/v1beta1, internal/controller) rather than assumed from existing docs, and the site was built locally with asciidoctor to confirm it renders with no warnings and no broken cross-references. --- .github/workflows/docs.yaml | 52 ++++++++ .gitignore | 7 + Gemfile | 6 + Makefile | 31 +++++ docs/Makefile | 52 ++++++++ docs/assemblies/.gitkeep | 0 docs/configuration.adoc | 214 +++++++++++++++++++++++++++++ docs/images/.gitkeep | 0 docs/install_guide.adoc | 260 ++++++++++++++++++++++++++++++++++++ docs/main.adoc | 22 +++ docs/troubleshooting.adoc | 112 ++++++++++++++++ docs/usage.adoc | 64 +++++++++ 12 files changed, 820 insertions(+) create mode 100644 .github/workflows/docs.yaml create mode 100644 Gemfile create mode 100644 docs/Makefile create mode 100644 docs/assemblies/.gitkeep create mode 100644 docs/configuration.adoc create mode 100644 docs/images/.gitkeep create mode 100644 docs/install_guide.adoc create mode 100644 docs/main.adoc create mode 100644 docs/troubleshooting.adoc create mode 100644 docs/usage.adoc diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..de4f1f0 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,52 @@ +name: Build Docs +on: + workflow_dispatch: + push: + branches: + - main + pull_request: + branches: + - main + paths: + - .github/workflows/docs* + - docs/** + - README.md + - Gemfile +jobs: + deploy: + if: github.repository == 'openstack-k8s-operators/lightspeed-operator' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + # this fetches all branches. Needed because we need gh-pages branch for deploy to work + fetch-depth: 0 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.4.10' + + - name: Build docs + run: | + make docs + cp docs_build/lightspeed-operator/index.html index.html + cp -r docs_build/lightspeed-operator/images images + + - name: Prepare gh-pages branch + run: | + git config user.name github-actions + git config user.email github-actions@github.com + + git branch -D gh-pages &>/dev/null || true + git checkout --orphan gh-pages + git reset + + - name: Commit asciidoc docs + run: | + git add index.html + git add images + git commit -m "Rendered docs" + + - name: Push rendered docs to gh-pages + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + run: | + git push --force origin gh-pages diff --git a/.gitignore b/.gitignore index 6a58d60..394a7cc 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,10 @@ kuttl-report-openstack-lightspeed.xml # Vulnerability scan output vuln_output.json + +# Ruby bundle related files +/.bundle +/local +/Gemfile.lock +docs/readme.adoc +/docs_build diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..b355ae2 --- /dev/null +++ b/Gemfile @@ -0,0 +1,6 @@ +source 'https://rubygems.org' + +gem 'asciidoctor', '~> 2.0', '>= 2.0.20' + +# Uncomment for ability to convert Markdown to AsciiDoc +gem 'kramdown-asciidoc' diff --git a/Makefile b/Makefile index cf00dab..47979fd 100644 --- a/Makefile +++ b/Makefile @@ -430,3 +430,34 @@ catalog-build: opm ## Build a catalog image. .PHONY: catalog-push catalog-push: ## Push a catalog image. $(MAKE) docker-push IMG=$(CATALOG_IMG) + +##@ Documentation + +.PHONY: .bundle +.bundle: + if ! type bundle; then \ + echo "Bundler not found. On Linux run 'sudo dnf install /usr/bin/bundle' to install it."; \ + exit 1; \ + fi + + bundle config set --local path 'local/bundle'; bundle install + +.PHONY: docs-dependencies +docs-dependencies: .bundle ## Convert markdown docs to ascii docs + bundle exec kramdoc README.md -o docs/readme.adoc + +.PHONY: docs +docs: docs-dependencies ## Build docs + cd docs; $(MAKE) html + +.PHONY: docs-preview +docs-preview: docs ## Build docs and open them in a browser + cd docs; $(MAKE) open-html + +.PHONY: docs-watch +docs-watch: docs-preview ## Build docs, open them, and rebuild on file changes + cd docs; $(MAKE) watch-html + +.PHONY: docs-clean +docs-clean: ## Remove built docs + rm -rf docs_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..09cffc1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,52 @@ +BUILD = upstream +BUILD_DIR = ../docs_build +ROOTDIR = $(realpath .) +NAME = lightspeed-operator +DEST_DIR = $(BUILD_DIR)/$(NAME) +DEST_HTML = $(DEST_DIR)/index.html +IMAGES_DIR = $(DEST_DIR)/images +IMAGES_TS = $(DEST_DIR)/.timestamp-images +MAIN_SOURCE = main.adoc +OTHER_SOURCES = install_guide.adoc configuration.adoc troubleshooting.adoc usage.adoc $(shell find ./assemblies -type f) +IMAGES = $(shell find ./images -type f) +ALL_SOURCES = $(MAIN_SOURCE) $(OTHER_SOURCES) $(IMAGES) +UNAME = $(shell uname) +BUNDLE_EXEC ?= bundle exec + +ifeq ($(UNAME), Linux) +BROWSER_OPEN = xdg-open +endif +ifeq ($(UNAME), Darwin) +BROWSER_OPEN = open +endif + +all: html + +html: html-latest + +html-latest: prepare $(IMAGES_TS) $(DEST_HTML) + +prepare: + @mkdir -p $(BUILD_DIR) + @mkdir -p $(DEST_DIR) $(IMAGES_DIR) + +clean: + @rm -rf "$(DEST_DIR)" + +watch-html: + @which inotifywait > /dev/null || ( echo "ERROR: inotifywait not found, install inotify-tools" && exit 1 ) + while true; do \ + inotifywait -r -e modify -e create -e delete .; \ + sleep 0.5; \ + $(MAKE) html; \ + done + +open-html: html + ${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(DEST_HTML))" + +$(IMAGES_TS): $(IMAGES) + @if [ -n "$(IMAGES)" ]; then cp $(IMAGES) $(IMAGES_DIR); fi + touch $(IMAGES_TS) + +$(DEST_HTML): $(ALL_SOURCES) + $(BUNDLE_EXEC) asciidoctor -a source-highlighter=highlightjs -a highlightjs-languages="yaml,bash" -a highlightjs-theme="monokai" --failure-level WARN -a build=$(BUILD) -b xhtml5 -d book -o $@ $(MAIN_SOURCE) diff --git a/docs/assemblies/.gitkeep b/docs/assemblies/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/configuration.adoc b/docs/configuration.adoc new file mode 100644 index 0000000..9694473 --- /dev/null +++ b/docs/configuration.adoc @@ -0,0 +1,214 @@ += Configuration + +All configuration is expressed through the `OpenStackLightspeed` custom +resource (`lightspeed.openstack.org/v1beta1`). This page documents every field +in its `spec`. + +== Core fields + +[cols="1,1,3", options="header"] +|=== +|Field |Required |Description + +|`llmEndpoint` +|Yes +|URL of the LLM endpoint (e.g. `\https://api.openai.com/v1`). Must start with `http://` or `https://`. + +|`llmEndpointType` +|Yes +|Type of provider serving the LLM. See <>. + +|`modelName` +|Yes +|Name of the model to use at `llmEndpoint`. + +|`llmCredentials` +|Yes +|Name of a `Secret` in the same namespace containing the API token under the key `apitoken`. + +|`tlsCACertBundle` +|No +|Name of a `ConfigMap` in the same namespace containing a CA certificate bundle, for endpoints using a custom or self-signed certificate. + +|`maxTokensForResponse` +|No +|Maximum number of tokens to use for response generation. Minimum `1`. Defaults to `2048`. + +|`llmProjectID` +|No +|Project ID, required by some providers (e.g. WatsonX). + +|`llmDeploymentName` +|No +|Deployment name, required by some providers (e.g. Azure OpenAI). + +|`llmAPIVersion` +|No +|API version, required by some providers (e.g. Azure OpenAI). + +|`feedbackEnabled` +|No +|Enables user feedback collection on responses. Defaults to `true`. + +|`transcriptsEnabled` +|No +|Enables conversation transcript collection. Defaults to `false`. +|=== + +[#supported-providers] +== Supported LLM providers (`llmEndpointType`) + +* `openai` — OpenAI-compatible endpoints (including self-hosted, e.g. Ollama, vLLM). +* `azure_openai` — Microsoft Azure OpenAI. Requires `llmDeploymentName` and `llmAPIVersion`. +* `watsonx` — IBM watsonx.ai. Requires `llmProjectID`. +* `rhoai_vllm` — vLLM served through Red Hat OpenShift AI. +* `rhelai_vllm` — vLLM served through RHEL AI. +* `gemini` — Google Gemini. + +TIP: The list of supported providers is enforced by the CRD's validation +schema. Check the `llmEndpointType` field description on the CRD installed in +your cluster (`oc explain openstacklightspeed.spec.llmEndpointType`) for the +authoritative, up-to-date list, since new providers are added over time. + +== Logging (`logging`) + +[cols="1,1,3", options="header"] +|=== +|Field |Default |Description + +|`logging.ogxLogLevel` +|`all=info` +|Log level for the llama-stack/OGX container. Accepts a standard level or fine-grained `component=level` pairs (e.g. `core=debug,providers=info`). + +|`logging.lightspeedStackLogLevel` +|`INFO` +|Log level for the lightspeed-service-api container. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. + +|`logging.dataverseExporterLogLevel` +|`INFO` +|Log level for the transcript/feedback exporter sidecar. Same values as above. + +|`logging.postgresLogLevel` +|`INFO` +|Log level for the PostgreSQL container. `DEBUG` additionally logs every SQL statement. +|=== + +== Persistent storage (`database`) + +Omit this field to use an `emptyDir` volume for PostgreSQL (data is lost on +pod reschedule). Set it to provision a PersistentVolumeClaim instead: + +[source,yaml] +---- +spec: + database: + size: "5Gi" # defaults to 1Gi + class: "my-storage-class" # defaults to the cluster's default StorageClass +---- + +== Container resources (`resources`) + +Every container managed by the operator has a sensible default resource +request/limit. Override any of them; the value you provide replaces the +default entirely (it is not merged): + +[source,yaml] +---- +spec: + resources: + llamaStack: + requests: {cpu: "500m", memory: "2Gi"} + limits: {cpu: "2", memory: "8Gi"} + lightspeedService: + requests: {cpu: "250m", memory: "512Mi"} + limits: {cpu: "1", memory: "2Gi"} + postgres: + requests: {cpu: "30m", memory: "300Mi"} + limits: {cpu: "500m", memory: "2Gi"} + okp: + requests: {cpu: "500m", memory: "2Gi"} + limits: {cpu: "2", memory: "4Gi"} + consolePlugin: + requests: {cpu: "50m", memory: "64Mi"} + limits: {cpu: "200m", memory: "256Mi"} + mcp: + requests: {cpu: "50m", memory: "64Mi"} + limits: {memory: "200Mi"} +---- + +== Offline Knowledge Portal (`okp`) + +[IMPORTANT] +==== +Unlike the other fields on this page, OKP is **not** opt-in infrastructure. +The operator deploys an OKP pod on every `OpenStackLightspeed` instance +regardless of whether `spec.okp` is set. `spec.okp` only *configures* OKP +(access key, offline mode) — it does not control whether it gets deployed. +Pulling the OKP image requires the same free `registry.redhat.io` account +already covered in <>; see that section to set it up. +==== + +`accessKey` is optional and controls which tier of OKP content you get: + +[source,yaml] +---- +spec: + okp: {} # no access key: browsing works, search does not +---- + +[source,yaml] +---- +spec: + okp: + accessKey: okp-access-key-secret # Secret containing key "access_key" +---- + +* **Without `accessKey`** (the default) — documentation and product lifecycle + content can be browsed, but search, Solutions, and Articles are + unavailable. This is the tier upstream users are expected to run on. +* **With `accessKey`** — unlocks full search and the encrypted knowledgebase + content. Getting a key requires an active Red Hat Satellite subscription + (see + https://access.redhat.com/offline/access[access.redhat.com/offline/access]); + treat this as a bonus for organizations that already have one, not + something every upstream user needs. + +**RAG source, by default, is OKP-only.** The `dev.okpRagOnly` flag (see +below) defaults to `true` when unset, which disables the bundled +community-documentation vector database entries in favor of OKP alone. Set +`dev.okpRagOnly: false` explicitly if you want the bundled community +OpenStack/OpenShift documentation included as a RAG source instead of (or +alongside) OKP. + +== Developer / experimental options (`dev`) + +[WARNING] +==== +`dev` is **not** part of the stable API. Fields here may change or be removed +without notice between releases. +==== + +[source,yaml] +---- +spec: + dev: + featureFlags: + - rhoso_mcps # enables the read-only MCP introspection sidecar + okpChunkFilterQuery: "product:(*openstack* OR *openshift*)" # overrides the auto-detected default + okpRagOnly: false # false: include the bundled community docs too, not just OKP + rhosMCPConfig: | + debug: true + workers: 4 +---- + +If `okpChunkFilterQuery` is left unset, the operator auto-detects your +OpenShift and RHOSO versions and builds a version-aware filter query itself +rather than using the literal string shown above (which is just an example +override). + +`rhoso_mcps` is currently the primary feature flag: enabling it deploys an +MCP (Model Context Protocol) server sidecar that gives the assistant +strictly read-only introspection tools against your OpenStack and OpenShift +resources. See xref:_usage[Usage] for details on what it does and how +credentials are obtained. diff --git a/docs/images/.gitkeep b/docs/images/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/install_guide.adoc b/docs/install_guide.adoc new file mode 100644 index 0000000..d24b5f0 --- /dev/null +++ b/docs/install_guide.adoc @@ -0,0 +1,260 @@ += Installation Guide + +== Prerequisites + +* An OpenShift cluster (4.18+). +* Access to an LLM endpoint and an API key for it. OpenStack Lightspeed follows + a Bring Your Own Model (BYOM) approach: any provider from the supported list + in xref:supported-providers[Configuration] can be used. +* A free Red Hat Developer account, to pull certain component images (notably + the console plugin) from `registry.redhat.io`. See + <> below. +* Optionally, an existing `OpenStackControlPlane` if you want the assistant to + be aware of your OpenStack deployment. + +[#redhat-registry-access] +== Access to registry.redhat.io images + +Some of the images the operator deploys notably the console plugin and the +OKP (Offline Knowledge Portal) pod, both of which are deployed on every +install, not opt-in are published on `registry.redhat.io` rather than +`quay.io`. This is a deliberate +choice, not an oversight: the team evaluated mirroring these to `quay.io` and +decided against it, because the `quay.io` copies were not being kept up to +date. Until +https://github.com/openstack-k8s-operators/lightspeed-operator/pull/21[PR #21] +(which exposes image references on the `OpenStackLightspeed` CR) is merged, +there is no supported way to override these to point elsewhere so, for now, +plan on having `registry.redhat.io` access available. + +The good news: this only requires a **free** account, not a paid subscription. + +. Create a free Red Hat Developer account at + https://developers.redhat.com/[developers.redhat.com]. This gives you + access to developer tools and programs, including the images used here. +. Get a pull secret for CRC: log in to the + https://console.redhat.com/[Hybrid Cloud Console] with that account and + download your pull secret. This is the same `pull-secret.txt` referenced as + `PULL_SECRET` in the CRC setup below. +. Verify you have access before deploying, using Podman: ++ +[source,bash] +---- +$ podman login registry.redhat.io +Username: +Password: +Login Succeeded! + +$ podman pull registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12 +Trying to pull registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12... +Getting image source signatures +Copying blob ... done +Copying config ... done +Writing manifest to image destination +---- ++ +If you are not authenticated, the pull fails instead with: ++ +[source,console] +---- +Error: unable to copy from source docker://registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12: initializing source docker://...: unable to retrieve auth token: invalid username/password: unauthorized: Please login to the Red Hat Registry using your Customer Portal credentials. Further instructions can be found here: https://access.redhat.com/RegistryAuthentication +---- ++ +That error, or `ImagePullBackOff` on operator-managed pods, is a strong +signal you need to complete the steps above — see +xref:_console_widget_not_appearing[Troubleshooting] if it happens on the +console plugin specifically. + +TIP: This is tracked as a documentation TODO: once image references are +configurable on the CR (`PR #21`), this page will be updated to also show how +to point them at alternative registries if you prefer. + +== Installing the operator + +[IMPORTANT] +==== +OpenStack Lightspeed is not yet searchable from the in-console +*Operators -> OperatorHub* catalog. Publishing it there is tracked upstream by +https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/10781[community-operators-prod PR #10781] +(initial operator submission) and +https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/10782[PR #10782] +(OCP 4.18 catalog index update), both open as of this writing. Once merged, +the in-console search flow below will work directly. Until then, use one of +the two options first. +==== + +=== Option 1: Deploy from source (works today) + +[source,bash] +---- +git clone https://github.com/openstack-k8s-operators/lightspeed-operator.git +cd lightspeed-operator +make openstack-lightspeed-deploy +---- + +This creates a `CatalogSource` pointing at the published +`quay.io/openstack-lightspeed/operator-catalog:latest` image, plus the +`openstack-lightspeed` namespace, an `OperatorGroup`, and a `Subscription` — +then waits for the operator to come up. No OperatorHub listing required. + +=== Option 2: Add the catalog source manually + +If you don't want to clone the repository, apply the `CatalogSource` yourself: + +[source,yaml] +---- +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: openstack-lightspeed-catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: quay.io/openstack-lightspeed/operator-catalog:latest + displayName: OpenStack Lightspeed Operator + publisher: Red Hat +---- + +Once it appears (`oc get catalogsource -n openshift-marketplace`), it shows up +under *Operators -> OperatorHub* in the console as a regular catalog entry — +find it there, or create a `Subscription` to it directly. + +=== Once published to OperatorHub + +After the PRs above merge, the flow becomes the standard one: + +. Open the OpenShift web console and navigate to *Operators -> OperatorHub*. +. Search for *"OpenStack Lightspeed (Community)"*. +. Click *Install* and select the desired namespace (the default is + `openstack-lightspeed`). +. Track progress under *Operators -> Installed Operators*, or from the CLI: ++ +[source,bash] +---- +$ oc get -n openstack-lightspeed pods +NAME READY STATUS RESTARTS AGE +openstack-lightspeed-operator-controller-manager-76df7fbfb5wggr 1/1 Running 0 72s +---- + +== Don't have a cluster yet? (CRC) + +For local development or testing, deploy an OpenShift CRC cluster using +`install_yamls` before running Option 1 or 2 above: + +[source,bash] +---- +git clone https://github.com/openstack-k8s-operators/install_yamls.git +cd install_yamls/devsetup +make download_tools + +CRC_VERSION=2.51.0 PULL_SECRET=~/work/pull-secret CRC_MONITORING_ENABLED=true CPUS=12 MEMORY=25600 DISK=100 make crc +make crc_attach_default_interface +eval $(crc oc-env) +cd ../.. +---- + +`PULL_SECRET` here is the same pull secret from +<> above. + +== Setting up LLM credentials + +To reach your LLM you need an API key, an endpoint URL, and a model name. + +`tlsCACertBundle` is **not** something most upstream users need to set. It +only matters if your LLM endpoint's TLS certificate isn't already trusted by +a public certificate authority — for example, a self-hosted vLLM/Ollama +endpoint using a self-signed or internal-CA certificate. Public providers +like Gemini, OpenAI, and Anthropic use publicly-trusted certificates, so +there's nothing to configure for them here; skip straight to applying the CR +below. + +Create the API key secret (referenced later as `llmCredentials`). The secret +*must* contain a key named `apitoken`: + +[source,bash] +---- +oc apply -f - < +EOF +---- + +If your LLM endpoint uses a custom or self-signed certificate, create a +ConfigMap with the CA bundle (referenced later as `tlsCACertBundle`). Every +key in the ConfigMap's `data` is parsed as PEM certificate data — the key +name itself doesn't matter (`cert` below is just a convention, not a +requirement), and you can include multiple keys/certificates: + +[source,bash] +---- +oc apply -f - <:/v1 + llmEndpointType: openai + llmCredentials: openstack-lightspeed-apitoken + modelName: + tlsCACertBundle: openstack-lightspeed-certs # optional +---- + +The operator reconciles this resource into the full stack: the AI engine +(lightspeed-stack and llama-stack/OGX), PostgreSQL, and the OpenShift console +plugin. + +== Verifying the deployment + +Check the `Ready` condition on the `OpenStackLightspeed` resource, and inspect +the deployments it created: + +[source,bash] +---- +oc describe -n openstack-lightspeed openstacklightspeed +oc get -n openstack-lightspeed deployments,pods +---- + +See xref:_troubleshooting[Troubleshooting] if the resource does not reach +`Ready`. + +== Accessing the assistant + +Once ready, open the +https://console-openshift-console.apps-crc.testing[OpenShift web console] and +use the Lightspeed widget in the lower-right corner. You may need to click the +*refresh* link that appears in a console notification the first time the +plugin is activated. + +If you are running CRC on a remote machine, you can reach the console with +`sshuttle`: + +* Add this line to your local `/etc/hosts` (don't change the IP): + `192.168.130.11 api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing` +* Run `sshuttle -r $remote_username@$remote_server 192.168.130.0/24`. diff --git a/docs/main.adoc b/docs/main.adoc new file mode 100644 index 0000000..c2ce33c --- /dev/null +++ b/docs/main.adoc @@ -0,0 +1,22 @@ += OpenStack Lightspeed Operator documentation +:toc: left +:toclevels: 3 +:icons: font +:compat-mode: +:doctype: book +:context: osp +:imagesdir: images + +[IMPORTANT] +==== +This is a community release. Support is provided **upstream only**, through +https://github.com/openstack-k8s-operators/lightspeed-operator/issues[GitHub Issues] +on this repository. There is no separate commercial support channel for this +project. +==== + +include::readme.adoc[leveloffset=+1] +include::install_guide.adoc[leveloffset=+1] +include::configuration.adoc[leveloffset=+1] +include::troubleshooting.adoc[leveloffset=+1] +include::usage.adoc[leveloffset=+1] diff --git a/docs/troubleshooting.adoc b/docs/troubleshooting.adoc new file mode 100644 index 0000000..0cf0a29 --- /dev/null +++ b/docs/troubleshooting.adoc @@ -0,0 +1,112 @@ += Troubleshooting + +== Start with the resource's conditions + +The `OpenStackLightspeed` resource reports its state through +`status.conditions`. Always start here: + +[source,bash] +---- +oc describe -n openstacklightspeed +---- + +The `Message` and `Status` columns (also visible via `oc get openstacklightspeed`) +summarize the current reconciliation state. Key condition types to look for: + +[cols="1,3", options="header"] +|=== +|Condition |Meaning + +|`OpenStackLightspeedReady` +|Overall readiness. `False`/`Unknown` means some part of the stack (engine, database, or console plugin) has not converged yet. + +|`OpenStackLightspeedMCPServerReady` +|Only relevant when the `rhoso_mcps` dev feature flag is enabled. Tracks the MCP introspection sidecar deployment. +|=== + +== Deployment-specific issues + +=== lightspeed-stack (engine) pod not becoming healthy + +The `lightspeed-stack-deployment` pod runs two containers: +lightspeed-service-api and llama-stack (OGX). Check both: + +[source,bash] +---- +oc logs -n deploy/lightspeed-stack-deployment -c lightspeed-service-api +oc logs -n deploy/lightspeed-stack-deployment -c llama-stack +---- + +A common cause of failure here is a bad or unreachable `llmEndpoint`, an +invalid `apitoken` in the `llmCredentials` secret, or a missing +`tlsCACertBundle` when the endpoint uses a self-signed certificate. The +llama-stack container will typically log an authentication or TLS error from +the provider in this case. + +=== PostgreSQL pod not starting + +[source,bash] +---- +oc logs -n deploy/lightspeed-postgres-server +---- + +If you changed `spec.database.size` to a *smaller* value than the existing +PVC, the operator rejects the change (shrinking a PVC in place isn't +supported) and reports it in the operator logs. Revert to the original size, +or delete and recreate the PVC if you intend to shrink it (this loses data). + +=== Console widget not appearing + +* Confirm the `ConsolePlugin` named `lightspeed-console-plugin` exists + (`oc get consoleplugin`) and is listed under `spec.plugins` on the cluster + `Console` resource (`oc get console.operator.openshift.io cluster -o yaml`). +* The console needs a moment to load newly-activated plugins. Click the + *refresh* link in the notification banner shown in the OpenShift console. +* Check the `lightspeed-console-plugin` deployment and pod logs for TLS + errors — the plugin serves over HTTPS using a service-ca-issued certificate + that can take a few seconds to appear after first deploy. +* If the pod is stuck in `ImagePullBackOff`/`ErrImagePull`, this is usually + missing `registry.redhat.io` access rather than a bug: the console plugin + image is hosted there, not on `quay.io`. See + xref:redhat-registry-access[Access to registry.redhat.io images] in the + Installation Guide to set up a free Red Hat Developer account and pull + secret, then verify with `podman login registry.redhat.io`. + +=== ImagePullBackOff on any operator-managed pod + +Some images (notably the console plugin) are pulled from `registry.redhat.io` +rather than `quay.io`. `oc describe pod` will show an error like: + +[source,console] +---- +Failed to pull image "registry.redhat.io/...": unauthorized: Please login to the Red Hat Registry using your Customer Portal credentials. +---- + +This means the node/cluster pull secret doesn't have `registry.redhat.io` +credentials. See +xref:redhat-registry-access[Access to registry.redhat.io images] for how to +get a free account and pull secret, and how to verify access with Podman +before troubleshooting further. + +=== CA bundle errors + +If `tlsCACertBundle` is set but reconciliation reports a CA parsing error, +verify every key in the ConfigMap's `data` contains valid PEM-encoded +certificate data (all keys are parsed, not just a specific one named `cert`), +and that none of them include extra leading/trailing whitespace introduced by +copy-pasting. + +== Getting operator logs + +[source,bash] +---- +oc logs -n deploy/openstack-lightspeed-operator-controller-manager +---- + +== Still stuck? + +This is a community release: support is provided upstream through GitHub +Issues. Please open an issue at +https://github.com/openstack-k8s-operators/lightspeed-operator/issues, +including the output of `oc describe openstacklightspeed`, relevant pod logs, +and your (redacted) `OpenStackLightspeed` resource spec. diff --git a/docs/usage.adoc b/docs/usage.adoc new file mode 100644 index 0000000..86bbe73 --- /dev/null +++ b/docs/usage.adoc @@ -0,0 +1,64 @@ += Usage + +== Asking questions + +Once the `OpenStackLightspeed` resource is `Ready`, open the OpenShift web +console and use the Lightspeed widget (bottom-right corner). Ask questions in +natural language, for example: + +* "How can I spin up a VM using the OpenStack CLI?" +* "Why would a Nova compute service show as down?" + +Responses are grounded via retrieval-augmented generation (RAG), and include +references you can verify. By default, grounding comes from +xref:_offline_knowledge_portal_okp[OKP] (deployed automatically with every +install, browsable without any extra credentials — see Configuration for the +free vs. keyed tiers). The bundled community OpenStack/OpenShift +documentation is also available as a RAG source, but only if you explicitly +set `dev.okpRagOnly: false`. + +== Cluster introspection (optional) + +When the `rhoso_mcps` dev feature flag is enabled (see +xref:_configuration[Configuration]), the assistant gains read-only tools +to inspect your actual OpenStack and OpenShift resources rather than relying +on documentation alone — for example, checking the status of a specific +service or resource in your deployment. + +* All introspection is **strictly read-only**: the assistant cannot modify + your cluster or your OpenStack deployment through these tools. +* Introspection happens locally, inside your cluster. Only the assistant's + query and retrieved context are sent to your configured LLM provider. +* The operator automatically provisions a scoped Keystone Application + Credential for this purpose when an `OpenStackControlPlane` is detected — + no manual credential setup is required. + +This capability is still evolving and ships disabled by default. + +== Feedback and transcripts + +Two independent, administrator-controlled settings affect data collection: + +* `feedbackEnabled` (default `true`) lets users thumbs-up/down individual + responses. +* `transcriptsEnabled` (default `false`) additionally collects full + conversation transcripts. + +Both are configured on the `OpenStackLightspeed` resource — see +xref:_configuration[Configuration]. Collected data is used to improve +answer quality in future releases; disable either setting if that doesn't fit +your environment's data handling policy. + +== Support + +OpenStack Lightspeed is a **community release**. Support is provided +**upstream only**, through GitHub Issues — there is no separate Red Hat +support entitlement for this project at this stage: + +* Operator issues: https://github.com/openstack-k8s-operators/lightspeed-operator/issues +* RAG content issues: https://github.com/openstack-k8s-operators/lightspeed-rag-content/issues +* MCP tooling issues: https://github.com/openstack-k8s-operators/lightspeed-mcps/issues + +When filing an issue, include the output of `oc describe openstacklightspeed`, +relevant pod logs, and your (redacted) `OpenStackLightspeed` spec — see +xref:_troubleshooting[Troubleshooting] for details. From a385d6c2cd91d63dffbc736462cbf1f5a59aa500 Mon Sep 17 00:00:00 2001 From: Omkar Joshi <103182931+omkarjoshi0304@users.noreply.github.com> Date: Thu, 20 Aug 2026 16:46:15 +0100 Subject: [PATCH 2/3] Migrate documentation to Sphinx / Read the Docs Switch the docs toolchain from AsciiDoctor/GitHub Pages to Sphinx/reStructuredText/Read the Docs, per team decision after PR review. Adds .readthedocs.yaml, docs/conf.py, and requirements.txt; drops the Gemfile, docs/Makefile, and the GitHub Pages workflow, since Read the Docs builds via its own webhook. Also carries over content fixes from review: stop including the full README (fixes duplicate headings and broken bullet rendering), dedupe the CRC instructions, add the missing pull-secret step for non-CRC clusters, merge "Still stuck?" into Support, add an Overview page with an architecture diagram, and rewrite the landing page so it's understandable with zero prior OpenStack knowledge. Verified with `sphinx-build -W`: zero warnings, all cross-references resolve. --- .github/workflows/docs.yaml | 52 ------- .gitignore | 10 +- .readthedocs.yaml | 16 +++ Gemfile | 6 - Makefile | 32 ++--- docs/Makefile | 52 ------- docs/assemblies/.gitkeep | 0 docs/conf.py | 12 ++ docs/configuration.adoc | 214 ---------------------------- docs/configuration.rst | 193 ++++++++++++++++++++++++++ docs/images/architecture.svg | 1 + docs/index.rst | 33 +++++ docs/install_guide.adoc | 260 ----------------------------------- docs/install_guide.rst | 216 +++++++++++++++++++++++++++++ docs/main.adoc | 22 --- docs/overview.rst | 19 +++ docs/quickstart.rst | 64 +++++++++ docs/requirements.txt | 2 + docs/troubleshooting.adoc | 112 --------------- docs/troubleshooting.rst | 94 +++++++++++++ docs/usage.adoc | 64 --------- docs/usage.rst | 58 ++++++++ 22 files changed, 726 insertions(+), 806 deletions(-) delete mode 100644 .github/workflows/docs.yaml create mode 100644 .readthedocs.yaml delete mode 100644 Gemfile delete mode 100644 docs/Makefile delete mode 100644 docs/assemblies/.gitkeep create mode 100644 docs/conf.py delete mode 100644 docs/configuration.adoc create mode 100644 docs/configuration.rst create mode 100644 docs/images/architecture.svg create mode 100644 docs/index.rst delete mode 100644 docs/install_guide.adoc create mode 100644 docs/install_guide.rst delete mode 100644 docs/main.adoc create mode 100644 docs/overview.rst create mode 100644 docs/quickstart.rst create mode 100644 docs/requirements.txt delete mode 100644 docs/troubleshooting.adoc create mode 100644 docs/troubleshooting.rst delete mode 100644 docs/usage.adoc create mode 100644 docs/usage.rst diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml deleted file mode 100644 index de4f1f0..0000000 --- a/.github/workflows/docs.yaml +++ /dev/null @@ -1,52 +0,0 @@ -name: Build Docs -on: - workflow_dispatch: - push: - branches: - - main - pull_request: - branches: - - main - paths: - - .github/workflows/docs* - - docs/** - - README.md - - Gemfile -jobs: - deploy: - if: github.repository == 'openstack-k8s-operators/lightspeed-operator' - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - with: - # this fetches all branches. Needed because we need gh-pages branch for deploy to work - fetch-depth: 0 - - uses: ruby/setup-ruby@v1 - with: - ruby-version: '3.4.10' - - - name: Build docs - run: | - make docs - cp docs_build/lightspeed-operator/index.html index.html - cp -r docs_build/lightspeed-operator/images images - - - name: Prepare gh-pages branch - run: | - git config user.name github-actions - git config user.email github-actions@github.com - - git branch -D gh-pages &>/dev/null || true - git checkout --orphan gh-pages - git reset - - - name: Commit asciidoc docs - run: | - git add index.html - git add images - git commit -m "Rendered docs" - - - name: Push rendered docs to gh-pages - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - run: | - git push --force origin gh-pages diff --git a/.gitignore b/.gitignore index 394a7cc..c7607e1 100644 --- a/.gitignore +++ b/.gitignore @@ -35,9 +35,7 @@ kuttl-report-openstack-lightspeed.xml # Vulnerability scan output vuln_output.json -# Ruby bundle related files -/.bundle -/local -/Gemfile.lock -docs/readme.adoc -/docs_build +# Sphinx docs build artifacts +/docs/_build +/docs/.venv +__pycache__/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..897fc7c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + fail_on_warning: true + +python: + install: + - requirements: docs/requirements.txt diff --git a/Gemfile b/Gemfile deleted file mode 100644 index b355ae2..0000000 --- a/Gemfile +++ /dev/null @@ -1,6 +0,0 @@ -source 'https://rubygems.org' - -gem 'asciidoctor', '~> 2.0', '>= 2.0.20' - -# Uncomment for ability to convert Markdown to AsciiDoc -gem 'kramdown-asciidoc' diff --git a/Makefile b/Makefile index 47979fd..526f960 100644 --- a/Makefile +++ b/Makefile @@ -433,31 +433,27 @@ catalog-push: ## Push a catalog image. ##@ Documentation -.PHONY: .bundle -.bundle: - if ! type bundle; then \ - echo "Bundler not found. On Linux run 'sudo dnf install /usr/bin/bundle' to install it."; \ +DOCS_VENV = docs/.venv +DOCS_PYTHON = $(DOCS_VENV)/bin/python + +.PHONY: .docs-venv +.docs-venv: + if ! command -v python3 > /dev/null; then \ + echo "python3 not found. Install Python 3 to build the docs."; \ exit 1; \ fi - - bundle config set --local path 'local/bundle'; bundle install - -.PHONY: docs-dependencies -docs-dependencies: .bundle ## Convert markdown docs to ascii docs - bundle exec kramdoc README.md -o docs/readme.adoc + test -d $(DOCS_VENV) || python3 -m venv $(DOCS_VENV) + $(DOCS_PYTHON) -m pip install --quiet --upgrade pip + $(DOCS_PYTHON) -m pip install --quiet -r docs/requirements.txt .PHONY: docs -docs: docs-dependencies ## Build docs - cd docs; $(MAKE) html +docs: .docs-venv ## Build docs (Sphinx, matching the Read the Docs build) + $(DOCS_VENV)/bin/sphinx-build -W -b html docs docs/_build/html .PHONY: docs-preview docs-preview: docs ## Build docs and open them in a browser - cd docs; $(MAKE) open-html - -.PHONY: docs-watch -docs-watch: docs-preview ## Build docs, open them, and rebuild on file changes - cd docs; $(MAKE) watch-html + open docs/_build/html/index.html || xdg-open docs/_build/html/index.html .PHONY: docs-clean docs-clean: ## Remove built docs - rm -rf docs_build + rm -rf docs/_build diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 09cffc1..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,52 +0,0 @@ -BUILD = upstream -BUILD_DIR = ../docs_build -ROOTDIR = $(realpath .) -NAME = lightspeed-operator -DEST_DIR = $(BUILD_DIR)/$(NAME) -DEST_HTML = $(DEST_DIR)/index.html -IMAGES_DIR = $(DEST_DIR)/images -IMAGES_TS = $(DEST_DIR)/.timestamp-images -MAIN_SOURCE = main.adoc -OTHER_SOURCES = install_guide.adoc configuration.adoc troubleshooting.adoc usage.adoc $(shell find ./assemblies -type f) -IMAGES = $(shell find ./images -type f) -ALL_SOURCES = $(MAIN_SOURCE) $(OTHER_SOURCES) $(IMAGES) -UNAME = $(shell uname) -BUNDLE_EXEC ?= bundle exec - -ifeq ($(UNAME), Linux) -BROWSER_OPEN = xdg-open -endif -ifeq ($(UNAME), Darwin) -BROWSER_OPEN = open -endif - -all: html - -html: html-latest - -html-latest: prepare $(IMAGES_TS) $(DEST_HTML) - -prepare: - @mkdir -p $(BUILD_DIR) - @mkdir -p $(DEST_DIR) $(IMAGES_DIR) - -clean: - @rm -rf "$(DEST_DIR)" - -watch-html: - @which inotifywait > /dev/null || ( echo "ERROR: inotifywait not found, install inotify-tools" && exit 1 ) - while true; do \ - inotifywait -r -e modify -e create -e delete .; \ - sleep 0.5; \ - $(MAKE) html; \ - done - -open-html: html - ${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(DEST_HTML))" - -$(IMAGES_TS): $(IMAGES) - @if [ -n "$(IMAGES)" ]; then cp $(IMAGES) $(IMAGES_DIR); fi - touch $(IMAGES_TS) - -$(DEST_HTML): $(ALL_SOURCES) - $(BUNDLE_EXEC) asciidoctor -a source-highlighter=highlightjs -a highlightjs-languages="yaml,bash" -a highlightjs-theme="monokai" --failure-level WARN -a build=$(BUILD) -b xhtml5 -d book -o $@ $(MAIN_SOURCE) diff --git a/docs/assemblies/.gitkeep b/docs/assemblies/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..5cec25f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,12 @@ +# Configuration file for the Sphinx documentation builder. +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +project = "OpenStack Lightspeed Operator" +copyright = "OpenStack Lightspeed contributors" +author = "OpenStack Lightspeed contributors" + +extensions = [] + +exclude_patterns = ["_build", ".venv", "Thumbs.db", ".DS_Store"] + +html_theme = "sphinx_rtd_theme" diff --git a/docs/configuration.adoc b/docs/configuration.adoc deleted file mode 100644 index 9694473..0000000 --- a/docs/configuration.adoc +++ /dev/null @@ -1,214 +0,0 @@ -= Configuration - -All configuration is expressed through the `OpenStackLightspeed` custom -resource (`lightspeed.openstack.org/v1beta1`). This page documents every field -in its `spec`. - -== Core fields - -[cols="1,1,3", options="header"] -|=== -|Field |Required |Description - -|`llmEndpoint` -|Yes -|URL of the LLM endpoint (e.g. `\https://api.openai.com/v1`). Must start with `http://` or `https://`. - -|`llmEndpointType` -|Yes -|Type of provider serving the LLM. See <>. - -|`modelName` -|Yes -|Name of the model to use at `llmEndpoint`. - -|`llmCredentials` -|Yes -|Name of a `Secret` in the same namespace containing the API token under the key `apitoken`. - -|`tlsCACertBundle` -|No -|Name of a `ConfigMap` in the same namespace containing a CA certificate bundle, for endpoints using a custom or self-signed certificate. - -|`maxTokensForResponse` -|No -|Maximum number of tokens to use for response generation. Minimum `1`. Defaults to `2048`. - -|`llmProjectID` -|No -|Project ID, required by some providers (e.g. WatsonX). - -|`llmDeploymentName` -|No -|Deployment name, required by some providers (e.g. Azure OpenAI). - -|`llmAPIVersion` -|No -|API version, required by some providers (e.g. Azure OpenAI). - -|`feedbackEnabled` -|No -|Enables user feedback collection on responses. Defaults to `true`. - -|`transcriptsEnabled` -|No -|Enables conversation transcript collection. Defaults to `false`. -|=== - -[#supported-providers] -== Supported LLM providers (`llmEndpointType`) - -* `openai` — OpenAI-compatible endpoints (including self-hosted, e.g. Ollama, vLLM). -* `azure_openai` — Microsoft Azure OpenAI. Requires `llmDeploymentName` and `llmAPIVersion`. -* `watsonx` — IBM watsonx.ai. Requires `llmProjectID`. -* `rhoai_vllm` — vLLM served through Red Hat OpenShift AI. -* `rhelai_vllm` — vLLM served through RHEL AI. -* `gemini` — Google Gemini. - -TIP: The list of supported providers is enforced by the CRD's validation -schema. Check the `llmEndpointType` field description on the CRD installed in -your cluster (`oc explain openstacklightspeed.spec.llmEndpointType`) for the -authoritative, up-to-date list, since new providers are added over time. - -== Logging (`logging`) - -[cols="1,1,3", options="header"] -|=== -|Field |Default |Description - -|`logging.ogxLogLevel` -|`all=info` -|Log level for the llama-stack/OGX container. Accepts a standard level or fine-grained `component=level` pairs (e.g. `core=debug,providers=info`). - -|`logging.lightspeedStackLogLevel` -|`INFO` -|Log level for the lightspeed-service-api container. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. - -|`logging.dataverseExporterLogLevel` -|`INFO` -|Log level for the transcript/feedback exporter sidecar. Same values as above. - -|`logging.postgresLogLevel` -|`INFO` -|Log level for the PostgreSQL container. `DEBUG` additionally logs every SQL statement. -|=== - -== Persistent storage (`database`) - -Omit this field to use an `emptyDir` volume for PostgreSQL (data is lost on -pod reschedule). Set it to provision a PersistentVolumeClaim instead: - -[source,yaml] ----- -spec: - database: - size: "5Gi" # defaults to 1Gi - class: "my-storage-class" # defaults to the cluster's default StorageClass ----- - -== Container resources (`resources`) - -Every container managed by the operator has a sensible default resource -request/limit. Override any of them; the value you provide replaces the -default entirely (it is not merged): - -[source,yaml] ----- -spec: - resources: - llamaStack: - requests: {cpu: "500m", memory: "2Gi"} - limits: {cpu: "2", memory: "8Gi"} - lightspeedService: - requests: {cpu: "250m", memory: "512Mi"} - limits: {cpu: "1", memory: "2Gi"} - postgres: - requests: {cpu: "30m", memory: "300Mi"} - limits: {cpu: "500m", memory: "2Gi"} - okp: - requests: {cpu: "500m", memory: "2Gi"} - limits: {cpu: "2", memory: "4Gi"} - consolePlugin: - requests: {cpu: "50m", memory: "64Mi"} - limits: {cpu: "200m", memory: "256Mi"} - mcp: - requests: {cpu: "50m", memory: "64Mi"} - limits: {memory: "200Mi"} ----- - -== Offline Knowledge Portal (`okp`) - -[IMPORTANT] -==== -Unlike the other fields on this page, OKP is **not** opt-in infrastructure. -The operator deploys an OKP pod on every `OpenStackLightspeed` instance -regardless of whether `spec.okp` is set. `spec.okp` only *configures* OKP -(access key, offline mode) — it does not control whether it gets deployed. -Pulling the OKP image requires the same free `registry.redhat.io` account -already covered in <>; see that section to set it up. -==== - -`accessKey` is optional and controls which tier of OKP content you get: - -[source,yaml] ----- -spec: - okp: {} # no access key: browsing works, search does not ----- - -[source,yaml] ----- -spec: - okp: - accessKey: okp-access-key-secret # Secret containing key "access_key" ----- - -* **Without `accessKey`** (the default) — documentation and product lifecycle - content can be browsed, but search, Solutions, and Articles are - unavailable. This is the tier upstream users are expected to run on. -* **With `accessKey`** — unlocks full search and the encrypted knowledgebase - content. Getting a key requires an active Red Hat Satellite subscription - (see - https://access.redhat.com/offline/access[access.redhat.com/offline/access]); - treat this as a bonus for organizations that already have one, not - something every upstream user needs. - -**RAG source, by default, is OKP-only.** The `dev.okpRagOnly` flag (see -below) defaults to `true` when unset, which disables the bundled -community-documentation vector database entries in favor of OKP alone. Set -`dev.okpRagOnly: false` explicitly if you want the bundled community -OpenStack/OpenShift documentation included as a RAG source instead of (or -alongside) OKP. - -== Developer / experimental options (`dev`) - -[WARNING] -==== -`dev` is **not** part of the stable API. Fields here may change or be removed -without notice between releases. -==== - -[source,yaml] ----- -spec: - dev: - featureFlags: - - rhoso_mcps # enables the read-only MCP introspection sidecar - okpChunkFilterQuery: "product:(*openstack* OR *openshift*)" # overrides the auto-detected default - okpRagOnly: false # false: include the bundled community docs too, not just OKP - rhosMCPConfig: | - debug: true - workers: 4 ----- - -If `okpChunkFilterQuery` is left unset, the operator auto-detects your -OpenShift and RHOSO versions and builds a version-aware filter query itself -rather than using the literal string shown above (which is just an example -override). - -`rhoso_mcps` is currently the primary feature flag: enabling it deploys an -MCP (Model Context Protocol) server sidecar that gives the assistant -strictly read-only introspection tools against your OpenStack and OpenShift -resources. See xref:_usage[Usage] for details on what it does and how -credentials are obtained. diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..a314d83 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,193 @@ +Configuration +============= + +Everything is configured through the ``OpenStackLightspeed`` custom +resource (``lightspeed.openstack.org/v1beta1``). This page documents every +field in its ``spec``. + +Core fields +----------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 70 + + * - Field + - Required + - Description + * - ``llmEndpoint`` + - Yes + - URL of the LLM endpoint (e.g. ``https://api.openai.com/v1``). Must + start with ``http://`` or ``https://``. + * - ``llmEndpointType`` + - Yes + - Provider type. See :ref:`supported-providers`. + * - ``modelName`` + - Yes + - Model name to use at ``llmEndpoint``. + * - ``llmCredentials`` + - Yes + - ``Secret`` name (same namespace) with the API token under key + ``apitoken``. + * - ``tlsCACertBundle`` + - No + - ``ConfigMap`` name (same namespace) with a CA bundle, for + self-signed endpoints. + * - ``maxTokensForResponse`` + - No + - Max response tokens. Minimum ``1``. Defaults to ``2048``. + * - ``llmProjectID`` + - No + - Required by some providers (e.g. WatsonX). + * - ``llmDeploymentName`` + - No + - Required by some providers (e.g. Azure OpenAI). + * - ``llmAPIVersion`` + - No + - Required by some providers (e.g. Azure OpenAI). + * - ``feedbackEnabled`` + - No + - User feedback collection. Defaults to ``true``. + * - ``transcriptsEnabled`` + - No + - Conversation transcript collection. Defaults to ``false``. + +.. _supported-providers: + +Supported LLM providers (``llmEndpointType``) +------------------------------------------------ + +* ``openai`` — OpenAI-compatible endpoints (Ollama, vLLM, etc.) +* ``azure_openai`` — Azure OpenAI (needs ``llmDeploymentName``, ``llmAPIVersion``) +* ``watsonx`` — IBM watsonx.ai (needs ``llmProjectID``) +* ``rhoai_vllm`` — vLLM via Red Hat OpenShift AI +* ``rhelai_vllm`` — vLLM via RHEL AI +* ``gemini`` — Google Gemini + +.. tip:: + + This list is enforced by the CRD schema and grows over time. Check + ``oc explain openstacklightspeed.spec.llmEndpointType`` on your cluster + for the current, authoritative list. + +Logging (``logging``) +----------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 15 60 + + * - Field + - Default + - Description + * - ``logging.ogxLogLevel`` + - ``all=info`` + - llama-stack/OGX container. Standard level, or + ``component=level`` pairs (e.g. ``core=debug,providers=info``). + * - ``logging.lightspeedStackLogLevel`` + - ``INFO`` + - lightspeed-service-api container. ``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``. + * - ``logging.dataverseExporterLogLevel`` + - ``INFO`` + - Feedback/transcript exporter sidecar. Same values as above. + * - ``logging.postgresLogLevel`` + - ``INFO`` + - PostgreSQL container. ``DEBUG`` also logs every SQL statement. + +Persistent storage (``database``) +------------------------------------ + +Omit for an ``emptyDir`` volume (data lost on pod reschedule), or set to +provision a PVC: + +.. code-block:: yaml + + spec: + database: + size: "5Gi" # default: 1Gi + class: "my-storage-class" # default: cluster's default StorageClass + +Container resources (``resources``) +-------------------------------------- + +Every container has a default request/limit. Setting one replaces its +default entirely: + +.. code-block:: yaml + + spec: + resources: + llamaStack: + requests: {cpu: "500m", memory: "2Gi"} + limits: {cpu: "2", memory: "8Gi"} + lightspeedService: + requests: {cpu: "250m", memory: "512Mi"} + limits: {cpu: "1", memory: "2Gi"} + postgres: + requests: {cpu: "30m", memory: "300Mi"} + limits: {cpu: "500m", memory: "2Gi"} + okp: + requests: {cpu: "500m", memory: "2Gi"} + limits: {cpu: "2", memory: "4Gi"} + consolePlugin: + requests: {cpu: "50m", memory: "64Mi"} + limits: {cpu: "200m", memory: "256Mi"} + mcp: + requests: {cpu: "50m", memory: "64Mi"} + limits: {memory: "200Mi"} + +.. _offline-knowledge-portal: + +Offline Knowledge Portal (``okp``) +-------------------------------------- + +.. 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 as :ref:`redhat-registry-access`. + +.. code-block:: yaml + + spec: + okp: {} # no access key: browsing works, search doesn't + +.. code-block:: yaml + + spec: + okp: + accessKey: okp-access-key-secret # Secret key: "access_key" + +* **No ``accessKey``** (default) — browse docs and product lifecycle + content; no search, Solutions, or Articles. What upstream users run on. +* **With ``accessKey``** — full search and 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). + +Developer / experimental options (``dev``) +----------------------------------------------- + +.. warning:: + + Not part of the stable API — may change without notice. + +.. code-block:: yaml + + 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 + rhosMCPConfig: | + debug: true + workers: 4 + +* ``okpChunkFilterQuery`` — if unset, auto-detects your OpenShift/RHOSO + versions instead of using the literal example above. +* ``rhoso_mcps`` — deploys the MCP introspection sidecar (read-only). See + :doc:`usage`. diff --git a/docs/images/architecture.svg b/docs/images/architecture.svg new file mode 100644 index 0000000..f0ce2d4 --- /dev/null +++ b/docs/images/architecture.svg @@ -0,0 +1 @@ +

openstack-lightspeed namespace

lightspeed-stack pod

uses console widget

read-only, optional

System Administrator

Console Plugin

OpenStackLightspeed CR

lightspeed-operator

PostgreSQL

OKP

lightspeed-service-api

llama-stack

MCP tools sidecar

Your LLM endpoint

Your OpenStack / OpenShift APIs

 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..cab4db2 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +OpenStack Lightspeed Operator documentation +============================================ + +OpenStack Lightspeed is an AI-powered assistant, built for anyone running +`OpenStack `_ (an open-source cloud platform) +on OpenShift, that lives inside the OpenShift web console and answers +questions in plain English — grounded in real documentation, not guesses. + +Ask it something like *"How do I create a VM using the OpenStack CLI?"* or +*"Why would a Nova compute service show as down?"* — see :doc:`usage` for +more. + +You don't need an existing OpenStack deployment to try it — an OpenShift +cluster and an LLM you can point it at is enough (see :doc:`quickstart`). + +.. important:: + + This is a community release. Support is provided **upstream only**, + through `GitHub Issues + `_ + on this repository. There is no separate commercial support channel for + this project. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + quickstart + overview + install_guide + configuration + troubleshooting + usage diff --git a/docs/install_guide.adoc b/docs/install_guide.adoc deleted file mode 100644 index d24b5f0..0000000 --- a/docs/install_guide.adoc +++ /dev/null @@ -1,260 +0,0 @@ -= Installation Guide - -== Prerequisites - -* An OpenShift cluster (4.18+). -* Access to an LLM endpoint and an API key for it. OpenStack Lightspeed follows - a Bring Your Own Model (BYOM) approach: any provider from the supported list - in xref:supported-providers[Configuration] can be used. -* A free Red Hat Developer account, to pull certain component images (notably - the console plugin) from `registry.redhat.io`. See - <> below. -* Optionally, an existing `OpenStackControlPlane` if you want the assistant to - be aware of your OpenStack deployment. - -[#redhat-registry-access] -== Access to registry.redhat.io images - -Some of the images the operator deploys notably the console plugin and the -OKP (Offline Knowledge Portal) pod, both of which are deployed on every -install, not opt-in are published on `registry.redhat.io` rather than -`quay.io`. This is a deliberate -choice, not an oversight: the team evaluated mirroring these to `quay.io` and -decided against it, because the `quay.io` copies were not being kept up to -date. Until -https://github.com/openstack-k8s-operators/lightspeed-operator/pull/21[PR #21] -(which exposes image references on the `OpenStackLightspeed` CR) is merged, -there is no supported way to override these to point elsewhere so, for now, -plan on having `registry.redhat.io` access available. - -The good news: this only requires a **free** account, not a paid subscription. - -. Create a free Red Hat Developer account at - https://developers.redhat.com/[developers.redhat.com]. This gives you - access to developer tools and programs, including the images used here. -. Get a pull secret for CRC: log in to the - https://console.redhat.com/[Hybrid Cloud Console] with that account and - download your pull secret. This is the same `pull-secret.txt` referenced as - `PULL_SECRET` in the CRC setup below. -. Verify you have access before deploying, using Podman: -+ -[source,bash] ----- -$ podman login registry.redhat.io -Username: -Password: -Login Succeeded! - -$ podman pull registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12 -Trying to pull registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12... -Getting image source signatures -Copying blob ... done -Copying config ... done -Writing manifest to image destination ----- -+ -If you are not authenticated, the pull fails instead with: -+ -[source,console] ----- -Error: unable to copy from source docker://registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12: initializing source docker://...: unable to retrieve auth token: invalid username/password: unauthorized: Please login to the Red Hat Registry using your Customer Portal credentials. Further instructions can be found here: https://access.redhat.com/RegistryAuthentication ----- -+ -That error, or `ImagePullBackOff` on operator-managed pods, is a strong -signal you need to complete the steps above — see -xref:_console_widget_not_appearing[Troubleshooting] if it happens on the -console plugin specifically. - -TIP: This is tracked as a documentation TODO: once image references are -configurable on the CR (`PR #21`), this page will be updated to also show how -to point them at alternative registries if you prefer. - -== Installing the operator - -[IMPORTANT] -==== -OpenStack Lightspeed is not yet searchable from the in-console -*Operators -> OperatorHub* catalog. Publishing it there is tracked upstream by -https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/10781[community-operators-prod PR #10781] -(initial operator submission) and -https://github.com/redhat-openshift-ecosystem/community-operators-prod/pull/10782[PR #10782] -(OCP 4.18 catalog index update), both open as of this writing. Once merged, -the in-console search flow below will work directly. Until then, use one of -the two options first. -==== - -=== Option 1: Deploy from source (works today) - -[source,bash] ----- -git clone https://github.com/openstack-k8s-operators/lightspeed-operator.git -cd lightspeed-operator -make openstack-lightspeed-deploy ----- - -This creates a `CatalogSource` pointing at the published -`quay.io/openstack-lightspeed/operator-catalog:latest` image, plus the -`openstack-lightspeed` namespace, an `OperatorGroup`, and a `Subscription` — -then waits for the operator to come up. No OperatorHub listing required. - -=== Option 2: Add the catalog source manually - -If you don't want to clone the repository, apply the `CatalogSource` yourself: - -[source,yaml] ----- -apiVersion: operators.coreos.com/v1alpha1 -kind: CatalogSource -metadata: - name: openstack-lightspeed-catalog - namespace: openshift-marketplace -spec: - sourceType: grpc - image: quay.io/openstack-lightspeed/operator-catalog:latest - displayName: OpenStack Lightspeed Operator - publisher: Red Hat ----- - -Once it appears (`oc get catalogsource -n openshift-marketplace`), it shows up -under *Operators -> OperatorHub* in the console as a regular catalog entry — -find it there, or create a `Subscription` to it directly. - -=== Once published to OperatorHub - -After the PRs above merge, the flow becomes the standard one: - -. Open the OpenShift web console and navigate to *Operators -> OperatorHub*. -. Search for *"OpenStack Lightspeed (Community)"*. -. Click *Install* and select the desired namespace (the default is - `openstack-lightspeed`). -. Track progress under *Operators -> Installed Operators*, or from the CLI: -+ -[source,bash] ----- -$ oc get -n openstack-lightspeed pods -NAME READY STATUS RESTARTS AGE -openstack-lightspeed-operator-controller-manager-76df7fbfb5wggr 1/1 Running 0 72s ----- - -== Don't have a cluster yet? (CRC) - -For local development or testing, deploy an OpenShift CRC cluster using -`install_yamls` before running Option 1 or 2 above: - -[source,bash] ----- -git clone https://github.com/openstack-k8s-operators/install_yamls.git -cd install_yamls/devsetup -make download_tools - -CRC_VERSION=2.51.0 PULL_SECRET=~/work/pull-secret CRC_MONITORING_ENABLED=true CPUS=12 MEMORY=25600 DISK=100 make crc -make crc_attach_default_interface -eval $(crc oc-env) -cd ../.. ----- - -`PULL_SECRET` here is the same pull secret from -<> above. - -== Setting up LLM credentials - -To reach your LLM you need an API key, an endpoint URL, and a model name. - -`tlsCACertBundle` is **not** something most upstream users need to set. It -only matters if your LLM endpoint's TLS certificate isn't already trusted by -a public certificate authority — for example, a self-hosted vLLM/Ollama -endpoint using a self-signed or internal-CA certificate. Public providers -like Gemini, OpenAI, and Anthropic use publicly-trusted certificates, so -there's nothing to configure for them here; skip straight to applying the CR -below. - -Create the API key secret (referenced later as `llmCredentials`). The secret -*must* contain a key named `apitoken`: - -[source,bash] ----- -oc apply -f - < -EOF ----- - -If your LLM endpoint uses a custom or self-signed certificate, create a -ConfigMap with the CA bundle (referenced later as `tlsCACertBundle`). Every -key in the ConfigMap's `data` is parsed as PEM certificate data — the key -name itself doesn't matter (`cert` below is just a convention, not a -requirement), and you can include multiple keys/certificates: - -[source,bash] ----- -oc apply -f - <:/v1 - llmEndpointType: openai - llmCredentials: openstack-lightspeed-apitoken - modelName: - tlsCACertBundle: openstack-lightspeed-certs # optional ----- - -The operator reconciles this resource into the full stack: the AI engine -(lightspeed-stack and llama-stack/OGX), PostgreSQL, and the OpenShift console -plugin. - -== Verifying the deployment - -Check the `Ready` condition on the `OpenStackLightspeed` resource, and inspect -the deployments it created: - -[source,bash] ----- -oc describe -n openstack-lightspeed openstacklightspeed -oc get -n openstack-lightspeed deployments,pods ----- - -See xref:_troubleshooting[Troubleshooting] if the resource does not reach -`Ready`. - -== Accessing the assistant - -Once ready, open the -https://console-openshift-console.apps-crc.testing[OpenShift web console] and -use the Lightspeed widget in the lower-right corner. You may need to click the -*refresh* link that appears in a console notification the first time the -plugin is activated. - -If you are running CRC on a remote machine, you can reach the console with -`sshuttle`: - -* Add this line to your local `/etc/hosts` (don't change the IP): - `192.168.130.11 api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing` -* Run `sshuttle -r $remote_username@$remote_server 192.168.130.0/24`. diff --git a/docs/install_guide.rst b/docs/install_guide.rst new file mode 100644 index 0000000..f0dec19 --- /dev/null +++ b/docs/install_guide.rst @@ -0,0 +1,216 @@ +Installation Guide +=================== + +This page covers prerequisites, installing the operator, setting up LLM +credentials, and deploying ``OpenStackLightspeed``. No cluster yet? See +:ref:`dont-have-a-cluster-yet-crc` at the end of this page. + +Prerequisites +------------- + +* An OpenShift cluster (4.18+). + + .. warning:: + + Known issue: the console UI does not currently work on OpenShift 4.20 + or newer. Stick to 4.18/4.19 until this is resolved upstream. + +* An LLM endpoint and API key — any provider from + :ref:`supported-providers` works. +* A free Red Hat Developer account, to pull some images from + ``registry.redhat.io`` — see :ref:`redhat-registry-access` below. +* Optional: an existing ``OpenStackControlPlane``, only needed for the + experimental cluster-introspection feature (:doc:`usage`). + +.. _redhat-registry-access: + +Access to registry.redhat.io images +------------------------------------ + +The console plugin and OKP images (both always deployed) come from +``registry.redhat.io`` rather than ``quay.io``. This requires a **free** +account, not a paid subscription: + +#. Create a free account at `developers.redhat.com + `_. +#. Download a pull secret from the `Hybrid Cloud Console + `_. +#. Add it to your cluster: + + * **CRC**: pass it as ``PULL_SECRET`` when creating the cluster — see + :ref:`dont-have-a-cluster-yet-crc`. + * **Existing cluster**: merge it into the cluster-wide pull secret: + + .. code-block:: bash + + oc get secret/pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' \ + | base64 -d > pull-secret.json + # merge the downloaded auths into pull-secret.json, then: + oc set data secret/pull-secret -n openshift-config \ + --from-file=.dockerconfigjson=pull-secret.json + +#. Verify access: + + .. code-block:: console + + $ podman login registry.redhat.io + Login Succeeded! + + ``ImagePullBackOff`` on the console plugin or OKP pod almost always + means this step is missing — see :ref:`console-widget-not-appearing`. + +.. tip:: + + Once `PR #21 `_ + merges, image references become overridable on the CR, so this + requirement becomes optional. Until then, plan on having registry + access available. + +.. _installing-the-operator: + +Installing the operator +------------------------ + +#. **Operators → OperatorHub**, search for **"OpenStack Lightspeed + (Community)"**. +#. Click **Install**, choosing the ``openstack-lightspeed`` namespace. +#. Track progress under **Operators → Installed Operators**, or: + + .. code-block:: console + + $ oc get -n openstack-lightspeed pods + NAME READY STATUS RESTARTS AGE + openstack-lightspeed-operator-controller-manager-76df7fbfb5wggr 1/1 Running 0 72s + +.. tip:: + + Just-merged releases can take a little while to reach a cluster's + catalog. If a version doesn't show up right away, give it time. + +**Alternative — deploy from source** (for testing an unreleased build): + +.. code-block:: bash + + git clone https://github.com/openstack-k8s-operators/lightspeed-operator.git + cd lightspeed-operator + make openstack-lightspeed-deploy + +This sets up its own ``CatalogSource``, namespace, and ``Subscription`` — +bypassing OperatorHub entirely. + +Setting up LLM credentials +---------------------------- + +You need an API key, endpoint URL, and model name. + +Create the API key secret — the key **must** be named ``apitoken``: + +.. code-block:: bash + + oc apply -f - < + EOF + +Using a self-hosted endpoint with a self-signed certificate (e.g. vLLM, +Ollama)? Add its CA bundle too — any key name works, PEM data is all +that's parsed: + +.. code-block:: bash + + oc apply -f - <:/v1 + llmEndpointType: openai + llmCredentials: openstack-lightspeed-apitoken + modelName: + tlsCACertBundle: openstack-lightspeed-certs # optional + +This deploys the full stack: the AI engine (lightspeed-stack and +llama-stack/OGX), PostgreSQL, OKP, and the console plugin. + +Verifying the deployment +--------------------------- + +.. code-block:: bash + + oc describe -n openstack-lightspeed openstacklightspeed + oc get -n openstack-lightspeed deployments,pods + +Not reaching ``Ready``? See :doc:`troubleshooting`. + +Accessing the assistant +--------------------------- + +.. code-block:: bash + + oc whoami --show-console + +Open that URL and use the Lightspeed widget (lower-right corner). First +time activating the plugin, you may need to click **refresh** on the +console notification that appears. + +.. _dont-have-a-cluster-yet-crc: + +Don't have a cluster yet? (CRC) +----------------------------------- + +For local development/testing only (not for trying the assistant for real +— CRC is resource-constrained). Deploy a CRC cluster before +:ref:`installing-the-operator`: + +.. code-block:: bash + + git clone https://github.com/openstack-k8s-operators/install_yamls.git + cd install_yamls/devsetup + make download_tools + + CRC_VERSION=2.51.0 PULL_SECRET=~/work/pull-secret CRC_MONITORING_ENABLED=true CPUS=12 MEMORY=25600 DISK=100 make crc + make crc_attach_default_interface + eval $(crc oc-env) + cd ../.. + +``PULL_SECRET`` is the same pull secret from :ref:`redhat-registry-access`. + +CRC's console is always at a fixed address: +`console-openshift-console.apps-crc.testing +`_ — not something you +look up with ``oc whoami --show-console``. + +Running CRC remotely? Reach that console with ``sshuttle``: + +* Add to your local ``/etc/hosts`` (keep the IP as-is): + ``192.168.130.11 api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing`` +* Run ``sshuttle -r $remote_username@$remote_server 192.168.130.0/24``. diff --git a/docs/main.adoc b/docs/main.adoc deleted file mode 100644 index c2ce33c..0000000 --- a/docs/main.adoc +++ /dev/null @@ -1,22 +0,0 @@ -= OpenStack Lightspeed Operator documentation -:toc: left -:toclevels: 3 -:icons: font -:compat-mode: -:doctype: book -:context: osp -:imagesdir: images - -[IMPORTANT] -==== -This is a community release. Support is provided **upstream only**, through -https://github.com/openstack-k8s-operators/lightspeed-operator/issues[GitHub Issues] -on this repository. There is no separate commercial support channel for this -project. -==== - -include::readme.adoc[leveloffset=+1] -include::install_guide.adoc[leveloffset=+1] -include::configuration.adoc[leveloffset=+1] -include::troubleshooting.adoc[leveloffset=+1] -include::usage.adoc[leveloffset=+1] diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000..78614bf --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,19 @@ +Architecture +============ + +.. image:: images/architecture.svg + :alt: Architecture diagram. An OpenStackLightspeed CR is reconciled by + lightspeed-operator, which manages the Console Plugin, PostgreSQL, + OKP, and a lightspeed-stack pod containing lightspeed-service-api, + llama-stack, and an MCP tools sidecar. The Console Plugin proxies + user requests into the pod, llama-stack talks to OKP and to your + configured LLM endpoint, and the optional MCP sidecar makes + read-only calls to your OpenStack and OpenShift APIs. + +Two things worth calling out that aren't obvious from the box-and-arrow view: + +* The MCP tools run as a *sidecar container inside the lightspeed-stack + pod*, not a separate service — introspection stays local to the pod. +* **OKP is deployed on every install, not opt-in.** It's the default RAG + source; the bundled community documentation is available too, but only if + you explicitly opt in. See :doc:`configuration` for details. diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..eb132e8 --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,64 @@ +Quickstart +========== + +Already have an OpenShift cluster (4.18+) and an LLM endpoint? Three +steps and you're running. No cluster yet? See +:ref:`dont-have-a-cluster-yet-crc`. + +Install the operator +------------------------ + +**Operators → OperatorHub**, search **"OpenStack Lightspeed +(Community)"**, click **Install**. Full details (including what to do if +it's not visible yet): :doc:`install_guide`. + +Create the secret and CR +------------------------------ + +Save as ``secret.yaml``, with your own LLM API key: + +.. code-block:: yaml + + apiVersion: v1 + kind: Secret + type: Opaque + metadata: + name: openstack-lightspeed-apitoken + namespace: openstack-lightspeed + stringData: + apitoken: + +Save as ``cr.yaml``, with your own endpoint and model: + +.. code-block:: yaml + + apiVersion: lightspeed.openstack.org/v1beta1 + kind: OpenStackLightspeed + metadata: + name: openstack-lightspeed + namespace: openstack-lightspeed + spec: + llmEndpoint: https://:/v1 + llmEndpointType: openai + llmCredentials: openstack-lightspeed-apitoken + modelName: + +Then apply both: + +.. code-block:: bash + + oc apply -f secret.yaml + oc apply -f cr.yaml + +Self-hosted endpoint with a self-signed certificate, or a different +provider? See :doc:`install_guide` and :doc:`configuration` for the full +field reference. + +Open the console +--------------------- + +.. code-block:: bash + + oc whoami --show-console + +Open that URL and use the Lightspeed widget (lower-right corner). diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..c88c871 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx>=7.0,<8.0 +sphinx-rtd-theme>=2.0,<3.0 diff --git a/docs/troubleshooting.adoc b/docs/troubleshooting.adoc deleted file mode 100644 index 0cf0a29..0000000 --- a/docs/troubleshooting.adoc +++ /dev/null @@ -1,112 +0,0 @@ -= Troubleshooting - -== Start with the resource's conditions - -The `OpenStackLightspeed` resource reports its state through -`status.conditions`. Always start here: - -[source,bash] ----- -oc describe -n openstacklightspeed ----- - -The `Message` and `Status` columns (also visible via `oc get openstacklightspeed`) -summarize the current reconciliation state. Key condition types to look for: - -[cols="1,3", options="header"] -|=== -|Condition |Meaning - -|`OpenStackLightspeedReady` -|Overall readiness. `False`/`Unknown` means some part of the stack (engine, database, or console plugin) has not converged yet. - -|`OpenStackLightspeedMCPServerReady` -|Only relevant when the `rhoso_mcps` dev feature flag is enabled. Tracks the MCP introspection sidecar deployment. -|=== - -== Deployment-specific issues - -=== lightspeed-stack (engine) pod not becoming healthy - -The `lightspeed-stack-deployment` pod runs two containers: -lightspeed-service-api and llama-stack (OGX). Check both: - -[source,bash] ----- -oc logs -n deploy/lightspeed-stack-deployment -c lightspeed-service-api -oc logs -n deploy/lightspeed-stack-deployment -c llama-stack ----- - -A common cause of failure here is a bad or unreachable `llmEndpoint`, an -invalid `apitoken` in the `llmCredentials` secret, or a missing -`tlsCACertBundle` when the endpoint uses a self-signed certificate. The -llama-stack container will typically log an authentication or TLS error from -the provider in this case. - -=== PostgreSQL pod not starting - -[source,bash] ----- -oc logs -n deploy/lightspeed-postgres-server ----- - -If you changed `spec.database.size` to a *smaller* value than the existing -PVC, the operator rejects the change (shrinking a PVC in place isn't -supported) and reports it in the operator logs. Revert to the original size, -or delete and recreate the PVC if you intend to shrink it (this loses data). - -=== Console widget not appearing - -* Confirm the `ConsolePlugin` named `lightspeed-console-plugin` exists - (`oc get consoleplugin`) and is listed under `spec.plugins` on the cluster - `Console` resource (`oc get console.operator.openshift.io cluster -o yaml`). -* The console needs a moment to load newly-activated plugins. Click the - *refresh* link in the notification banner shown in the OpenShift console. -* Check the `lightspeed-console-plugin` deployment and pod logs for TLS - errors — the plugin serves over HTTPS using a service-ca-issued certificate - that can take a few seconds to appear after first deploy. -* If the pod is stuck in `ImagePullBackOff`/`ErrImagePull`, this is usually - missing `registry.redhat.io` access rather than a bug: the console plugin - image is hosted there, not on `quay.io`. See - xref:redhat-registry-access[Access to registry.redhat.io images] in the - Installation Guide to set up a free Red Hat Developer account and pull - secret, then verify with `podman login registry.redhat.io`. - -=== ImagePullBackOff on any operator-managed pod - -Some images (notably the console plugin) are pulled from `registry.redhat.io` -rather than `quay.io`. `oc describe pod` will show an error like: - -[source,console] ----- -Failed to pull image "registry.redhat.io/...": unauthorized: Please login to the Red Hat Registry using your Customer Portal credentials. ----- - -This means the node/cluster pull secret doesn't have `registry.redhat.io` -credentials. See -xref:redhat-registry-access[Access to registry.redhat.io images] for how to -get a free account and pull secret, and how to verify access with Podman -before troubleshooting further. - -=== CA bundle errors - -If `tlsCACertBundle` is set but reconciliation reports a CA parsing error, -verify every key in the ConfigMap's `data` contains valid PEM-encoded -certificate data (all keys are parsed, not just a specific one named `cert`), -and that none of them include extra leading/trailing whitespace introduced by -copy-pasting. - -== Getting operator logs - -[source,bash] ----- -oc logs -n deploy/openstack-lightspeed-operator-controller-manager ----- - -== Still stuck? - -This is a community release: support is provided upstream through GitHub -Issues. Please open an issue at -https://github.com/openstack-k8s-operators/lightspeed-operator/issues, -including the output of `oc describe openstacklightspeed`, relevant pod logs, -and your (redacted) `OpenStackLightspeed` resource spec. diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 0000000..949b508 --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,94 @@ +Troubleshooting +=============== + +Common failures, how to diagnose them, and where to get help if none of +this resolves it. + +Start with the resource's conditions +---------------------------------------- + +.. code-block:: bash + + oc describe -n openstacklightspeed + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Condition + - Meaning + * - ``OpenStackLightspeedReady`` + - Overall readiness. ``False``/``Unknown``: engine, database, OKP, or + console plugin hasn't converged yet. + * - ``OpenStackLightspeedMCPServerReady`` + - Only relevant with ``rhoso_mcps`` enabled. Tracks the MCP sidecar. + +Deployment-specific issues +------------------------------ + +lightspeed-stack (engine) pod not becoming healthy ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. code-block:: bash + + oc logs -n deploy/lightspeed-stack-deployment -c lightspeed-service-api + oc logs -n deploy/lightspeed-stack-deployment -c llama-stack + +Usual causes: bad/unreachable ``llmEndpoint``, invalid ``apitoken``, or a +missing ``tlsCACertBundle`` for a self-signed endpoint. llama-stack logs +the actual auth/TLS error from the provider. + +PostgreSQL pod not starting +++++++++++++++++++++++++++++ + +.. code-block:: bash + + oc logs -n deploy/lightspeed-postgres-server + +Shrinking ``spec.database.size`` below the existing PVC is rejected (not +supported in place). Revert the size, or delete/recreate the PVC to +actually shrink it (loses data). + +.. _console-widget-not-appearing: + +Console widget not appearing ++++++++++++++++++++++++++++++ + +* Confirm the ``ConsolePlugin`` (``lightspeed-console-plugin``) exists and + is listed under ``spec.plugins`` on ``oc get + console.operator.openshift.io cluster -o yaml``. +* Newly-activated plugins need a moment — click **refresh** on the + console notification. +* Check the plugin's pod logs for TLS errors — its service-ca certificate + can take a few seconds to appear after first deploy. + +.. _imagepullbackoff: + +ImagePullBackOff on any operator-managed pod ++++++++++++++++++++++++++++++++++++++++++++++ + +The console plugin and OKP pods come from ``registry.redhat.io``, not +``quay.io``: + +.. code-block:: console + + Failed to pull image "registry.redhat.io/...": unauthorized: Please login to the Red Hat Registry using your Customer Portal credentials. + +Means the pull secret is missing ``registry.redhat.io`` credentials — see +:ref:`redhat-registry-access` to fix and verify with Podman. + +CA bundle errors +++++++++++++++++++ + +If ``tlsCACertBundle`` causes a CA parsing error, check every key in the +ConfigMap's ``data`` for valid PEM data and no stray whitespace (all keys +are parsed, not just one named ``cert``). + +Getting operator logs +------------------------- + +.. code-block:: bash + + oc logs -n deploy/openstack-lightspeed-operator-controller-manager + +Still stuck? See :doc:`usage` for support. diff --git a/docs/usage.adoc b/docs/usage.adoc deleted file mode 100644 index 86bbe73..0000000 --- a/docs/usage.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= Usage - -== Asking questions - -Once the `OpenStackLightspeed` resource is `Ready`, open the OpenShift web -console and use the Lightspeed widget (bottom-right corner). Ask questions in -natural language, for example: - -* "How can I spin up a VM using the OpenStack CLI?" -* "Why would a Nova compute service show as down?" - -Responses are grounded via retrieval-augmented generation (RAG), and include -references you can verify. By default, grounding comes from -xref:_offline_knowledge_portal_okp[OKP] (deployed automatically with every -install, browsable without any extra credentials — see Configuration for the -free vs. keyed tiers). The bundled community OpenStack/OpenShift -documentation is also available as a RAG source, but only if you explicitly -set `dev.okpRagOnly: false`. - -== Cluster introspection (optional) - -When the `rhoso_mcps` dev feature flag is enabled (see -xref:_configuration[Configuration]), the assistant gains read-only tools -to inspect your actual OpenStack and OpenShift resources rather than relying -on documentation alone — for example, checking the status of a specific -service or resource in your deployment. - -* All introspection is **strictly read-only**: the assistant cannot modify - your cluster or your OpenStack deployment through these tools. -* Introspection happens locally, inside your cluster. Only the assistant's - query and retrieved context are sent to your configured LLM provider. -* The operator automatically provisions a scoped Keystone Application - Credential for this purpose when an `OpenStackControlPlane` is detected — - no manual credential setup is required. - -This capability is still evolving and ships disabled by default. - -== Feedback and transcripts - -Two independent, administrator-controlled settings affect data collection: - -* `feedbackEnabled` (default `true`) lets users thumbs-up/down individual - responses. -* `transcriptsEnabled` (default `false`) additionally collects full - conversation transcripts. - -Both are configured on the `OpenStackLightspeed` resource — see -xref:_configuration[Configuration]. Collected data is used to improve -answer quality in future releases; disable either setting if that doesn't fit -your environment's data handling policy. - -== Support - -OpenStack Lightspeed is a **community release**. Support is provided -**upstream only**, through GitHub Issues — there is no separate Red Hat -support entitlement for this project at this stage: - -* Operator issues: https://github.com/openstack-k8s-operators/lightspeed-operator/issues -* RAG content issues: https://github.com/openstack-k8s-operators/lightspeed-rag-content/issues -* MCP tooling issues: https://github.com/openstack-k8s-operators/lightspeed-mcps/issues - -When filing an issue, include the output of `oc describe openstacklightspeed`, -relevant pod logs, and your (redacted) `OpenStackLightspeed` spec — see -xref:_troubleshooting[Troubleshooting] for details. diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..68a71f7 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,58 @@ +Usage +===== + +Day-to-day use: asking questions, optional cluster introspection, +feedback/transcripts, and support. + +Asking questions +-------------------- + +Open the Lightspeed widget (bottom-right corner of the OpenShift console) +once ``OpenStackLightspeed`` is ``Ready``: + +* "How can I spin up a VM using the OpenStack CLI?" +* "Why would a Nova compute service show as down?" + +Answers are grounded via RAG, with references you can verify. By default, +grounding comes from :ref:`offline-knowledge-portal` (always deployed, no +credentials needed to browse — see :doc:`configuration` for the free vs. +keyed tiers). The bundled community documentation is also available, but +only if you set ``dev.okpRagOnly: false``. + +Cluster introspection (optional) +------------------------------------ + +Enabling the ``rhoso_mcps`` dev flag (:doc:`configuration`) gives the +assistant read-only tools to inspect your actual OpenStack/OpenShift +resources instead of relying on docs alone. + +* **Strictly read-only** — can't modify your cluster or OpenStack deployment. +* Introspection stays local to your cluster; only the query and retrieved + context go to your LLM provider. +* Credentials are automatic — the operator provisions a scoped Keystone + Application Credential when an ``OpenStackControlPlane`` is detected. + +Disabled by default; still evolving. + +Feedback and transcripts +---------------------------- + +* ``feedbackEnabled`` (default ``true``) — thumbs-up/down on responses. +* ``transcriptsEnabled`` (default ``false``) — full conversation transcripts. + +Both configured on the CR (:doc:`configuration`). Used to improve answer +quality — disable either if that doesn't fit your data policy. + +.. _support: + +Support +----------- + +Community release — support is **upstream only**, via GitHub Issues: + +* `lightspeed-operator issues `_ +* `lightspeed-rag-content issues `_ +* `lightspeed-mcps issues `_ + +Include ``oc describe openstacklightspeed`` output, pod logs, and your +(redacted) CR spec — see :doc:`troubleshooting`. From 37a6fbd54f5a81963981eed4e85ba445f425b6c6 Mon Sep 17 00:00:00 2001 From: Omkar Joshi <103182931+omkarjoshi0304@users.noreply.github.com> Date: Mon, 24 Aug 2026 16:51:36 +0100 Subject: [PATCH 3/3] Address second round of PR review feedback --- docs/conf.py | 2 +- docs/configuration.rst | 13 ++++-- docs/development.rst | 68 +++++++++++++++++++++++++++++++ docs/images/architecture.svg | 1 - docs/index.rst | 25 +++++++----- docs/install_guide.rst | 78 ++++++++++++------------------------ docs/overview.rst | 19 --------- docs/quickstart.rst | 21 +++++----- docs/requirements.txt | 1 + docs/troubleshooting.rst | 6 ++- docs/usage.rst | 27 ++++--------- 11 files changed, 145 insertions(+), 116 deletions(-) create mode 100644 docs/development.rst delete mode 100644 docs/images/architecture.svg delete mode 100644 docs/overview.rst diff --git a/docs/conf.py b/docs/conf.py index 5cec25f..1daabf9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -5,7 +5,7 @@ copyright = "OpenStack Lightspeed contributors" author = "OpenStack Lightspeed contributors" -extensions = [] +extensions = ["sphinxcontrib.mermaid"] exclude_patterns = ["_build", ".venv", "Thumbs.db", ".DS_Store"] diff --git a/docs/configuration.rst b/docs/configuration.rst index a314d83..a17bcb3 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -187,7 +187,14 @@ Developer / experimental options (``dev``) debug: true workers: 4 -* ``okpChunkFilterQuery`` — if unset, auto-detects your OpenShift/RHOSO - versions instead of using the literal example above. -* ``rhoso_mcps`` — deploys the MCP introspection sidecar (read-only). See +* ``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 :doc:`usage`. +* ``rhosMCPConfig`` is deep-merged on top of the operator's own defaults + — it can override anything the default config sets, including the + ``allow_write`` flags that keep introspection read-only. Only set this + if you understand exactly what you're overriding. diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 0000000..aa7cbb2 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,68 @@ +Development +============ + +This page is for contributors and anyone testing changes locally — not +needed if you're just installing and using the operator. + +.. _dont-have-a-cluster-yet-crc: + +Local cluster (CRC) +----------------------- + +For local development/testing only (not for trying the assistant for real +— CRC is resource-constrained). Deploy a CRC cluster before +:ref:`installing-the-operator`: + +.. code-block:: bash + + git clone https://github.com/openstack-k8s-operators/install_yamls.git + cd install_yamls/devsetup + make download_tools + + CRC_VERSION=2.51.0 PULL_SECRET=~/work/pull-secret CRC_MONITORING_ENABLED=true CPUS=12 MEMORY=25600 DISK=100 make crc + make crc_attach_default_interface + eval $(crc oc-env) + cd ../.. + +``PULL_SECRET`` is the same pull secret from :ref:`redhat-registry-access`. + +CRC's console is always at a fixed address: +`console-openshift-console.apps-crc.testing +`_ — not something you +look up with ``oc whoami --show-console``. + +Running CRC remotely? Reach that console with ``sshuttle``: + +* Add to your local ``/etc/hosts`` (keep the IP as-is): + ``192.168.130.11 api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing`` +* Run ``sshuttle -r $remote_username@$remote_server 192.168.130.0/24``. + +Architecture +--------------- + +.. mermaid:: + + graph TB + User[System Administrator] -->|uses console widget| Plugin + + subgraph ns["openstack-lightspeed namespace"] + CR[OpenStackLightspeed CR] --> Operator[lightspeed-operator] + Operator --> Plugin[Console Plugin] + Operator --> DB[(PostgreSQL)] + Operator --> OKP[OKP] + Operator --> Pod + + subgraph Pod["lightspeed-stack pod"] + API[lightspeed-service-api] --> OGX[llama-stack] + OGX -.-> MCP[MCP tools sidecar] + end + end + + Plugin --> API + OGX --> OKP + OGX --> LLM[Your LLM endpoint] + MCP -.->|read-only, optional| OSP[Your OpenStack / OpenShift APIs] + +**OKP is deployed on every install, not opt-in.** It's the default RAG +source; the bundled community documentation is available too, but only if +you explicitly opt in. See :doc:`configuration` for details. diff --git a/docs/images/architecture.svg b/docs/images/architecture.svg deleted file mode 100644 index f0ce2d4..0000000 --- a/docs/images/architecture.svg +++ /dev/null @@ -1 +0,0 @@ -

openstack-lightspeed namespace

lightspeed-stack pod

uses console widget

read-only, optional

System Administrator

Console Plugin

OpenStackLightspeed CR

lightspeed-operator

PostgreSQL

OKP

lightspeed-service-api

llama-stack

MCP tools sidecar

Your LLM endpoint

Your OpenStack / OpenShift APIs

 \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index cab4db2..88ae2ec 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,33 +1,38 @@ OpenStack Lightspeed Operator documentation ============================================ -OpenStack Lightspeed is an AI-powered assistant, built for anyone running -`OpenStack `_ (an open-source cloud platform) -on OpenShift, that lives inside the OpenShift web console and answers -questions in plain English — grounded in real documentation, not guesses. +OpenStack Lightspeed is an AI-powered assistant, tailored for Red Hat +OpenStack Services on OpenShift (RHOSO), that lives inside the OpenShift +web console and answers questions in plain English — grounded in real +documentation, not guesses. Ask it something like *"How do I create a VM using the OpenStack CLI?"* or *"Why would a Nova compute service show as down?"* — see :doc:`usage` for more. -You don't need an existing OpenStack deployment to try it — an OpenShift +You don't need an existing RHOSO deployment to try it — an OpenShift cluster and an LLM you can point it at is enough (see :doc:`quickstart`). .. important:: This is a community release. Support is provided **upstream only**, - through `GitHub Issues - `_ - on this repository. There is no separate commercial support channel for - this project. + via GitHub Issues — there is no separate commercial support channel + for this project: + + * `lightspeed-operator issues `_ + * `lightspeed-rag-content issues `_ + * `lightspeed-mcps issues `_ + + See :doc:`troubleshooting` for what to check, and what to include, + before filing an issue. .. toctree:: :maxdepth: 2 :caption: Contents: quickstart - overview install_guide configuration + development troubleshooting usage diff --git a/docs/install_guide.rst b/docs/install_guide.rst index f0dec19..f5ef7b8 100644 --- a/docs/install_guide.rst +++ b/docs/install_guide.rst @@ -3,24 +3,25 @@ Installation Guide This page covers prerequisites, installing the operator, setting up LLM credentials, and deploying ``OpenStackLightspeed``. No cluster yet? See -:ref:`dont-have-a-cluster-yet-crc` at the end of this page. +:doc:`development`. Prerequisites ------------- -* An OpenShift cluster (4.18+). +* An OpenShift cluster (4.16+). .. warning:: Known issue: the console UI does not currently work on OpenShift 4.20 - or newer. Stick to 4.18/4.19 until this is resolved upstream. + or newer. Stick to 4.18 until this is resolved upstream. * An LLM endpoint and API key — any provider from :ref:`supported-providers` works. * A free Red Hat Developer account, to pull some images from ``registry.redhat.io`` — see :ref:`redhat-registry-access` below. -* Optional: an existing ``OpenStackControlPlane``, only needed for the - experimental cluster-introspection feature (:doc:`usage`). +* Optional: RHOSO installed (so an ``OpenStackControlPlane`` exists), + only needed for the experimental cluster-introspection feature + (:doc:`usage`). .. _redhat-registry-access: @@ -49,22 +50,25 @@ account, not a paid subscription: oc set data secret/pull-secret -n openshift-config \ --from-file=.dockerconfigjson=pull-secret.json -#. Verify access: +#. Optional quick sanity check of your credentials (this only checks + *your* machine, not the cluster): .. code-block:: console $ podman login registry.redhat.io Login Succeeded! - ``ImagePullBackOff`` on the console plugin or OKP pod almost always - means this step is missing — see :ref:`console-widget-not-appearing`. +#. Verify the cluster itself can pull, using its own pull secret: -.. tip:: + .. code-block:: console + + $ oc run registry-pull-test --image=registry.redhat.io/openshift-lightspeed/lightspeed-console-plugin-pf5-rhel9:1.0.12 --restart=Never + $ oc get pod registry-pull-test - Once `PR #21 `_ - merges, image references become overridable on the CR, so this - requirement becomes optional. Until then, plan on having registry - access available. + Any status other than ``ImagePullBackOff``/``ErrImagePull`` means it's + working — clean up with ``oc delete pod registry-pull-test``. If you do + see it, the secret from the previous step didn't propagate — see + :ref:`console-widget-not-appearing`. .. _installing-the-operator: @@ -82,12 +86,14 @@ Installing the operator NAME READY STATUS RESTARTS AGE openstack-lightspeed-operator-controller-manager-76df7fbfb5wggr 1/1 Running 0 72s -.. tip:: +.. note:: - Just-merged releases can take a little while to reach a cluster's - catalog. If a version doesn't show up right away, give it time. + Currently published for OpenShift 4.16 and 4.18 specifically — on + other versions it won't appear in OperatorHub search. Use the + alternative below instead. -**Alternative — deploy from source** (for testing an unreleased build): +**Alternative — deploy from source** (for testing an unreleased build, or +if your OpenShift version isn't in the catalog yet): .. code-block:: bash @@ -142,7 +148,8 @@ Deploying OpenStackLightspeed -------------------------------- At minimum, set ``llmEndpoint``, ``llmEndpointType``, ``modelName``, and -``llmCredentials`` — see :doc:`configuration` for everything else: +``llmCredentials`` — see :doc:`configuration` for the full list of +supported ``llmEndpointType`` values and everything else: .. code-block:: yaml @@ -153,7 +160,7 @@ At minimum, set ``llmEndpoint``, ``llmEndpointType``, ``modelName``, and namespace: openstack-lightspeed spec: llmEndpoint: https://:/v1 - llmEndpointType: openai + llmEndpointType: llmCredentials: openstack-lightspeed-apitoken modelName: tlsCACertBundle: openstack-lightspeed-certs # optional @@ -181,36 +188,3 @@ Accessing the assistant Open that URL and use the Lightspeed widget (lower-right corner). First time activating the plugin, you may need to click **refresh** on the console notification that appears. - -.. _dont-have-a-cluster-yet-crc: - -Don't have a cluster yet? (CRC) ------------------------------------ - -For local development/testing only (not for trying the assistant for real -— CRC is resource-constrained). Deploy a CRC cluster before -:ref:`installing-the-operator`: - -.. code-block:: bash - - git clone https://github.com/openstack-k8s-operators/install_yamls.git - cd install_yamls/devsetup - make download_tools - - CRC_VERSION=2.51.0 PULL_SECRET=~/work/pull-secret CRC_MONITORING_ENABLED=true CPUS=12 MEMORY=25600 DISK=100 make crc - make crc_attach_default_interface - eval $(crc oc-env) - cd ../.. - -``PULL_SECRET`` is the same pull secret from :ref:`redhat-registry-access`. - -CRC's console is always at a fixed address: -`console-openshift-console.apps-crc.testing -`_ — not something you -look up with ``oc whoami --show-console``. - -Running CRC remotely? Reach that console with ``sshuttle``: - -* Add to your local ``/etc/hosts`` (keep the IP as-is): - ``192.168.130.11 api.crc.testing canary-openshift-ingress-canary.apps-crc.testing console-openshift-console.apps-crc.testing default-route-openshift-image-registry.apps-crc.testing downloads-openshift-console.apps-crc.testing oauth-openshift.apps-crc.testing`` -* Run ``sshuttle -r $remote_username@$remote_server 192.168.130.0/24``. diff --git a/docs/overview.rst b/docs/overview.rst deleted file mode 100644 index 78614bf..0000000 --- a/docs/overview.rst +++ /dev/null @@ -1,19 +0,0 @@ -Architecture -============ - -.. image:: images/architecture.svg - :alt: Architecture diagram. An OpenStackLightspeed CR is reconciled by - lightspeed-operator, which manages the Console Plugin, PostgreSQL, - OKP, and a lightspeed-stack pod containing lightspeed-service-api, - llama-stack, and an MCP tools sidecar. The Console Plugin proxies - user requests into the pod, llama-stack talks to OKP and to your - configured LLM endpoint, and the optional MCP sidecar makes - read-only calls to your OpenStack and OpenShift APIs. - -Two things worth calling out that aren't obvious from the box-and-arrow view: - -* The MCP tools run as a *sidecar container inside the lightspeed-stack - pod*, not a separate service — introspection stays local to the pod. -* **OKP is deployed on every install, not opt-in.** It's the default RAG - source; the bundled community documentation is available too, but only if - you explicitly opt in. See :doc:`configuration` for details. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index eb132e8..0123c7a 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,16 +1,16 @@ Quickstart ========== -Already have an OpenShift cluster (4.18+) and an LLM endpoint? Three -steps and you're running. No cluster yet? See -:ref:`dont-have-a-cluster-yet-crc`. +Already have an OpenShift cluster and an LLM endpoint? Three steps and +you're running. No cluster yet? See :ref:`dont-have-a-cluster-yet-crc`. Install the operator ------------------------ **Operators → OperatorHub**, search **"OpenStack Lightspeed -(Community)"**, click **Install**. Full details (including what to do if -it's not visible yet): :doc:`install_guide`. +(Community)"**, click **Install**. Currently published for OpenShift 4.16 +and 4.18 — on other versions, or if it's not showing up, see +:doc:`install_guide` for the source-based alternative. Create the secret and CR ------------------------------ @@ -28,7 +28,8 @@ Save as ``secret.yaml``, with your own LLM API key: stringData: apitoken: -Save as ``cr.yaml``, with your own endpoint and model: +Save as ``cr.yaml``, with your own endpoint, model, and provider type +(see :ref:`supported-providers` for valid values): .. code-block:: yaml @@ -39,7 +40,7 @@ Save as ``cr.yaml``, with your own endpoint and model: namespace: openstack-lightspeed spec: llmEndpoint: https://:/v1 - llmEndpointType: openai + llmEndpointType: llmCredentials: openstack-lightspeed-apitoken modelName: @@ -50,9 +51,9 @@ Then apply both: oc apply -f secret.yaml oc apply -f cr.yaml -Self-hosted endpoint with a self-signed certificate, or a different -provider? See :doc:`install_guide` and :doc:`configuration` for the full -field reference. +Self-hosted endpoint with a self-signed certificate? See +:doc:`install_guide` and :doc:`configuration` for the full field +reference. Open the console --------------------- diff --git a/docs/requirements.txt b/docs/requirements.txt index c88c871..2d2f3d9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx>=7.0,<8.0 sphinx-rtd-theme>=2.0,<3.0 +sphinxcontrib-mermaid>=0.9,<1.0 diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 949b508..fd62a1d 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -91,4 +91,8 @@ Getting operator logs oc logs -n deploy/openstack-lightspeed-operator-controller-manager -Still stuck? See :doc:`usage` for support. +Still stuck? See :doc:`index` for the repos to file an issue against. +When filing one, include ``oc describe -n openstack-lightspeed +openstacklightspeed`` output, pod logs, and your CR spec — **redact API +tokens, endpoint URLs/hostnames, and any retrieved context from all +three** before posting, since these are public issue trackers. diff --git a/docs/usage.rst b/docs/usage.rst index 68a71f7..cbb1938 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,8 +1,8 @@ -Usage -===== +Available Features +==================== -Day-to-day use: asking questions, optional cluster introspection, -feedback/transcripts, and support. +Day-to-day use: asking questions, optional cluster introspection, and +feedback/transcripts. Asking questions -------------------- @@ -26,7 +26,10 @@ Enabling the ``rhoso_mcps`` dev flag (:doc:`configuration`) gives the assistant read-only tools to inspect your actual OpenStack/OpenShift resources instead of relying on docs alone. -* **Strictly read-only** — can't modify your cluster or OpenStack deployment. +* **Strictly read-only by default** — only list/get/describe-style + ``openstack`` and ``oc`` commands are exposed as tools; nothing that + creates, updates, or deletes resources is available to the assistant + out of the box. * Introspection stays local to your cluster; only the query and retrieved context go to your LLM provider. * Credentials are automatic — the operator provisions a scoped Keystone @@ -42,17 +45,3 @@ Feedback and transcripts Both configured on the CR (:doc:`configuration`). Used to improve answer quality — disable either if that doesn't fit your data policy. - -.. _support: - -Support ------------ - -Community release — support is **upstream only**, via GitHub Issues: - -* `lightspeed-operator issues `_ -* `lightspeed-rag-content issues `_ -* `lightspeed-mcps issues `_ - -Include ``oc describe openstacklightspeed`` output, pod logs, and your -(redacted) CR spec — see :doc:`troubleshooting`.