volcano-sh / volcano-sh/agentcube
[Discussion] Evolving architecture: decouple agent provisioning from the Kubernetes control plane
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 167
- Forks
- 88
- Avg merge
- 44m
- Merged PRs (30d)
- 1
Description
Background
Today, AgentCube is built entirely around the Kubernetes control plane: every agent / code-interpreter session is backed by Kubernetes resources (sandbox CRs and Pods) that are created on demand by the Workload Manager. This gives us good governance, RBAC, and ecosystem integration — but it also means every session creation must go through the Kubernetes API server and scheduler.
As we move toward large-scale, parallel agent workloads (hundreds or thousands of agents starting in a short burst), this design shows some real limits.
Problems with the current architecture
-
Session creation is slow because it goes through Kubernetes scheduling.
Creating a sandbox involves many steps: CR creation → reconcile → Pod creation → scheduling → kubelet sync → image pull → microVM boot. Each step adds delay. Taking a couple of seconds to start a Pod is fine for long-running services, but for an interactive agent session that may only live for seconds, this delay is the main part of the user-visible latency. Warm pools help, but do not solve the problem: refilling the pool still goes through the full Kubernetes provisioning path, so a large burst that empties the pool falls back to cold-start latency. -
The API server is not designed for a huge number of short-lived objects.
Agent sessions are bursty and short-lived. If every session maps to Kubernetes objects, we generate a large volume of create/update/delete writes against etcd. At the scale of massive parallel agent creation, this becomes a bottleneck and can even hurt the stability of the whole cluster. -
Idle sandboxes waste resources.
Agents spend most of their time idle, waiting for input. Keeping one Pod per idle session wastes CPU and memory and limits how many agents a cluster can hold. Kubernetes has no native suspend/resume for Pods, and even if it did, going through the API server for every wake-up would be too slow. -
Capacity planning is mixed up with session lifecycle.
Today, "how much capacity is reserved for agents" and "how many agent sessions exist right now" are the same thing. Administrators have no way to plan and reserve capacity for agents ahead of time, independently of live sessions.
Proposed direction
Split the responsibilities into two layers:
-
Kubernetes manages resources, not sessions.
Administrators plan one or more resource pools ahead of time (e.g., a new CRD) dedicated to running agents. Kubernetes does what it is good at: provisioning nodes, scheduling long-running worker Pods (sandbox hosts), scaling the pool, and applying the usual RBAC / quota / policy to the pool definition. -
The AgentCube control plane manages agent sessions, without touching the Kubernetes API on the hot path.
When an agent creation / invocation request arrives, the control plane picks an available pool and assigns the session to it directly. No Kubernetes objects are created per session. Session state lives in the session store, not in etcd.
In short: Kubernetes owns the pool; AgentCube owns the sessions.
What I'm asking for
This issue is meant to start a discussion and agree on a direction, looking forward to your thoughts and welcome proposals!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the proposed split between Kubernetes-managed resource pools and AgentCube-managed sessions, including the Workload Manager and session store described in the issue. Done means reaching agreement on an architecture direction; the issue names no files, tests, or concrete implementation entry points.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes
- Domain
- backend, distributed-systems, infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100