Skip to content

stack-decisions.md

Latest commit

 

History

History
31 lines (16 loc) · 3.85 KB

stack-decisions.md

File metadata and controls

31 lines (16 loc) · 3.85 KB
Raw

Stack Decisions (Executive Summary)

One-paragraph overview of each accepted architecture decision, grouped by layer. Each entry links to the full ADR in docs/adr/.

For the full decision log with options considered, trade-offs, and references, see the ADR index.

Cross-cutting

  • ADR process — ADR-0001: Decisions are recorded as individual files in docs/adr/ with a dual index (technical README + this executive summary) to keep rationale traceable without cluttering AGENTS.md.

  • Explicit version pinning — ADR-0006: All operators, Helm charts, and container images are pinned to explicit versions. Upgrades are deliberate commits — no automatic channel updates — so the demo is reproducible across cluster provisions.

Infrastructure

  • OCP with RHOAI as base platform — ADR-0002: The demo runs on OpenShift Container Platform with Red Hat OpenShift AI (RHOAI) 3.x as the AI add-on, providing operator-managed MLflow, TrustyAI, and model serving through the DataScienceCluster CRD.

  • RHOAI DataScienceCluster component selection — ADR-0008: The demo enables dashboard, mlflowoperator, trustyai, and kserve (required for TrustyAI readiness). Deployment ordering fixes (Dashboard CRD wait, Helm-ownership adoption for odh-dashboard-config) are implemented in deploy/Makefile.

Platform Layer

  • OpenShell on OpenShift — ADR-0003: Agent sandboxing runs on the cluster via a single Helm release (wrapper chart 0.3.0, declaring the upstream OCI chart as a real Helm subchart dependency pinned 0.0.83 in Chart.yaml/Chart.lock — matching ADR-0006, corrected 2026-08-05 after two earlier, abandoned designs: first a dead unused dependency, then briefly a two-release ConfigMap round-trip), with TLS, certgen hook, and global.appsDomain replacing all bash-templated placeholders. Uses the Red Hat build of Agent Sandbox Operator (OLM, OSC 1.13 TP, package agent-sandbox-operator channel preview-0.9) as the sole source of the sandbox controller/router/CRDs — the upstream raw v0.5.1 manifest path was retired 2026-08-06. (Merges what was briefly a separate ADR-0009, since retired as a duplicate.)

  • NeMo Guardrails via TrustyAI — ADR-0004: Guardrails are deployed through the TrustyAI operator on OCP rather than a standalone sidecar, keeping lifecycle management within the RHOAI operator stack.

Agent Layer

  • OpenClaw as demo agent harness — This demo runs OpenClaw inside an OpenShell sandbox (AGENT-SANDBOX-AND-OPENSHELL.md, ROADMAP.md Phase 1.5/2). The BYOA principle is unchanged: the platform stack works regardless of which agent framework a customer chooses.

  • MLflow tracing via mlflow-openclaw plugin — ADR-0010: OpenClaw traces reach RHOAI's MLflow through the mlflow-openclaw plugin (patched for SDK compatibility), not the generic diagnostics-otel exporter — the latter produced traces with null Request/Response content, while the plugin hooks OpenClaw's own lifecycle events for full content.

  • OpenClaw UI authentication via nginx mTLS bridge + password — ADR-0011: The Control UI is reached through an nginx reverse proxy that presents mTLS client certificates to the OpenShell relay. OpenClaw gateway.auth.mode: password protects the WebSocket (shared OPENCLAW_GATEWAY_PASSWORD). Per-user OCP SSO via oauth-proxy was dropped — not a current requirement.