Repository navigation
fix(docs): microvm WorkerPools can host kagent Actors (#537) - #570
Conversation
Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
|
FYI - I broke some filepaths on your branch when i merged to main earlier - fixing them to resolve the conflict i created, then continuing to review. |
4fcc7cd to
d2dfb15
Compare
| > The `ateomImage` field in the [Inspect the runtime](#inspect-the-runtime) response reports this same setting, which the WorkerPool resource calls `workerImage`. To check which build a pool is running, compare the two names. | ||
|
|
||
| A cluster-scoped SandboxConfig named `gvisor-default` must also exist, because kagent names it directly rather than resolving a default. A missing one fails template preparation with `SandboxConfig "gvisor-default" not found`. | ||
| A cluster-scoped SandboxConfig for the pool's class must also exist, because kagent names it directly rather than resolving a default: `gvisor-default` for the `gvisor` class and `microvm` for the `microvm` class. A missing one fails template preparation with `SandboxConfig "<name>" not found`. |
There was a problem hiding this comment.
Blocking: this tells a reader a microvm SandboxConfig must exist, but there is no supported way to get one. Substrate applies only sandboxconfig-gvisor.yaml (cmd/ate-setup/internal/steps/deploy.go:462); the microvm config is a template staged out of band by hack/install-microvm-deps.sh --install, and kagent installs none of it. Add a prerequisite stating that microvm requires operator-staged assets that kagent does not provide.
| A pool's sandbox class decides which sandbox runtime its Workers provide, and kagent constrains the choice more tightly than Agent Substrate does. | ||
|
|
||
| Agent Substrate supports the `gvisor` and `microvm` classes, as explained in [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). kagent compiles every ActorTemplate to the `gvisor` class and to a SandboxConfig named exactly `gvisor-default`. Placement never relaxes the class constraint, so Workers in a `microvm` pool accept no kagent Actor, and the pool sits idle while turns time out. | ||
| Agent Substrate supports the `gvisor` and `microvm` classes, as explained in [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). kagent compiles every ActorTemplate to the class that its pool selected and to the matching SandboxConfig: a pool on `gvisor` (or no `sandboxClass`, which defaults to `gvisor`) gets the `gvisor` class and a SandboxConfig named `gvisor-default`, while a pool on `microvm` gets the `microvm` class and a SandboxConfig named `microvm`. Placement never relaxes the class constraint, so a Worker in a pool whose class does not match an ActorTemplate's class cannot host that Actor. |
There was a problem hiding this comment.
Dropping "sits idle while turns time out" is correct, but "cannot host that Actor" names nothing a reader can observe. Use the reasons the controller reports: RevisionInvalid with unsupported sandbox class "<value>" (go/core/internal/controller/reconciler.go:124), and WorkerPoolNotFound (reconciler.go:115).
| Agent Substrate supports the `gvisor` and `microvm` classes, as explained in [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). kagent compiles every ActorTemplate to the class that its pool selected and to the matching SandboxConfig: a pool on `gvisor` (or no `sandboxClass`, which defaults to `gvisor`) gets the `gvisor` class and a SandboxConfig named `gvisor-default`, while a pool on `microvm` gets the `microvm` class and a SandboxConfig named `microvm`. Placement never relaxes the class constraint, so a Worker in a pool whose class does not match an ActorTemplate's class cannot host that Actor. | ||
|
|
||
| Leave a pool that backs kagent Harnesses on `gvisor`, and keep the pool's image on the matching Worker build. | ||
| Leave a pool that backs kagent Harnesses on the class you intend to run, and keep the pool's image on the matching Worker build. |
There was a problem hiding this comment.
"the matching Worker build" never says what the match is. Name both images, ateom-gvisor and ateom-microvm, so a reader choosing microvm can act on this.
| Leave a pool that backs kagent Harnesses on the class you intend to run, and keep the pool's image on the matching Worker build. | ||
|
|
||
| ```yaml | ||
| substrateWorkerPool: |
There was a problem hiding this comment.
The prose above now covers both classes, but this example and the kubectl get sandboxconfigs output below it still show gvisor only. Add the microvm variant to both, or say that the example is the gVisor case.
| Because an Actor often runs a model-directed agent that calls tools and executes commands, Substrate runs each Actor in an isolated sandbox rather than a plain container. A WorkerPool's `sandboxClass` field selects the sandbox technology for its Workers: [gVisor](https://gvisor.dev), or a micro-VM that runs the workload under [Cloud Hypervisor](https://www.cloudhypervisor.org) with a [Kata Containers](https://katacontainers.io) kernel and root image. Both technologies isolate an Actor from its Worker's host kernel, and both support suspend and resume operations. | ||
|
|
||
| kagent compiles every ActorTemplate to the `gvisor` class, so a kagent agent runs in a {{< gloss "gVisor" >}}gVisor{{< /gloss >}} sandbox today and the micro-VM class is a Substrate capability that kagent does not yet select. Keep a WorkerPool that backs kagent Harnesses on `gvisor`. For what each class isolates, see [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). | ||
| kagent compiles each ActorTemplate to the sandbox class of the WorkerPool that hosts it, so a default installation runs kagent agents in a {{< gloss "gVisor" >}}gVisor{{< /gloss >}} sandbox, and a pool on the `microvm` class runs them under the micro-VM. A WorkerPool that backs kagent Harnesses should run the class it is meant to serve, with a matching Worker build. For what each class isolates, see [Sandboxing]({{< link path="about/substrate-runtime/sandboxing" >}}). |
There was a problem hiding this comment.
"run the class it is meant to serve" is circular, because a pool's class is what it serves. This also says "should" where sandboxing.md says "must" for the same instruction. Suggested: "A WorkerPool that backs kagent Harnesses must run the Worker build that matches its class."
Signed-off-by: Moritz Schmitz von Hülst <mschmitzvonhuelst@gmail.com>
Rachael-Graham
left a comment
Rachael-Graham
left a comment
There was a problem hiding this comment.
LGTM! Thank you very much.
2 participants
Closes #537
The docs told a reader that a
microvmWorkerPool cannot run kagent agents, steering them away from a supported configuration sincev1.0.0-alpha4(kagent#2918). The controller selects the ActorTemplate's sandbox configuration from the pool'ssandboxClass(sandboxConfigForClassingo/core/internal/substrate/actor_template.go):gvisor/empty →gvisor-default,microvm→microvm. So amicrovmpool hosts kagent Actors fine, provided the pool's Worker build and a matching cluster-scoped SandboxConfig exist.Changes:
operations/tune-agent-substrate.md— intro no longer says "any other class sits idle while turns time out"; the "Keep pools on the gvisor class" section now explains the per-class mapping and names bothgvisor-defaultand themicrovmSandboxConfig; the "must exist" note generalizes fromgvisor-defaultto the pool's class.substrate-runtime/sandboxing.md— the note about ActorTemplates using thegvisorclass now reflects per-class selection.about/architecture/agent-substrate.md— same correction (a default install runs gVisor; amicrovmpool runs the micro-VM).data/glossary.yaml— the gVisor tooltip no longer claims kagent compiles every ActorTemplate to gvisor.How to Test
Docs site:
cd docs-site && hugo mod get ./... && npm ci && hugo --config hugo.yaml --gc --minifybuilds cleanly (Hugo 0.160.1 extended, 626 pages). The renderedtune-agent-substratepage now reads "Keep pools on the sandbox class they serve".