api: Replace `spec.templateRef` in `SandboxClaim` with `spec.warmpoolRef`. by SHRUTI6991 · Pull Request #899 · kubernetes-sigs/agent-sandbox

SHRUTI6991 · 2026-05-30T23:00:56Z

What this PR does / why we need it:

This PR implements the API changes proposed in KEP-0208: Resolving Mutually Exclusive Fields in SandboxClaim for Beta.

Previously, a user creating a SandboxClaim had to provide a TemplateRef and could optionally specify a WarmPoolPolicy. This created ambiguity and conflicting states if the claim requested a template that did not match the underlying warm pool's template, and also risked naming collisions with custom warm pools.

To provide a cleaner, more predictable API contract for end-users, this PR removes the templateRef and warmpool policy fields from SandboxClaimSpec and replaces them with a single warmPoolRef.

Key Changes:

API Schema Update: Replaced TemplateRef and WarmPoolPolicy with WarmPoolRef in SandboxClaimSpec.
Implicit Cold Starts: Added logic to implicitly bypass the warm pool queue and trigger a cold start if the user provides custom environment variables (len(claim.Spec.Env) > 0).
Queue Refactoring: Refactored SimpleSandboxQueue to route and key off the WarmPoolName instead of the TemplateRefHash, enabling O(1) lookups directly against the requested pool.
Controller Updates: The SandboxClaim controller now looks up the SandboxWarmPool first, and dynamically resolves the associated SandboxTemplate when falling back to a cold start (i.e., when the pool is empty or bypassed).
Metrics & E2E: Updated E2E tests (chromesandbox_claim_test.go, pythonruntime_test.go, etc.) and the metrics collection to align with the new schema.

Which issue(s) this PR fixes:

Working on #740

Release note:

ACTION REQUIRED: The `SandboxClaim` API has been updated to use `warmPoolRef` instead of `templateRef`. The `warmpool` policy field has been removed. Users must now explicitly point their SandboxClaims to a `SandboxWarmPool`. To perform a cold start without pre-warming, cluster administrators should create a SandboxWarmPool with `replicas: 0` for users to reference.

netlify · 2026-05-30T23:01:01Z

✅ Deploy Preview for agent-sandbox canceled.

Name	Link
🔨 Latest commit	`cd231a1`
🔍 Latest deploy log	https://app.netlify.com/projects/agent-sandbox/deploys/6a1deab96e49a9000848384b

Copilot

Pull request overview

This PR implements KEP-0208's API change to remove the ambiguous combination of templateRef + warmpool policy in SandboxClaimSpec, replacing them with a single required warmPoolRef. The reconciler now resolves the underlying SandboxTemplate indirectly through the referenced SandboxWarmPool, and the in-memory warm-pool queue is keyed by warm-pool name instead of by template hash. A claim that supplies spec.env now implicitly bypasses the warm pool and triggers a cold start. All Go/Python clients, e2e tests, CRDs, and generated docs are updated for the rename.

Changes:

API: drop TemplateRef + WarmPoolPolicy from SandboxClaimSpec; introduce SandboxWarmPoolRef and WarmPoolRefField; lift SandboxTemplateRef into sandboxtemplate_types.go.
Controller: route adoption through WarmPoolRef, resolve template via warm pool, key SimpleSandboxQueue by warm-pool name, watch/index SandboxWarmPool, add ErrWarmPoolNotFound condition reason, replace "env + warmpool ⇒ error" with implicit cold start, and derive metric template_name from sandbox annotation or template lookup.
Clients/tests: rename template/TemplateName → warmpool/WarmPoolName across Go/Python SDKs and all unit/e2e tests; introduce SandboxWarmPoolNotFoundError; create explicit SandboxWarmPool objects for shutdown-policy and metrics e2e tests.

