v0.5.0

> [!WARNING]
> **Upgrade Advisory (Warm-Started Claims Only):**  
> Releases `v0.5.0` and `v0.5.1` contain a status-wiping race condition during controller reconciliation that affects **warm-started `SandboxClaim`s** (`spec.warmPoolRef`).  
>   
> When upgrading from `v0.4.x` to `v0.5.0`/`v0.5.1`, initial bulk reconciliation of active warm claims can cause transient errors that wipe `status.sandbox.name`, forcing an unnecessary pod cold restart or re-adoption.  
>   
> **Scope:**  
> * **Fresh installations & Cold-start claims (`v1beta1`):** Not impacted during initial setup.  
> * **Upgrading from `v0.4.x` with active warm claims:** Please hold off on upgrading until **`v0.5.2`** is released (scheduled for Thursday, July 16).

# 🚀 Announcing Agent Sandbox v0.5.0!

We're excited to announce the release of Agent Sandbox v0.5.0! This release marks a significant milestone with the official graduation of our APIs to `v1beta1`, bringing enhanced stability, critical security hardening, and a wealth of new features and improvements across the platform, client SDKs, and examples. Dive in to experience a more robust and developer-friendly Agent Sandbox.

### ⚠️ Breaking Changes / Action Required

*   **API Group Upgrade and Deprecation (`v1alpha1` to `v1beta1`):**
    *   The core and extension APIs (`agents.x-k8s.io` and `extensions.agents.x-k8s.io`) have been officially graduated from `v1alpha1` to `v1beta1`.
    *   `v1alpha1` APIs are now deprecated. While multi-version CRD support is introduced with a conversion webhook, users are strongly encouraged to migrate their `v1alpha1` resources to `v1beta1`.
    *   **Action Required:** Update your manifests and API interactions to use `apiVersion: agents.x-k8s.io/v1beta1` and `apiVersion: extensions.agents.x-k8s.io/v1beta1`. Refer to the [API Migration Guide](https://github.com/kubernetes-sigs/agent-sandbox/blob/v0.5.0/docs/api-migration-guide.md) for detailed steps.
*   **Sandbox `spec.replicas` Removed, `spec.operatingMode` Introduced:**
    *   The `spec.replicas` field has been removed from the Sandbox API and replaced with `spec.operatingMode` (with values `Running` and `Suspended`).
    *   This is a breaking change for any automation or tools that relied on `spec.replicas` for scaling (e.g., `kubectl scale`, HorizontalPodAutoscalers, PodDisruptionBudgets).
    *   **Action Required:** Update your Sandbox manifests and any scaling logic to use `spec.operatingMode` for managing Sandbox lifecycle.
*   **SandboxClaim `spec.templateRef` Replaced by `spec.warmpoolRef`:**
    *   The `SandboxClaim` API no longer uses `spec.templateRef` or the `warmpool` policy field. Instead, claims must explicitly point to a `SandboxWarmPool` using `spec.warmpoolRef`.
    *   To achieve a cold start without pre-warming, cluster administrators should create a `SandboxWarmPool` with `replicas: 0` for users to reference.
    *   **Action Required:** Update `SandboxClaim` manifests to reference `spec.warmpoolRef` pointing to an existing `SandboxWarmPool` resource.
*   **NetworkPolicy Namespace Restriction for `sandbox-router`:**
    *   The default `NetworkPolicy` generated by the `SandboxTemplate` controller now strictly scopes ingress rules to the `agent-sandbox-system` namespace for the `sandbox-router`.
    *   **Action Required:** If your deployments are running the `sandbox-router` in a namespace other than `agent-sandbox-system`, you **must migrate and deploy the `sandbox-router` inside `agent-sandbox-system`** prior to or in tandem with upgrading the controller to avoid service interruption.

### Key Highlights

#### Core API & Platform Stability
*   **API Graduation & Multi-Version Support**: Official graduation of core and extension APIs to `v1beta1`, including multi-version CRD support with conversion webhooks for `v1alpha1` compatibility during migration (#817, #993).
*   **Sandbox Lifecycle Management**: Replaced `spec.replicas` with `spec.operatingMode` for more explicit control over Sandbox suspension and resume behavior (#801).
*   **SandboxClaim Enhancements**: `SandboxClaim` now uses `spec.warmpoolRef` for clearer warm pool association and gained printer columns for improved `kubectl get` visibility (#899, #984).
*   **Optimized Warm Pool Operations**: Enabled parallel creation and deletion of sandboxes within `SandboxWarmPool` controller, significantly speeding up scale operations (#798).
*   **Improved Warm Pool Selection Strategy**: Implemented a smart warm pool selection strategy that prioritizes ready sandboxes, spreads workloads across nodes, and optimizes for in-memory processing, reducing API overhead (#878, #939).
*   **Resource Adoption & Persistence**: Fixed orphan adoption for Sandbox child resources and introduced explicit authorization for unowned resources to prevent hijacking (#944, #784).
*   **Performance Improvements**: Switched `SandboxClaim` status updates to patching (`.Patch()`) to reduce conflicts at scale, improving overall system performance (#508).
*   **Helm Chart Enhancements**: Added support for `podSecurityContext`, `containerSecurityContext`, `podAnnotations`, and `podLabels` in the controller Helm chart for better Kubernetes policy compliance and custom metadata injection (#753, #750).
*   **Storage Configuration via SandboxClaim**: Introduced support for volume claim templates within SandboxClaims, enabling customized persistent volumes with policy-driven merging (#960).
*   **Warmpool Label Propagation**: Enhanced warmpool label propagation from sandbox to pod, ensuring consistent identification across resources (#927).
*   **Preserve Zero Replica Counts**: Fixed an issue where zero replica counts in warmpool status were not preserved during server-side apply operations (#807).
*   **Assigned Sandbox Name Storage**: Switched to storing assigned Sandbox names in annotations instead of labels to bypass Kubernetes length constraints (#771).

#### Security & Hardening
*   **SSRF Protections**: Disabled automatic HTTP redirects in both Go and Python SDKs to prevent Server-Side Request Forgery (SSRF) vulnerabilities from untrusted sandbox workloads (#874, #816).
*   **Router Security**: Addressed an unauthenticated internal proxy vulnerability in the sandbox router with strict input validation and optional bearer token authentication (#755).
*   **Network Policy Enhancements**: Default `NetworkPolicy` now blocks IPv6 link-local traffic and strictly scopes ingress to the `agent-sandbox-system` namespace for the `sandbox-router` for enhanced isolation (#827, #881).
*   **Build-time Injection Prevention**: Sanitized git-derived version strings to prevent build-time command injection vulnerabilities (#946).
*   **Denial of Service (ReDoS) Fix**: Replaced a vulnerable regex matching function with an iterative dynamic programming approach to resolve a ReDoS vulnerability (#935).
*   **Pod Metadata Protection**: Protected system-reserved Pod labels and annotations from tenant override to prevent traffic hijacking or tracking label forging (#894).
*   **Warm Pool Poisoning Prevention**: `isAdoptable` function now explicitly rejects unowned sandboxes to prevent warm pool poisoning (#875).
*   **OpenTelemetry Trace Sanitization**: Sanitized `sandbox.command` attribute in OpenTelemetry traces to prevent sensitive data exposure (#895).
*   **CLI Tool Hardening**: Fixed concurrency race conditions and stale PID cleanup issues in `resourcectl` CLI utility, preventing data loss and arbitrary process termination (#934, #902).

#### Client SDK & Developer Experience
*   **Dynamic Timeout Propagation**: SDKs now support dynamic timeout propagation to the sandbox router, ensuring long-running operations are not prematurely terminated (#857).
*   **Python Async Client Cleanup**: Added `cleanup=True` support to `AsyncSandboxClient` for automatic resource cleanup on program termination (#859).
*   **Python `additionalPodMetadata` Exposure**: Exposed `additionalPodMetadata` in the Python client for direct control over Sandbox Pod labels and annotations (#979).
*   **Go Client PodIP Routing**: Enabled PodIP routing in the Go client to resolve connection issues when Kubernetes DNS is unavailable for sandbox services (#910).
*   **Sandbox Client Improvements**: Hardened filesystem path sanitization, improved label selectors, and enabled template-verified reattachment in the Python SDK (#695).
*   **PSS SDK Enhancements**: Enabled restoration from dedicated snapshots and filtering by creation timestamp for the Python Snapshot SDK (#799, #732).
*   **CI/CD & Tooling**: Optimized CI staging builds, increased promotion timeouts, and updated `pyyaml` dependency for CRD sorting during release publish (#1021). Improved AI code review configuration and guidelines for Copilot and CodeRabbit (#938, #936, #947, #866).

#### Examples & Documentation
*   **RL & Evals Example**: Introduced `agent-sandbox-rl`, a complete Python package for multi-cluster warm-pool orchestration of RL and Evals workloads (#1000).
*   **Anthropic Agents Example**: Added an example for running Anthropic Managed Agents self-hosted sandboxes on GKE Agent Sandbox (#950).
*   **Sandboxed Tools Enhancements**: Improved `sandboxed-tools` examples to persist sessions and filesystem state across multiple tool calls and refactored tools into their own package (#888, #887, #877, #886).
*   **MCP Server Example**: Provided an example for running an MCP server inside a sandbox with persistent storage (#937).
*   **AKS Kata Container Example**: Added an AKS example demonstrating Kata Containers with sandbox warm pools (#839).
*   **Ray Integration**: Documented an example on how to run a RayJob with Agent Sandbox via direct PodIP (#868, #742).
*   **Comprehensive Troubleshooting Guide**: Added a detailed troubleshooting guide for debugging SDK, custom image, and cluster-level issues (#660).
*   **API & NetworkPolicy Documentation**: Updated documentation to reflect `v1beta1` API changes, clarified NodeLocal DNS walkthrough, and expanded NetworkPolicy guidance (#867, #823, #815).
*   **Issue Templates**: Added structured GitHub issue templates for bug reports, feature requests, and epics, and improved their ordering (#880, #891).

### Installation

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

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

To upgrade from v0.4.6 to v0.5.0, please follow the detailed steps in [API Migration Guide](https://github.com/kubernetes-sigs/agent-sandbox/blob/v0.5.0/docs/api-migration-guide.md).

#### Python SDK
```bash
pip install k8s-agent-sandbox==0.5.0
```

---
### Contributors
We extend our sincere thanks to all contributors to this release:
@AlexBulankou, @ArthurKamalov, @HasonoCell, @RidPra, @SHRUTI6991, @aditya-shantanu, @aleks-stefanovic, @alimx07, @dependabot, @armistcxy, @arpitjain099, @chw120, @hrsh1209, @ianchakeres, @inardini, @janetkuo, @justinsb, @kannon92, @lauragalbraith, @mesutoezdil, @moficodes, @mvanhorn, @patcrombie, @rainwoodman, @rmalani-nv, @ryanzhang-oss, @sairajp-rewind, @shaikenov, @shelwinnn, @shrutiyam-glitch, @sohanpatil, @tom1299, @tomergee, @vicentefb, @volatilemolotov, @zhzhuang-zju

## New Contributors
* @lauragalbraith made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/763
* @shelwinnn made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/805
* @arpitjain099 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/796
* @patcrombie made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/803
* @rainwoodman made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/711
* @rmalani-nv made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/750
* @shaikenov made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/798
* @tom1299 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/845
* @armistcxy made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/885
* @ianchakeres made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/906
* @hrsh1209 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/753
* @AlexBulankou made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/866
* @ryanzhang-oss made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/839
* @mvanhorn made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/864
* @kannon92 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/947
* @RidPra made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/859
* @sairajp-rewind made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/957
* @HasonoCell made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/857
* @mesutoezdil made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/978
* @inardini made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/950
* @zhzhuang-zju made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/974

**Full Changelog**: https://github.com/kubernetes-sigs/agent-sandbox/compare/v0.4.6...v0.5.0