github kubernetes-sigs/agent-sandbox v0.5.0rc1
on GitHub

pre-release6 hours ago

🚀 Announcing Agent Sandbox v0.5.0rc1!

We're excited to announce the release candidate of Agent Sandbox v0.5.0! This pre-release introduces major API advancements with the v1beta1 upgrade, enhanced warm pool management, critical security hardenings, and expanded developer tooling.

⚠️ Pre-Release Notice

This is a Release Candidate (RC) intended for early testing, validation, and feedback by maintainers and early adopters. It is not recommended for production environments.

Warning

Migrating existing v1alpha1 API objects to v1beta1 is not yet supported (coming soon); users must install this version in a clean environment (no pre-existing v1alpha1 CRDs or CRs).

⚠️ Breaking Changes / Action Required

  • API Group Upgrade (v1beta1) (#867): The core and extension APIs have been upgraded from v1alpha1 to v1beta1. All example manifests and documentation now reflect v1beta1.
  • SandboxClaim Specification Overhaul (#899): The spec.templateRef field in SandboxClaim has been replaced with spec.warmpoolRef to better reflect warm pool architectural integration.
  • System-Reserved Metadata Protection (#894): System-reserved Pod labels and annotations are now protected from tenant overrides to prevent privilege escalation and sandbox hijacking.

Key Highlights

  • API Evolution & Stability

    • API Graduation to v1beta1: The core Agent Sandbox API has been graduated from v1alpha1 to v1beta1, marking a significant step towards maturity and stability. This involves dropping legacy alpha schemas and updating controllers for parity.
    • Sandbox Lifecycle Management: Replaced spec.replicas with a new spec.operatingMode field (supporting Running and Suspended) to provide more explicit and granular control over Sandbox suspension and resumption. This is a breaking change.
    • SandboxClaim API Refinement: The SandboxClaim API now uses a spec.warmPoolRef instead of spec.templateRef, simplifying how claims interact with warm pools and enhancing clarity. This is an action-required breaking change.
    • Granular Sandbox Suspend Condition: Introduced an explicit Suspended condition in the Sandbox status for more accurate tracking of sandbox states, supporting future features like process freezing.
    • Orphan Adoption Restoration: Fixed a regression preventing the Sandbox controller from re-adopting unowned child resources (Pods, Services, PVCs) after Sandbox recreation, ensuring proper declarative lifecycle management.
    • Sandbox Template Ref Hash Propagation: The sandbox-template-ref-hash label is now consistently propagated to SandboxTemplate resources and adopted/cold-path Sandboxes, enabling easier client-side resolution of template-to-sandbox relationships.
    • Warm Pool Eviction: Implemented warm pool eviction using Cluster Autoscaler annotations, allowing idle, un-adopted Sandboxes to be marked as safe to evict.
    • Sandbox Name Annotation: The assigned Sandbox name is now stored in an annotation instead of a label to bypass Kubernetes' 63-character length constraint.

  • Security Enhancements

    • Sandbox Router Hardening: Addressed vulnerabilities related to unauthenticated internal proxying by enforcing strict sandbox_id validation, implementing optional Bearer token authentication, and tightening NetworkPolicy scoping to agent-sandbox-system namespace.
    • Pod Metadata Protection: Prevented tenants from overriding system-reserved Pod labels and annotations (agents.x-k8s.io/, extensions.agents.x-k8s.io/), mitigating potential traffic hijacking and spoofing.
    • Resource Hijacking Prevention: Introduced explicit label authorization (agents.x-k8s.io/adoptable: "true") before adopting unowned Pods, Services, and PVCs, fixing a critical vulnerability.
    • Python SDK Security: Disabled automatic HTTP redirects in SandboxConnector to prevent Server-Side Request Forgery (SSRF) attacks and sanitized OpenTelemetry trace attributes to prevent sensitive data exposure.
    • CI/Build Security: Fixed a Python module shadowing vulnerability in CI presubmits that could lead to Remote Code Execution (RCE) and added validation for KATA_VERSION to prevent path traversal.
    • IPv6 NetworkPolicy Hardening: The default NetworkPolicy now explicitly blocks IPv6 link-local traffic (fe80::/10), preventing untrusted code from accessing local services or cloud metadata endpoints.
    • Resourcectl PID Cleanup: Fixed a logic issue in resourcectl cleanup that could lead to arbitrary process termination due to stale heartbeat PIDs.
    • Analytics Tool Hardening: Patched a security vulnerability in the examples/analytics-tool allowing bypass of command execution allow-lists.

  • Performance & Scalability

    • Parallel Warm Pool Operations: Enabled parallel creation and deletion of sandboxes in the Warm Pool controller, significantly reducing reconciliation times (up to 4.26x faster).
    • Warm Pool Selection Optimization: Optimized the NodeSpread sandbox selection strategy to run purely in-memory, drastically reducing API server overhead and improving P99 concurrent claim latency by up to 4x.
    • Claim Status Update Optimization: Switched to patching for SandboxClaim status updates to reduce conflicts and improve scalability.
    • Memory Leak Reduction: Implemented measures to catch memory leaks and reduce per-scrape allocations across controllers and clients.

  • Python & Go SDK Improvements

    • Python SDK Client Enhancements: Added support for label selectors, hardened file upload path validation, enabled template-verified reattachment, and introduced shutdown_after_seconds for ephemeral sandboxes.
    • Python SDK Snapshot Restoration: Enabled restoration from dedicated snapshots, allowing sandboxes to be reverted to specific previous states.
    • Go SDK PodIP Routing: Implemented PodIP routing to fix connection issues with local sandbox-router gateways when cluster DNS is not available.

  • Enhanced Developer Experience & Tooling

    • Standardized GitHub Issue Templates: Added structured YAML templates for bug reports, feature requests, and maintainer epics, along with a config.yml for clearer contact links.
    • AI Code Review Integration: Configured CodeRabbit for automated PR summaries and walkthroughs, and optimized Copilot instructions to align with project toolchain, linting, and review scope policies.
    • Helm Chart Flexibility: Added podAnnotations, podLabels, podSecurityContext, and containerSecurityContext options to the controller Helm chart for greater customization and compliance with cluster security policies.
    • Build System Updates: Bumped Go versions across the repository and updated GitHub Actions dependencies. The PyPI publish process was also updated to allow release candidate versions.

  • Examples & Documentation

    • Sandboxed Tools Enhancements: Refactored tools into their own package, added functionality for persisting sessions across invocations, and enabled sandboxes to stay alive over multiple tool calls for faster execution.
    • New Example Workloads: Introduced a self-contained example for running an MCP server inside a sandbox with storage persistence, an AKS example using Kata Containers with sandbox warm pools, and a RayJob integration example.
    • Comprehensive Documentation Updates: All examples and documentation have been upgraded to reflect the v1beta1 API. New guides include detailed explanations of NetworkPolicy management, NodeLocal DNS with NetworkPolicy, and utilizing Dataplane-v2 for setup.

Installation

Core & Extensions

# To install only the core components:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.0rc1/manifest.yaml

# To install the extensions components:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.0rc1/extensions.yaml

Python SDK

pip install k8s-agent-sandbox==0.5.0rc1

Contributors

We extend our sincere thanks to all contributors to this release:
@aditya-shantanu, @AlexBulankou, @armistcxy, @arpitjain099, @chw120, @dependabot[bot], @hrsh1209, @ianchakeres, @janetkuo, @justinsb, @lauragalbraith, @moficodes, @mvanhorn, @patcrombie, @rainwoodman, @rmalani-nv, @ryanzhang-oss, @shaikenov, @shelwinnn, @SHRUTI6991, @shrutiyam-glitch, @tom1299, @tomergee, @vicentefb

👋 New Contributors

Full Changelog: v0.4.6...v0.5.0rc1

Check out latest releases or
releases around kubernetes-sigs/agent-sandbox v0.5.0rc1

Don't miss a new agent-sandbox release

NewReleases is sending notifications on new releases.

Get notifications