spec(plane-on-kubernetes): Req 2/3 -- the reconciler stays the CLI with a remote mode; artifacts land in the store

Maintainer: trigger the checks in kube from the CLI and feed the results back;
execution is remote instead of local, not a separate service.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo
This commit is contained in:
Marius Ciepluch
2026-10-02 19:46:22 +02:00
co-authored by Claude Fable 5.1
parent 17ac7ad69d
commit 91a35a4406
+28 -18
View File
@@ -9,7 +9,7 @@ production entry point (a delta Run for a push) is added. Context: `brief.md`, `
## Boundary Context
- **In scope**: two profiles of one code base, `kind` (local, kept) and `k3s` (production); the reconciler as an in-cluster workload; receiver and router addressed as Services; configurable
- **In scope**: two profiles of one code base, `kind` (local, kept) and `k3s` (production); a remote execution mode of the CLI; artifacts delivered to the store; configurable
cluster context, registry and image pins; our own snapshot and memory buckets; the Joern engine as a plane task
on a larger worker pool; worker pool sizing and autoscaling; a delta Run command and Workspaces from URL +
commit; a deployment runbook with a proof on kind and a checklist for the target cluster.
@@ -46,33 +46,43 @@ configuration value, so the plane runs the same on kind and on the target cluste
2. `ousast plane doctor` checks the configured cluster, not kind by name, and reports each configured address.
3. A test enumerates the source tree for host-only literals and fails on any.
### Requirement 2: The reconciler runs in the cluster
### Requirement 2: The reconciler stays the CLI, with a remote execution mode
**User Story:** As the maintainer, I want runs submitted to a reconciler that lives in the cluster, so that a
push from CI, not a laptop session, drives the plane.
**User Story:** As the maintainer, I want to trigger the checks in the cluster from the CLI and get the results
fed back, so that remote execution is a mode of the same tool, not a separate service.
#### Acceptance Criteria
1. The reconciler runs as a Kubernetes workload (a Deployment serving a submit API, or a Job per Run; the design
decides) from the runner image, with a ServiceAccount whose RBAC allows what it does and nothing more.
2. It talks to ax-server and `atenet-router` through their Services, not port-forwards; the `ax` CLI, if kept, is
in the image.
3. Provider and store credentials come from Kubernetes Secrets into the reconciler's environment, never into a
manifest, an ActorTemplate or a log; the start-request path is unchanged.
4. kind stays a first-class local execution mode, not a stepping stone: `ousast plane run` from a laptop
1. `ousast plane run` (and the later `ousast plane scan`) takes an execution mode, `local` or `remote`, from the
profile or a flag; `remote` submits the Run to ax-server in the target cluster (over the cluster's ingress or a
kubeconfig), `local` is today's kind path. The manifests, the memory-key seeding, the budgets and the
attribution table are identical in both modes.
2. In remote mode the CLI needs no inbound path: it polls the memory store for task completion and artifacts and
prints the same status, attribution table and verdicts; `ousast plane status <run>` reports a Run started
earlier from any machine with the store credentials.
3. Provider and store credentials come from the caller's environment (a laptop `.env`, a CI secret), travel only
in the start request, and never appear in a manifest, an ActorTemplate or a log.
4. The principal the CLI uses against the cluster has the least privilege the ax API needs and nothing against
Agent Substrate directly; a test compares the rendered role with the calls the CLI makes.
5. kind stays a first-class local execution mode, not a stepping stone: `ousast plane run` from a laptop
against the kind cluster keeps working with the development profile (same code, same manifests, local
registry, host reconciler), and every release is proven on it before anything is applied to k3s.
registry), and every release is proven on it before anything is applied to k3s.
6. An unattended in-cluster reconciler (a Deployment or Job that runs without a caller) is a later option, not
part of this spec.
### Requirement 3: Receiver and artifacts without a host
### Requirement 3: Artifacts land in the store, not on a host
**User Story:** As the maintainer, I want task artifacts to land in the cluster or the store, not on a laptop.
**User Story:** As the maintainer, I want task artifacts delivered to the memory store so that no host has to
be reachable from the cluster.
#### Acceptance Criteria
1. The receiver is a Service of the in-cluster reconciler, or tasks deliver through presigned URLs to the S3
store (the design chooses one and states why); the kind gateway EndpointSlice is removed.
2. Egress policies grant each task exactly the hosts it needs (receiver or store, git hosts, the bound Model's
host) and nothing else; a test renders the policy for every committed Task.
1. Tasks deliver their artifacts to the S3 memory store (presigned URLs minted by the CLI and carried in the
start request, or a scoped delivery credential; the design chooses one and states why) and the CLI reads
completion from the store. The receiver thread and the kind gateway EndpointSlice remain only if the design
shows the local profile needs them; one delivery path for both profiles is preferred.
2. Egress policies grant each task exactly the hosts it needs (the store's endpoint, git hosts, the bound
Model's host) and nothing else; a test renders the policy for every committed Task.
### Requirement 4: The engine is a plane task