From 2e2399c69a559b76b143d09b8b876a228487b63c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Jeanneret?= Date: Fri, 13 Nov 2026 11:21:39 +0000 Subject: [PATCH] feat(components): add optional OpenStack Assistant bricks Integrate the OpenStack Assistant (AI assistant for OpenStack, goose runtime) as opt-in kustomize components: - dependencies/lightspeed-operator: OpenStack Lightspeed operator (namespace, CatalogSource, OperatorGroup, Subscription) - dependencies/lightspeed: OpenStackLightspeed instance brick; LLM endpoint/model and apitoken Secret are patch points for the consuming overlay, never committed - rhoso/controlplane/services/openstackclient-mcp: patch enabling the MCP server sidecar (spec.openstackclient.template.mcp) on the OpenStackControlPlane's OpenStackClient - rhoso/assistant: OpenStackAssistant CR with PVC, hints, recipes (/cluster-health) and goose-config ConfigMaps, wired to the OpenStackClient MCP server and the in-cluster lightspeed stack - example/openstack-assistant: buildable example overlay - README: document the new bricks and composition Content derived from the lightspeed-operator docs and the openstack-operator OpenStackAssistant sample/types. AI-Tool: pi coding agent AI-Model: GLM-5.3 (rits/zai-org/glm-5-3) (Change reviewed by cjeanner after generation) --- README.md | 34 +++++++++++ .../lightspeed-operator/catalogsource.yaml | 16 +++++ .../lightspeed-operator/kustomization.yaml | 9 +++ .../lightspeed-operator/namespace.yaml | 5 ++ .../lightspeed-operator/operatorgroup.yaml | 10 ++++ .../lightspeed-operator/subscription.yaml | 14 +++++ .../lightspeed/kustomization.yaml | 6 ++ .../lightspeed/openstacklightspeed.yaml | 36 +++++++++++ components/rhoso/assistant/kustomization.yaml | 10 ++++ .../openstack-assistant-goose-config.yaml | 17 ++++++ .../assistant/openstack-assistant-hints.yaml | 26 ++++++++ .../assistant/openstack-assistant-pvc.yaml | 16 +++++ .../openstack-assistant-recipes.yaml | 41 +++++++++++++ .../rhoso/assistant/openstackassistant.yaml | 50 ++++++++++++++++ .../openstackclient-mcp/kustomization.yaml | 8 +++ .../openstack-controlplane-mcp.yaml | 14 +++++ .../openstack-assistant/kustomization.yaml | 59 +++++++++++++++++++ 17 files changed, 371 insertions(+) create mode 100644 components/dependencies/lightspeed-operator/catalogsource.yaml create mode 100644 components/dependencies/lightspeed-operator/kustomization.yaml create mode 100644 components/dependencies/lightspeed-operator/namespace.yaml create mode 100644 components/dependencies/lightspeed-operator/operatorgroup.yaml create mode 100644 components/dependencies/lightspeed-operator/subscription.yaml create mode 100644 components/dependencies/lightspeed/kustomization.yaml create mode 100644 components/dependencies/lightspeed/openstacklightspeed.yaml create mode 100644 components/rhoso/assistant/kustomization.yaml create mode 100644 components/rhoso/assistant/openstack-assistant-goose-config.yaml create mode 100644 components/rhoso/assistant/openstack-assistant-hints.yaml create mode 100644 components/rhoso/assistant/openstack-assistant-pvc.yaml create mode 100644 components/rhoso/assistant/openstack-assistant-recipes.yaml create mode 100644 components/rhoso/assistant/openstackassistant.yaml create mode 100644 components/rhoso/controlplane/services/openstackclient-mcp/kustomization.yaml create mode 100644 components/rhoso/controlplane/services/openstackclient-mcp/openstack-controlplane-mcp.yaml create mode 100644 example/openstack-assistant/kustomization.yaml diff --git a/README.md b/README.md index d3004ca..9d7e75a 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,40 @@ Provides the base for the OpenStackDataplaneNodeSet and OpenStackDataPlaneDeploy The CRs are extracted from the [RHOSO official documentation](https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_creating-the-data-plane) +### OpenStack Assistant / OpenStack Lightspeed + +Provides the optional building blocks to deploy the OpenStack Assistant (AI +assistant for OpenStack, based on Goose) and its dependencies. Each brick is +independent and opt-in: + +| Component | Purpose | +|-----------|---------| +| `components/dependencies/lightspeed-operator` | Deploys the OpenStack Lightspeed operator: `openstack-lightspeed` namespace, CatalogSource, OperatorGroup and Subscription (community catalog, `alpha` channel) | +| `components/dependencies/lightspeed` | Creates an `OpenStackLightspeed` instance (LLM inference stack). The consuming overlay must patch the LLM endpoint/model and provide the `apitoken` Secret out-of-band (e.g. via VSO/ESO) | +| `components/rhoso/controlplane/services/openstackclient-mcp` | Patches the `OpenStackControlPlane` to enable the MCP server sidecar (`spec.openstackclient.template.mcp`) on its `OpenStackClient` | +| `components/rhoso/assistant` | Creates the `OpenStackAssistant` CR (goose runtime) with its PVC, hints/recipes/goose-config ConfigMaps, wired to the OpenStackClient MCP server and the Lightspeed stack | + +Example overlay: + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +components: + - https://github.com/openstack-k8s-operators/gitops//components/dependencies/lightspeed-operator?ref=TAG + - https://github.com/openstack-k8s-operators/gitops//components/dependencies/lightspeed?ref=TAG + - https://github.com/openstack-k8s-operators/gitops//components/rhoso/controlplane/controlplane?ref=TAG + - https://github.com/openstack-k8s-operators/gitops//components/rhoso/controlplane/services/openstackclient-mcp?ref=TAG + - https://github.com/openstack-k8s-operators/gitops//components/rhoso/assistant?ref=TAG +# Patch spec.lightspeedStack.model and the OpenStackLightspeed LLM +# endpoint/model for your environment. +``` + +See the +[OpenStackAssistant documentation](https://github.com/openstack-k8s-operators/openstack-operator/blob/main/config/samples/assistant_v1beta1_openstackassistant.yaml) +and the +[OpenStack Lightspeed operator docs](https://github.com/openstack-k8s-operators/lightspeed-operator/tree/main/docs) +for details. + ### ArgoCD sync-wave annotation These annotations enable ArgoCD to determine the order that resources are created for the whole RHOSO cloud. [Learn more about sync-waves](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/) diff --git a/components/dependencies/lightspeed-operator/catalogsource.yaml b/components/dependencies/lightspeed-operator/catalogsource.yaml new file mode 100644 index 0000000..076bf65 --- /dev/null +++ b/components/dependencies/lightspeed-operator/catalogsource.yaml @@ -0,0 +1,16 @@ +--- +# CatalogSource for the OpenStack Lightspeed operator. +# The operator is community-published and not part of the default OperatorHub +# catalogs, so it needs its own CatalogSource. +# The image tag should be pinned by the consuming overlay (avoid :latest). +# https://github.com/openstack-k8s-operators/lightspeed-operator +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 diff --git a/components/dependencies/lightspeed-operator/kustomization.yaml b/components/dependencies/lightspeed-operator/kustomization.yaml new file mode 100644 index 0000000..6fa1a98 --- /dev/null +++ b/components/dependencies/lightspeed-operator/kustomization.yaml @@ -0,0 +1,9 @@ +--- +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +resources: + - namespace.yaml + - catalogsource.yaml + - operatorgroup.yaml + - subscription.yaml diff --git a/components/dependencies/lightspeed-operator/namespace.yaml b/components/dependencies/lightspeed-operator/namespace.yaml new file mode 100644 index 0000000..85cf483 --- /dev/null +++ b/components/dependencies/lightspeed-operator/namespace.yaml @@ -0,0 +1,5 @@ +--- +apiVersion: v1 +kind: Namespace +metadata: + name: openstack-lightspeed diff --git a/components/dependencies/lightspeed-operator/operatorgroup.yaml b/components/dependencies/lightspeed-operator/operatorgroup.yaml new file mode 100644 index 0000000..8f7fac0 --- /dev/null +++ b/components/dependencies/lightspeed-operator/operatorgroup.yaml @@ -0,0 +1,10 @@ +--- +# The OpenStack Lightspeed operator only supports OwnNamespace installs. +apiVersion: operators.coreos.com/v1 +kind: OperatorGroup +metadata: + name: lightspeed-operator-group + namespace: openstack-lightspeed +spec: + targetNamespaces: + - openstack-lightspeed diff --git a/components/dependencies/lightspeed-operator/subscription.yaml b/components/dependencies/lightspeed-operator/subscription.yaml new file mode 100644 index 0000000..183c9b1 --- /dev/null +++ b/components/dependencies/lightspeed-operator/subscription.yaml @@ -0,0 +1,14 @@ +--- +apiVersion: operators.coreos.com/v1alpha1 +kind: Subscription +metadata: + labels: + operators.coreos.com/openstack-lightspeed-operator.openstack-lightspeed: "" + name: openstack-lightspeed-operator + namespace: openstack-lightspeed +spec: + channel: alpha + installPlanApproval: Automatic + name: openstack-lightspeed-operator + source: openstack-lightspeed-catalog + sourceNamespace: openshift-marketplace diff --git a/components/dependencies/lightspeed/kustomization.yaml b/components/dependencies/lightspeed/kustomization.yaml new file mode 100644 index 0000000..58c5c3c --- /dev/null +++ b/components/dependencies/lightspeed/kustomization.yaml @@ -0,0 +1,6 @@ +--- +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +resources: + - openstacklightspeed.yaml diff --git a/components/dependencies/lightspeed/openstacklightspeed.yaml b/components/dependencies/lightspeed/openstacklightspeed.yaml new file mode 100644 index 0000000..9e6192b --- /dev/null +++ b/components/dependencies/lightspeed/openstacklightspeed.yaml @@ -0,0 +1,36 @@ +--- +# OpenStackLightspeed instance. Requires the lightspeed-operator component. +# +# Before applying, the consuming overlay MUST: +# - patch spec.defaultModel and spec.models[] with the actual LLM provider, +# endpoint and model (see the lightspeed-operator configuration docs): +# https://github.com/openstack-k8s-operators/lightspeed-operator/blob/main/docs/configuration.md +# - provide the Secret referenced by models[].llmCredentials (key: apitoken) +# in the openstack-lightspeed namespace, e.g. via the Vault Secrets +# Operator or External Secrets Operator components. Never commit it. +# +# Only one OpenStackLightspeed instance is allowed, in the namespace where the +# operator is installed (OwnNamespace mode). +# When the LLM endpoint uses a private or self-signed certificate, set +# spec.tlsCACertBundle from the consuming overlay and provide the referenced +# ConfigMap containing a PEM CA bundle. +apiVersion: lightspeed.openstack.org/v1beta1 +kind: OpenStackLightspeed +metadata: + name: openstack-lightspeed + namespace: openstack-lightspeed +spec: + # Set to the name of the model to use by default; must match one entry + # in spec.models[].name. + defaultModel: my-model + models: + - name: my-model + # LLM provider endpoint, e.g. https://api.example.com/v1 + llmEndpoint: https://REPLACE-WITH-LLM-ENDPOINT/v1 + # Supported types are listed in the lightspeed-operator configuration docs + llmEndpointType: openai + # Secret (key: apitoken) holding the LLM API token. Must be provided + # out-of-band, e.g. via VSO/ESO. + llmCredentials: openstack-lightspeed-apitoken + # Model name as known by the provider + modelName: REPLACE-WITH-MODEL-NAME diff --git a/components/rhoso/assistant/kustomization.yaml b/components/rhoso/assistant/kustomization.yaml new file mode 100644 index 0000000..917fb34 --- /dev/null +++ b/components/rhoso/assistant/kustomization.yaml @@ -0,0 +1,10 @@ +--- +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +resources: + - openstack-assistant-pvc.yaml + - openstack-assistant-hints.yaml + - openstack-assistant-recipes.yaml + - openstack-assistant-goose-config.yaml + - openstackassistant.yaml diff --git a/components/rhoso/assistant/openstack-assistant-goose-config.yaml b/components/rhoso/assistant/openstack-assistant-goose-config.yaml new file mode 100644 index 0000000..346b920 --- /dev/null +++ b/components/rhoso/assistant/openstack-assistant-goose-config.yaml @@ -0,0 +1,17 @@ +--- +# Goose configuration overlay projected into the assistant pod via +# spec.extraConfig. +apiVersion: v1 +kind: ConfigMap +metadata: + name: openstack-assistant-goose-config + namespace: openstack + labels: + app: openstack-assistant +data: + config.yaml: | + extensions: + summon: + enabled: true + todo: + enabled: true diff --git a/components/rhoso/assistant/openstack-assistant-hints.yaml b/components/rhoso/assistant/openstack-assistant-hints.yaml new file mode 100644 index 0000000..cca3a6b --- /dev/null +++ b/components/rhoso/assistant/openstack-assistant-hints.yaml @@ -0,0 +1,26 @@ +--- +# Hints projected into the assistant pod via spec.extraConfig. +apiVersion: v1 +kind: ConfigMap +metadata: + name: openstack-assistant-hints + namespace: openstack + labels: + app: openstack-assistant +data: + hints: | + This is an OpenStack deployment project running on an OpenShift cluster. + + ## Environment + - Use `oc` (OpenShift CLI) for cluster commands instead of `kubectl` + + ## Important + - Only use 'oc' (similar to 'kubectl') commands which *read* data. Do not edit or patch resources. + + ## Recipes + Custom slash commands are available. Type `/cluster-health` to run a cluster health check. + + ## Context Management + - Keep command outputs short. Use --no-headers, field selectors, and | head/tail to limit output. + - Summarize each command output immediately before running the next command. + - Do not store raw command output in memory; only retain the summary. diff --git a/components/rhoso/assistant/openstack-assistant-pvc.yaml b/components/rhoso/assistant/openstack-assistant-pvc.yaml new file mode 100644 index 0000000..b4dbd5e --- /dev/null +++ b/components/rhoso/assistant/openstack-assistant-pvc.yaml @@ -0,0 +1,16 @@ +--- +# Persistent storage for the assistant working directory (sessions, state). +# The storage class should be patched by the consuming overlay. +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: openstack-assistant-home + namespace: openstack + labels: + app: openstack-assistant +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi diff --git a/components/rhoso/assistant/openstack-assistant-recipes.yaml b/components/rhoso/assistant/openstack-assistant-recipes.yaml new file mode 100644 index 0000000..63c276b --- /dev/null +++ b/components/rhoso/assistant/openstack-assistant-recipes.yaml @@ -0,0 +1,41 @@ +--- +# Recipes (goose slash commands) projected into the assistant pod via +# spec.extraConfig. +apiVersion: v1 +kind: ConfigMap +metadata: + name: openstack-assistant-recipes + namespace: openstack + labels: + app: openstack-assistant +data: + cluster-health.yaml: | + version: "1.0.0" + title: Cluster Health Status Check + description: Run a full cluster health check using subagents for OpenShift and OpenStack categories, then output a combined markdown report + prompt: | + Run a cluster health check using two summon subagents, then immediately output the final report. Do not launch any additional subagents beyond the two described below. + + Use summon to create these two subagents: + + Subagent 1 - "OpenShift Health": Run each command and summarize the output before moving on: + - `oc get nodes -o wide` - note node count, roles, and any NotReady nodes. + - `oc get clusteroperators` and `oc get clusterversion` - note any degraded or unavailable operators. + - `oc get pv` - note any volumes that are not Bound. + - `oc get nncp` - note any degradations. + - `oc get events --all-namespaces --sort-by='.lastTimestamp' --field-selector type=Warning | tail -20` - summarize recent warnings. + Return a markdown section titled `## OpenShift Health` with findings. + + Subagent 2 - "OpenStack Health": Run each command and summarize the output before moving on: + - `oc get openstackcontrolplane -n openstack -o wide` - summarize the control plane status. + - `oc get pods -n openstack --field-selector=status.phase!=Running,status.phase!=Succeeded` - note any unhealthy pods. + Return a markdown section titled `## OpenStack Health` with findings. + + Once both subagents return their results, immediately output a final markdown report containing: + - `# Cluster Health Status Report` + - A timestamp + - The `## OpenShift Health` section from subagent 1 + - The `## OpenStack Health` section from subagent 2 + - A `## Summary` section with an overall assessment (Healthy / Degraded / Critical) and brief explanation of any issues. + + After outputting the report, you are done. Do not run any more commands or subagents. diff --git a/components/rhoso/assistant/openstackassistant.yaml b/components/rhoso/assistant/openstackassistant.yaml new file mode 100644 index 0000000..00db344 --- /dev/null +++ b/components/rhoso/assistant/openstackassistant.yaml @@ -0,0 +1,50 @@ +--- +# OpenStackAssistant instance (goose runtime with OpenStack/OpenShift MCP tools). +# +# Requirements: +# - a running RHOSO control plane in the openstack namespace +# - the MCP server sidecar enabled on the OpenStackClient +# (components/rhoso/controlplane/services/openstackclient-mcp) +# - a running OpenStackLightspeed stack reachable at spec.lightspeedStack.baseURL +# (components/dependencies/lightspeed-operator and +# components/dependencies/lightspeed) +# +# The consuming overlay should patch: +# - spec.lightspeedStack.model with the model configured in OpenStackLightspeed +# (/, discoverable from the ogx-config ConfigMap) +# - spec.containerImage if a pinned version is needed +# https://github.com/openstack-k8s-operators/openstack-operator/blob/main/config/samples/assistant_v1beta1_openstackassistant.yaml +apiVersion: assistant.openstack.org/v1beta1 +kind: OpenStackAssistant +metadata: + name: openstack-assistant + namespace: openstack +spec: + # Agent/harness image whose baked-in entrypoint renders its own config from + # the env vars and mounts the operator provides. Pin a specific tag in the + # consuming overlay. + containerImage: quay.io/openstack-s2i-containers/openstack-goose:master-latest + # AI backend: in-cluster OpenStackLightspeed API. The API key is derived + # from the pod service-account token, no provider secret is needed here. + lightspeedStack: + baseURL: https://lightspeed-app-server.openstack-lightspeed.svc:8443/v1 + # REPLACE with the model configured in OpenStackLightspeed + # (/) + model: REPLACE-WITH-MODEL + # MCP servers exposed to the assistant as MCP_SERVER_ env vars. + # openstackclient is the default OpenStackClient created by the + # OpenStackControlPlane; it requires the openstackclient-mcp component. + mcpServers: + - name: openstack + openstackClientRef: openstackclient + storage: + pvcName: openstack-assistant-home + # ConfigMaps projected into the pod for the image entrypoint to consume + # (hints, recipes, goose config overlay). + extraConfig: + - name: openstack-assistant-hints + mountPath: /etc/openstack-goose/hints + - name: openstack-assistant-recipes + mountPath: /etc/openstack-goose/recipes + - name: openstack-assistant-goose-config + mountPath: /etc/openstack-goose/config-overlay diff --git a/components/rhoso/controlplane/services/openstackclient-mcp/kustomization.yaml b/components/rhoso/controlplane/services/openstackclient-mcp/kustomization.yaml new file mode 100644 index 0000000..acd41fd --- /dev/null +++ b/components/rhoso/controlplane/services/openstackclient-mcp/kustomization.yaml @@ -0,0 +1,8 @@ +--- +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +patches: + - path: openstack-controlplane-mcp.yaml + target: + kind: OpenStackControlPlane diff --git a/components/rhoso/controlplane/services/openstackclient-mcp/openstack-controlplane-mcp.yaml b/components/rhoso/controlplane/services/openstackclient-mcp/openstack-controlplane-mcp.yaml new file mode 100644 index 0000000..978c27a --- /dev/null +++ b/components/rhoso/controlplane/services/openstackclient-mcp/openstack-controlplane-mcp.yaml @@ -0,0 +1,14 @@ +--- +# Enable the MCP server sidecar (MCPConfig) on the OpenStackClient created by +# the OpenStackControlPlane. The resulting MCP endpoint is consumed by the +# OpenStackAssistant (components/rhoso/assistant). +# https://github.com/openstack-k8s-operators/openstack-operator/blob/main/config/samples/assistant_v1beta1_openstackassistant.yaml +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackControlPlane +metadata: + name: openstack-control-plane +spec: + openstackclient: + template: + mcp: + enabled: true diff --git a/example/openstack-assistant/kustomization.yaml b/example/openstack-assistant/kustomization.yaml new file mode 100644 index 0000000..dd2bc31 --- /dev/null +++ b/example/openstack-assistant/kustomization.yaml @@ -0,0 +1,59 @@ +--- +# Example overlay composing the OpenStack Assistant and its dependencies. +# +# This example intentionally uses local component paths so it can be built and +# validated from a checkout. For a deployed environment, prefer remote refs +# pinned to a tag or hash once released, e.g.: +# https://github.com/openstack-k8s-operators/gitops//components/rhoso/assistant?ref=vX.Y.Z +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +components: + # 1. OpenStack Lightspeed operator and instance + - ../../components/dependencies/lightspeed-operator + - ../../components/dependencies/lightspeed + # 2. Control plane with MCP server sidecar enabled on OpenStackClient + - ../../components/rhoso/controlplane/controlplane + - ../../components/rhoso/controlplane/services/openstackclient-mcp + # 3. OpenStack Assistant (Goose runtime) + - ../../components/rhoso/assistant + +patches: + # Configure the LLM provider endpoint and model on OpenStackLightspeed. + # Remember to also provide the referenced Secret (key: apitoken) in the + # openstack-lightspeed namespace out-of-band (e.g. via VSO/ESO). + - target: + kind: OpenStackLightspeed + name: openstack-lightspeed + patch: |- + - op: replace + path: /spec/defaultModel + value: granite-3-8b-instruct + - op: replace + path: /spec/models/0 + value: + name: granite-3-8b-instruct + llmEndpoint: https://llm.example.com/v1 + llmEndpointType: openai + llmCredentials: openstack-lightspeed-apitoken + modelName: granite-3-8b-instruct + + # Point OpenStackAssistant to the model exposed by lightspeed-stack + # (/). + - target: + kind: OpenStackAssistant + name: openstack-assistant + patch: |- + - op: replace + path: /spec/lightspeedStack/model + value: my-provider/granite-3-8b-instruct + + # Optional: set the storageClass for the assistant PVC if no default + # StorageClass is defined on the cluster. + # - target: + # kind: PersistentVolumeClaim + # name: openstack-assistant-home + # patch: |- + # - op: add + # path: /spec/storageClassName + # value: lvms-vg1