Reviewed changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
extensions/api/v1beta1/sandboxclaim_types.go	Drops `WarmPoolPolicy`/`TemplateRef`, adds `SandboxWarmPoolRef` and `WarmPoolRefField` index key.
extensions/api/v1beta1/sandboxtemplate_types.go	Moves `SandboxTemplateRef` definition next to the template type it references.
extensions/api/v1beta1/zz_generated.deepcopy.go	Regenerated deepcopy for the new `SandboxWarmPoolRef`/updated spec.
extensions/controllers/sandboxclaim_controller.go	Core rewrite: warm-pool-keyed queue, warm-pool watcher, implicit cold start on env, template resolution via warm pool, new error/reason.
extensions/controllers/queue/simple_sandbox_queue.go	Renames `templateHash` parameters to `warmPoolName` and updates comments.
extensions/controllers/sandboxclaim_controller_test.go	Adds warm-pool fixtures everywhere, replaces template-hash assertions with controller-ref/annotation lookups, removes the old `WarmPoolPolicy` test suite.
extensions/controllers/sandboxclaim_pod_exclusivity_test.go	Adds `SandboxWarmPool` object and keys the seeded queue by pool name.
k8s/crds & helm/crds sandboxclaims YAML	CRD schema updated: `warmPoolRef` required, `sandboxTemplateRef`/`warmpool` removed.
docs/api.md	Regenerated API reference for the new spec and `SandboxWarmPoolRef` type.
clients/go/sandbox/{options,client,sandbox,k8s,*_test}.go	Renames `TemplateName`→`WarmPoolName` and updates validation/error messages.
clients/go/examples/gateway/main.go	Updated field name (value still references "my-sandbox-template").
clients/python/.../sandbox_client.py, async_sandbox_client.py, k8s_helper.py, async_k8s_helper.py	Replace `template`/`warmpool` policy params with a single `warmpool` (name); add `SandboxWarmPoolNotFoundError` handling.
clients/python/.../exceptions.py, init.py	Export new `SandboxWarmPoolNotFoundError`.
clients/python/.../test/unit/*.py, test_client.py	Tests updated to the new API; some legacy `warmpool` policy tests retained but now exercise only naming.
test/e2e/extensions/{shutdown_policy_test,sandboxclaim_metric_test,warmpool_sandbox_watcher_test,pythonruntime_test}.go	Create a `SandboxWarmPool` per test and point claims at it.
test/e2e/{parallelism_test,chromesandbox_claim_test}.go	Switch parameters from template to warm-pool name.

Files not reviewed (1)

extensions/api/v1beta1/zz_generated.deepcopy.go: Language not supported

aditya-shantanu

Reviewed the KEP-0208 implementation (replacing spec.templateRef/warmpool with spec.warmPoolRef). Overall this matches the KEP's preferred solution and the mechanics line up well:

Generated artifacts are in sync — the CRD (extensions.agents.x-k8s.io_sandboxclaims.yaml) and docs/api.md were regenerated correctly, and WarmPoolPolicy is fully removed.
The warm-pool controller sets both the SandboxWarmPool owner reference and the SandboxTemplateRefAnnotation on warm sandboxes, so getWarmPoolName() and the metrics annotation fast-path both resolve as intended.
Watches/indexers/event handlers were consistently re-pointed from SandboxTemplate to SandboxWarmPool.

A few things worth addressing before merge — left inline. Nothing is a hard blocker except possibly the missing regression test for the central new behavior (implicit env-based cold start). Severity is noted per comment: most are minor/cleanup, one design point about the in-memory queue key is worth a maintainer decision.

(Note: this is an ACTION REQUIRED breaking change to the v1beta1 API made in-place — no conversion for already-stored SandboxClaim objects. That's consistent with the KEP's stated migration plan, just flagging it explicitly for the release notes / reviewers.)

janetkuo

/lgtm

k8s-ci-robot · 2026-06-01T21:04:18Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: janetkuo, SHRUTI6991

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [janetkuo]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

SandboxClaim API PR kubernetes-sigs/agent-sandbox#899 replaced the SandboxClaim spec.sandboxTemplateRef and spec.warmpool fields with a single spec.warmPoolRef; the controller now resolves the template through the warm pool. Update the load generator to emit warmPoolRef and bump the default manifest ref to the post-GoogleCloudPlatform#899 main HEAD so the installed CRDs match.

Make the agent_sandbox benchmark run: a SandboxClaim load generator, the metrics it produces, the Run wiring that drives them, and a provision/prepare install split for fast iteration. The load generator (agent_sandbox_loadgen.py) submits SandboxClaim custom resources at a target QPS through a single shared Kubernetes Watch stream (no per-claim polling). ClaimDriver handles create/watch with 429 retry and separate connection pools, LoadGenerator paces submission, and readiness is tracked with bounded concurrency. Claims reference the warm pool directly via spec.warmPoolRef (kubernetes-sigs/agent-sandbox#899 replaced sandboxTemplateRef/warmpool with a single warmPoolRef; the controller resolves the template through the warm pool), and the default manifest ref is bumped to the post-GoogleCloudPlatform#899 main HEAD so the installed CRDs match. The metrics module (agent_sandbox_metrics.py) computes startup-time percentiles, submit/completion QPS, peak concurrency, warm_served_fraction, error counts, and lifecycle/exec-duration percentiles from the recorded events. The benchmark Run constructs the load generator from the load-shape flags, runs it, and converts the recorded events into PKB samples (the stub Run from the resource PR returned nothing). Install is split across provision and prepare: provision installs only the cluster scaffolding (gVisor, CRDs, RBAC); the controller Deployment, sandbox template, and warm pool move to the prepare stage via a new K8sAgentSandbox.InstallWorkload. This lets the controller be reinstalled against an existing cluster with --run_stage=prepare to iterate on controller settings without recreating it. Because the benchmark spec is pickled at provision and unpickled without re-applying flags, Prepare calls RefreshSpecFromFlags on a resume so the controller, template, and warm pool config reflect the current command-line flags. Note: --run_stage=provision alone no longer installs the controller; run provision,prepare for a full setup. Adds the kubernetes Python client to requirements.txt, plus unit tests for the load generator, the metrics, and the provision/prepare split.

…Ref`. (kubernetes-sigs#899) * api: Replace templateRef in SandboxClaim with warmpoolRef. * Generate api doc. * Fix rebase conflict. * Address co-pilot comments. * Address all comments. * Add a TODO for requeueing logic.

…ollow-up) Replace sandboxTemplateRef with the mandatory warmPoolRef field in SandboxClaim manifests, matching the upstream API change introduced in commit 2feb713. - Rename createSandbox() parameter template → warmpool - Add inspectClaimConditions() to surface WarmPoolNotFound / TemplateNotFound terminal failures as typed errors - Add SandboxTemplateNotFoundError and SandboxWarmPoolNotFoundError - Add getSandboxClaimWarmpoolName() public method - Update unit tests to cover new error paths and renamed parameters

…Ref`. (kubernetes-sigs#899) * api: Replace templateRef in SandboxClaim with warmpoolRef. * Generate api doc. * Fix rebase conflict. * Address co-pilot comments. * Address all comments. * Add a TODO for requeueing logic.

…ollow-up) Replace sandboxTemplateRef with the mandatory warmPoolRef field in SandboxClaim manifests, matching the upstream API change introduced in commit 2feb713. - Rename createSandbox() parameter template → warmpool - Add inspectClaimConditions() to surface WarmPoolNotFound / TemplateNotFound terminal failures as typed errors - Add SandboxTemplateNotFoundError and SandboxWarmPoolNotFoundError - Add getSandboxClaimWarmpoolName() public method - Update unit tests to cover new error paths and renamed parameters

…Ref`. (kubernetes-sigs#899) * api: Replace templateRef in SandboxClaim with warmpoolRef. * Generate api doc. * Fix rebase conflict. * Address co-pilot comments. * Address all comments. * Add a TODO for requeueing logic.

* Refactor the Sandbox Template hash generation to include the namespace * tweaks after review * expand tests * Revert back to main * Partition SimpleSandboxQueue by Namespace * Log, conciseness, test * Pop and remove legacy as well as namespaced * Clean up state after rebase on PRs #899 and 864 * test GetWithStrategy fallback case * Remove unnecessary fallback cases, and nits * Clean up SimpleSandboxQueue changes from previous revisions

github-project-automation Bot added this to Agent Sandbox May 30, 2026

github-project-automation Bot moved this to Backlog in Agent Sandbox May 30, 2026

k8s-ci-robot requested review from aditya-shantanu and igooch May 30, 2026 23:01

k8s-ci-robot added needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels May 30, 2026

api: Replace templateRef in SandboxClaim with warmpoolRef.

6a3beb5

SHRUTI6991 force-pushed the warmpool_policy_kep_impl branch from 70d6ee3 to 6a3beb5 Compare May 30, 2026 23:05

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label May 30, 2026

SHRUTI6991 changed the title ~~api: Replace templateRef in SandboxClaim with warmpoolRef.~~ May 30, 2026

SHRUTI6991 added 2 commits May 30, 2026 23:07

Generate api doc.

afb6ee5

Fix rebase conflict.

699e6f2

janetkuo requested a review from Copilot May 31, 2026 00:00

Copilot started reviewing on behalf of janetkuo May 31, 2026 00:00 View session

Copilot AI reviewed May 31, 2026

View reviewed changes

Address co-pilot comments.

2b96a25

janetkuo added the ready-for-review label May 31, 2026

aditya-shantanu reviewed Jun 1, 2026

View reviewed changes

janetkuo reviewed Jun 1, 2026

View reviewed changes

Address all comments.

63e8adf

janetkuo reviewed Jun 1, 2026

View reviewed changes

Comment thread extensions/controllers/sandboxclaim_controller.go

Add a TODO for requeueing logic.

cd231a1

janetkuo approved these changes Jun 1, 2026

View reviewed changes

k8s-ci-robot assigned janetkuo Jun 1, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 1, 2026

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jun 1, 2026

k8s-ci-robot merged commit 2feb713 into kubernetes-sigs:main Jun 1, 2026
13 checks passed

github-project-automation Bot moved this from Backlog to Done in Agent Sandbox Jun 1, 2026

shrutiyam-glitch mentioned this pull request Jun 2, 2026

pss: Update templateref to warmpool ref in test file #912

Closed

tomergee mentioned this pull request Jun 2, 2026

Add Argo CD simple canary example with Python and Go routers #745

Open

barney-s mentioned this pull request Jun 2, 2026

fix(extensions): record correct launch type and pod condition for SandboxClaim cold starts #911

Closed

mvanhorn mentioned this pull request Jun 4, 2026

feat: propagate sandbox-template-ref-hash label to SandboxTemplate and adopted Sandboxes #864

Merged

geojaz mentioned this pull request Jun 4, 2026

agent_sandbox: load generator, metrics, and runnable benchmark GoogleCloudPlatform/PerfKitBenchmarker#6740

Open

lauragalbraith mentioned this pull request Jun 13, 2026

Partition SimpleSandboxQueue by Namespace #813

Merged

lauragalbraith added a commit to lauragalbraith/agent-sandbox that referenced this pull request Jun 16, 2026

Clean up state after rebase on PRs kubernetes-sigs#899 and 864

c5fd827

lauragalbraith added a commit to lauragalbraith/agent-sandbox that referenced this pull request Jun 23, 2026

Clean up state after rebase on PRs kubernetes-sigs#899 and 864

d0d4485

shrutiyam-glitch mentioned this pull request Jun 26, 2026

metric: add warmpool_name label for sandboxclaim metrics #1050

Merged

lunarwhite mentioned this pull request Jul 2, 2026

cleanup: Remove sandbox_template label from SandboxClaim startup latency metrics #1051

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

api: Replace `spec.templateRef` in `SandboxClaim` with `spec.warmpoolRef`.#899

api: Replace `spec.templateRef` in `SandboxClaim` with `spec.warmpoolRef`.#899
k8s-ci-robot merged 6 commits into
kubernetes-sigs:mainfrom
SHRUTI6991:warmpool_policy_kep_impl

SHRUTI6991 commented May 30, 2026

netlify Bot commented May 30, 2026 •

edited

Loading

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aditya-shantanu left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janetkuo left a comment

k8s-ci-robot commented Jun 1, 2026

Uh oh!

Labels

5 participants

Uh oh!

Conversation

SHRUTI6991 commented May 30, 2026

What this PR does / why we need it:

Which issue(s) this PR fixes:

Release note:

netlify Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for agent-sandbox canceled.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aditya-shantanu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janetkuo left a comment

Choose a reason for hiding this comment

k8s-ci-robot commented Jun 1, 2026

Uh oh!

Labels

5 participants

netlify Bot commented May 30, 2026 •

edited

Loading