Repository navigation
fix(kubernetes): move agent-sandbox to v0.5.4 #2764
Description
Activity
- changed the title
[-]bump(agent-sandbox): move to v0.5.4[/-][+]fix(kubernetes): move agent-sandbox to v0.5.4[/+]on Aug 16, 2026 🏗️ build-plan
Implementation Plan
Issue type:
fix
Complexity: Medium
Confidence: High — current compatibility behavior and upstream release artifacts are verifiedSummary
Move OpenShell’s default Agent Sandbox dependency from v0.5.0 to v0.5.4 across local Kubernetes setup, E2E, branch CI, and release-canary coverage. Select the release manifest name by version so v0.5.2+ uses
sandbox.yamlwhile the supported v0.4.6 compatibility lane continues usingmanifest.yaml; retain the already-compatible lifecycle logic and add focused regression assertions for v0.5.4’s persistentSuspendedcondition.Scope
tasks/scripts/helm-k3s-local.sh: default to v0.5.4 and selectmanifest.yamlfor legacy releases versussandbox.yamlfor v0.5.2+.e2e/support/install-agent-sandbox.sh: apply the same version-aware asset selection and v0.5.4 default.e2e/with-kube-gateway.sh: update the default v1beta1 controller version to v0.5.4..github/workflows/e2e-kubernetes-test.yml: update the reusable workflow’s default Agent Sandbox version..github/workflows/branch-e2e.yml: run combined and sidecar v1beta1 jobs against v0.5.4 while retaining v0.4.6..github/workflows/release-canary.yml: pin the Kubernetes canary to v0.5.4.crates/openshell-driver-kubernetes/src/driver.rs: extend lifecycle-condition tests to proveSuspended=False/NotSuspendedis not interpreted as stopped.crates/openshell-server/src/compute/mod.rs: cover the exact v0.5.4 running condition set and clarify that staleSuspended=Truecompatibility applies to older v1beta1 releases.docs/kubernetes/setup.mdx: replace the obsolete latest-releasemanifest.yamlinstallation URL withsandbox.yaml.deploy/helm/openshell/README.md.gotmpl: update the prerequisite installation URL.deploy/helm/openshell/README.md: regenerate the Helm README from its template.docs/reference/sandbox-compute-drivers.mdx: clarify that stop completion requiresSuspended=True, not merely condition presence.
No architecture document or agent skill changes are needed; the existing subsystem boundaries and skill instructions remain accurate.
Implementation Steps
- Add focused driver and gateway unit assertions for v0.5.4’s persistent
Suspended=Falserunning condition, while retaining legacy stale-condition compatibility. - Update both installer paths to default to v0.5.4 and resolve the release asset at the v0.5.2 rename boundary, then validate both v0.5.4 and v0.4.6 URLs.
- Update reusable workflow defaults, branch E2E matrix entries, and the release-canary pin to v0.5.4 without changing the v0.4.6 compatibility lane.
- Update published Kubernetes setup instructions and the Helm README template to use
sandbox.yaml, regenerate the Helm README, and clarify condition-status semantics in the compute-driver reference. - Run targeted unit checks, pre-commit/Helm documentation checks, and Kubernetes E2E against both supported release shapes.
Test Plan
- Unit tests: Extend tests in
openshell-driver-kubernetesandopenshell-serverforSuspended=False/NotSuspended,False/PodTerminating, andTrue/PodTerminated; run the targeted crate test suites. - Integration tests: Run
mise run helm:docs:checkandmise run pre-commit; verify both selected release asset URLs resolve successfully. - E2E tests: Run
mise run e2e:kubernetes:agent-sandbox-versions, exercising v0.5.4 stop/start behavior and the retained v0.4.6 fallback. Branch CI additionally covers v0.5.4 in sidecar topology.
Risks & Open Questions
- Asset selection must use the v0.5.2 boundary; changing every path unconditionally to
sandbox.yamlwould break v0.4.6. - v0.5.4 contains controller changes beyond condition persistence, so the live Kubernetes lifecycle suite is required.
- Use core-only
sandbox.yaml, notsandbox-with-extensions.yaml; OpenShell requires only the controller and Sandbox CRD, matching the priormanifest.yamlinstallation. - No stakeholder decisions are required.
Documentation Impact
Update the Kubernetes setup page, Helm chart prerequisites, generated Helm README, and compute-driver condition wording. No navigation changes are needed.
Gateway Config Documentation Impact
None. This does not add, remove, rename, or change defaults for gateway TOML or driver configuration fields.
LSM Compatibility
No impact. The change does not alter process identity, binary execution,
/procaccess, or inter-process visibility, so SELinux and AppArmor behavior is unchanged.
Revision 1 — initial plan
🏗️ build-from-issue-agent
Implementation Complete
PR: #2937
What was built
Updated Agent Sandbox defaults and CI coverage to v0.5.4, added version-aware release manifest selection that preserves v0.4.6 compatibility, and documented and tested the new lifecycle condition behavior.
Tests
- Unit: 2 regression tests added/extended; targeted current and legacy lifecycle tests pass
- Integration: pre-commit, Helm docs, shell syntax, and release asset URL checks pass
- E2E: attempted, but the local k3d node hit ephemeral-storage disk pressure and evicted the sandbox and gateway pods; details are recorded in the PR
Docs updated
- Kubernetes setup
- Helm chart prerequisite template and generated README
- Kubernetes compute-driver lifecycle reference
The issue will auto-close when the PR is merged.
This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
I rechecked the setup instructions on September 16. The command still uses
latest/download/manifest.yaml, which redirects tov1.0.2/manifest.yamland returns 404. The versioned sandbox.yaml returns 200.That manifest brought the controller to Ready in our K3s lab, though this doesn't establish full OpenShell compatibility.
#2937 already includes the URL correction, and I saw the request to update its controller version. Could the documentation correction ship separately if that version update needs more testing? The published prerequisite is still broken.
https://github.com/kubernetes-sigs/agent-sandbox/releases/tag/v0.5.4
v0.5.4contains a breaking change to theSuspendedcondition that we now use after the stop/start functionality in #2653Also, the release manifest changed from
manifest.yamltosandbox.yaml. We need up update any scripts/docs that refer to this manifest. The manifest name switched in v0.5.2.v0.5.1 and earlier manifest path (current): https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.0/manifest.yaml
v0.5.2 and later manifest path (new): https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.4/sandbox.yaml