Skip to content

require actor cpu and memory limits - #2285

Merged
Tim Hockin (thockin) merged 2 commits into
agent-substrate:mainfrom
BenTheElder:require-actor-limits
Oct 15, 2026
Merged

Tim Hockin (thockin) merged 2 commits into
agent-substrate:mainfrom
BenTheElder:require-actor-limits

Conversation

@BenTheElder

Copy link
Copy Markdown
Collaborator

We can still consider more flexible overcommit in the future, but I think leaving actors uncapped is unsafe, and it's hard to pick a reasonable universal default, it's too workload dependent.

Actor authors should really be aware of how much resources their actor requires, and tuning them can have significant performance impacts.

In the future we could do something like determining how much memory was in use at snapshot time and consider that for scheduling resumes.

Breaking change

ActorTemplates must declare CPU/memory limits.

Previously microvm actors had defaulting, and gvisor actors were simply uncapped.

This made the scheduler unaware of placement for gvisor.
Requiring it also ensures actor owners are aware of how much resources they cost.

Setting actor size will be important for performance particularly with microvms where higher memory limits have a real cost for e.g. snapshot/resume.

@BenTheElder
Benjamin Elder (BenTheElder) force-pushed the require-actor-limits branch 2 times, most recently from 0c0e541 to 693965e Compare October 7, 2026 02:09
@BenTheElder
Benjamin Elder (BenTheElder) marked this pull request as ready for review October 7, 2026 19:04
@BenTheElder

Benjamin Elder (BenTheElder) commented Oct 7, 2026 •

Copy link
Copy Markdown
Collaborator Author

DO NOT MERGE for a chance for input, this is kind of a big change.
That said we should decide soon.

I think the ideal API might look more like:

  • configurable requests (with a small default)
  • configurable limits (no default)
  • track actual usage at snapshot time and let the scheduler consider "how much resources do I need to resume the snapshot" in addition to "can I fit the actor requests/limits"

That has some edge cases to reason about and some tricky memory footprint awareness.
I don't think we can ship that before GA alongside the other pending API changes.

So I propose we make our existing limits API required for GA and then we can relax it later and pivot.

We could default limits instead, but I don't think we'll get a better default than users at this stage.

@csantanapr

Carlos Santana (csantanapr) commented Oct 8, 2026 •

Copy link
Copy Markdown

In the same spirit that some think a best practice is to not set CPU limits in pods, why do we think is a good idea to put cpu limits on actors?

Why its so critical to set limit now vs. leaving configurable in terms of GA API change?
Think leaving configurable and let the admins decide what they wan to enforce

@BenTheElder

Benjamin Elder (BenTheElder) commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator Author

In the same spirit that some think a best practice is to not set CPU limits in pods, why do we think is a good idea to put cpu limits on actors?

Because we need to be able to migrate sandboxes between machines, the reasons are in both the PR body and the comment above.

Right now if you don't set limits, you don't even have requests, because requests are missing.

If we had more time, we'd add requests now, I think we'll have to add that post-GA.

Why its so critical to set limit now vs. leaving configurable in terms of GA API change?
Think leaving configurable and let the admins decide what they wan to enforce

Because we cannot reliably schedule actors without a more complex implementation in the short term.

@csantanapr

Carlos Santana (csantanapr) commented Oct 8, 2026 •

Copy link
Copy Markdown

Right now if you don't set limits, you don't even have requests, because requests are missing.

I thought actorTemplate.resources (* ResourceRequirements) is where requests are specified and use for scheduling today

// +k8s:maxItems=2
// +k8s:listType=map
// +k8s:listMapKey=name
repeated Limits limits = 1;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Carlos Santana (@csantanapr) there are only limits, no requests, that type is unchanged by this PR.

@BenTheElder

Copy link
Copy Markdown
Collaborator Author

We had a general ACK in the community call today, this still needs code review though.

Comment thread docs/api-guide.md Resolved
the scheduler books these against worker capacity, so every template should declare its size.
an actor without limits fit on any worker and booked nothing. micro-VM also bakes its size into snapshots, so the old 2GiB/1 vCPU fallback could resume onto a worker too small to hold it.

drop the micro-VM default sizing.

// ValidateCustom_ActorTemplate_Resources requires both a cpu and a memory
// limit, which the scheduler books against worker capacity.
func ValidateCustom_ActorTemplate_Resources(_ context.Context, _ operation.Operation, fldPath *field.Path, value, _ *ateapipb.Resources) field.ErrorList {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, DV has a way to specify list-items but apparently it doesn't compose with "required". TODO.

@thockin Tim Hockin (thockin) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am anxious about the implications of this, but it seems better than nothing.

@thockin
Tim Hockin (thockin) added this pull request to the merge queue Oct 14, 2026
@BenTheElder

Copy link
Copy Markdown
Collaborator Author

I am anxious about the implications of this, but it seems better than nothing.

Yeah. This is extremely high on my post-GA list, I think we need a complete revamp of how we track actor footprint and offer requests + limits and make the scheduler aware of the snapshot size for actors without limits. But I don't think we have the bandwidth to review an API change like this before GA.

CPU throttling is probably the biggest risk here, we could probably prioritize relaxing the CPU limit requirement first if we need, since it doesn't have the same degree of placement risk for resume.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/api User-facing API changes breaking-change PRs with breaking changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants