fix(api): mark Sandbox.spec.volumeClaimTemplates immutable via CEL

[mesutoezdil]

Move the XValidation rule from the optional `volumeClaimTemplates` field to the `SandboxSpec` parent struct so the API server enforces immutability for all three transitions: set to modified set, unset to set, and set to unset. The previous rule on the optional field was skipped when the field was absent in either the old or new object, leaving two gaps.

This aligns Sandbox with the StatefulSet immutability contract and prevents controller reconciliation failures or orphaned PVCs caused by post-creation mutations.

Related issue: 727

Changes

• `api/v1beta1/sandbox_types.go`: move XValidation marker to `SandboxSpec` with `has()` checks covering all transitions
• `k8s/crds/agents.x-k8s.io_sandboxes.yaml`: regenerated via `go generate ./...`
• `helm/crds/agents.x-k8s.io_sandboxes.yaml`: regenerated via `go generate ./...`
• `docs/api.md`: regenerated via `make generate-api-docs`
• `test/e2e/volumeclaimtemplate_test.go`: added table-driven e2e tests for all three rejection cases

Summary by CodeRabbit

• New Features
  • Added validation to prevent changes to volumeClaimTemplates after a Sandbox is created.
• Documentation
  • Updated the API reference to explain that volumeClaimTemplates is immutable after creation, while the matching template field remains editable.
• Tests
  • Added end-to-end coverage for update attempts that modify, remove, or add volume claim templates, confirming they are rejected with a clear error.

[netlify]

✅ Deploy Preview for agent-sandbox canceled.

Name	Link
🔨 Latest commit	5d7b1cc
🔍 Latest deploy log	https://app.netlify.com/projects/agent-sandbox/deploys/6a455d07e556360009aa6450

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: mesutoezdil / name: mesutoezdil (a93d3cb)

[k8s-ci-robot]

Welcome @mesutoezdil!

It looks like this is your first PR to kubernetes-sigs/agent-sandbox 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/agent-sandbox has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @mesutoezdil. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[Copilot]

Pull request overview

This PR makes Sandbox.spec.volumeClaimTemplates immutable after creation by adding a CEL XValidation rule (self == oldSelf). This aligns Sandbox behavior with Kubernetes’ StatefulSet immutability expectations and prevents silent drift between Sandbox spec and already-created PVCs.

Changes:

• Added a kubebuilder XValidation CEL rule to enforce immutability of SandboxSpec.VolumeClaimTemplates.
• Regenerated CRDs in both k8s/crds/ and helm/crds/ to include the resulting x-kubernetes-validations stanza.
• Updated the API reference docs to mention the immutability behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
api/v1beta1/sandbox_types.go	Adds CEL immutability validation for spec.volumeClaimTemplates.
k8s/crds/agents.x-k8s.io_sandboxes.yaml	Regenerated CRD reflecting x-kubernetes-validations for the field.
helm/crds/agents.x-k8s.io_sandboxes.yaml	Same regenerated CRD change for the Helm chart.
docs/api.md	Documents that volumeClaimTemplates is immutable after creation.

[barney-s]

• While this is a step in the right direction to align with StatefulSet expectations, the current CEL rule configuration on an optional field leaves gaps that allow transitions from unset to set (and vice versa) on update. To ensure strict immutability, the validation rule should be defined at the parent struct level.
• Additionally, there are no tests included to verify this validation behavior.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: mesutoezdil
Once this PR has been reviewed and has the lgtm label, please ask for approval from barney-s. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[mesutoezdil]

Thanks @barney-s. Both points are addressed in the latest commit.

[aditya-shantanu]

/lgtm

[aditya-shantanu]

/lgtm

[aditya-shantanu]

/lgtm

[kubernetes-prow]

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[kubernetes-prow]

New changes are detected. LGTM label has been removed.

[kubernetes-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: mesutoezdil
Once this PR has been reviewed and has the lgtm label, please ask for approval from barney-s. For more information see the Code Review Process.

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

Details

Needs approval from an approver in each of these files:

• OWNERS

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a CEL-based immutability validation rule for volumeClaimTemplates on the v1beta1 SandboxSpec, propagates it to the generated CRD manifest, documents the restriction in the API docs, and adds an e2e test verifying that updates to this field after creation are rejected.

Changes

volumeClaimTemplates immutability

Layer / File(s)	Summary
API validation rule and generated artifacts api/v1beta1/sandbox_types.go, helm/crds/agents.x-k8s.io_sandboxes.yaml, docs/api.md	Adds a kubebuilder XValidation CEL rule requiring volumeClaimTemplates on SandboxSpec to stay unchanged once set, mirrors this rule in the generated CRD's x-kubernetes-validations, and documents that the field is immutable after creation while noting SandboxTemplate copies remain editable.
E2E immutability test test/e2e/volumeclaimtemplate_test.go	Adds TestSandboxVolumeClaimTemplatesImmutable, which attempts to append, unset, or modify volumeClaimTemplates on an existing Sandbox and asserts each update fails with a "volumeClaimTemplates is immutable" error.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: lgtm

Suggested reviewers: barney-s, janetkuo

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is specific and matches the main change: making Sandbox.spec.volumeClaimTemplates immutable via CEL.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR clearly explains the change, motivation, related issue, and affected files, though it doesn't explicitly use the template headings.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mesutoezdil]

This PR has been open since May 23, and in true fast-moving-monorepo fashion the codebase moved on without me. main landed #995, hoisting PodTemplate/VolumeClaimTemplates into a shared SandboxBlueprint struct used by both Sandbox and SandboxTemplate. That conflicted with this branch badly enough that I had to re-read my own diff to remember what it was doing.

To be honest, six weeks for a small, self-contained CEL rule change is a long time to sit in review, long enough that the base branch drifted out from under it and turned a trivial merge into an archaeology exercise. It would help to get eyes on small API PRs like this sooner, before the diff itself becomes stale.

@janetkuo @soltysh @barney-s @SHRUTI6991, tagging everyone who has already weighed in so this doesn't sit unnoticed again. Ready for another pass whenever you have time, hopefully without another multi-week wait and another round of drift to untangle.