spec(plane-on-kubernetes): brief and requirements for review

Maintainer: the whole system moves to a Kubernetes cluster soon. Seven host-bound assumptions become cluster resources or configuration; the engine becomes a plane task on a larger pool; a delta Run command serves the pre-push use; every step is proven on kind first. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo
2026-10-20 05:29:28 +00:00 · 2026-10-02 19:36:59 +02:00
parent e5c338070d
commit 6187214be3
3 changed files with 160 additions and 0 deletions
@@ -0,0 +1,33 @@
+# Brief: the plane on a Kubernetes cluster
+
+Maintainer, 2026-10-02: "the plan is to move the whole to a kube system soon. what is in the way?" and earlier
+"later i will deploy this in a separate kube env."
+
+## Where we are
+
+The plane already runs on google/ax over Agent Substrate, on a single-node kind cluster on the maintainer's
+laptop (`ops/ax/`). Its manifests are ax's own kinds, every task is one digest-pinned runner image, the memory
+store is external (S3-compatible RustFS), and provider credentials travel only in the start request. What still
+assumes the laptop is small and listed in `docs/deployment.md` and `ops/ax/README.md`:
+
+1. the reconciler is a host CLI process (`ousast plane run`);
+2. the artifact receiver is a thread of that process, reached through a Service + EndpointSlice to the kind
+   gateway; the router is reached through a kubectl port-forward;
+3. the kube context `kind-ousast` and the registry `localhost:5001` are hard-coded in `doctor.py`, `egress.py`,
+   `router.py`;
+4. images come from the kind registry;
+5. ax's deploy manifest points `AX_SNAPSHOTS_BUCKET` at the ax authors' bucket;
+6. the Joern engine runs as a host Docker container (2.8 GB image, 3 GB memory), not as an ax task;
+7. the worker pool is two 1 CPU / 1.5 GiB workers with no autoscaling.
+
+## Direction
+
+Make the plane deployable to any Kubernetes cluster that runs Agent Substrate and ax, prove every change on the
+kind cluster first (it already behaves like the target), and leave nothing that only works on this host. The
+production use (a pre-push safety net fed by CI) needs, in addition, a delta Run command and Workspaces from a
+URL and commit; those are in scope as the last increment because they define what the cluster is for.
+
+## Not in scope
+
+Provisioning the maintainer's cluster, Substrate's and ax's own deployment procedures (followed, not changed),
+and any detection change.