v0.5.2

# 🚀 Announcing Agent Sandbox v0.5.2!

We're excited to announce the release of Agent Sandbox v0.5.2! This release focuses on significant improvements to core stability, lifecycle management, and developer experience, alongside robust enhancements to our testing infrastructure and expanded documentation. Key updates include critical fixes for warm pool adoption and cold restarts, new Sandbox examples for gVisor and Windows environments, and major upgrades to the sandbox router's WebSocket proxying capabilities. We've also streamlined the installation process with a new all-in-one manifest and provided numerous documentation clarity fixes.

### ⚠️ Breaking Changes / Action Required

*   **Python SDK `use_pod_ip` parameter removed (#1033)**: The `use_pod_ip` parameter has been removed from Python clients. In-cluster connections now automatically prefer the sandbox pod IP when available and fall back to in-cluster DNS otherwise. Users who explicitly set this parameter will need to remove it from their code.
*   **Installation Asset Renames (#1012)**: To streamline installation and improve GitOps compatibility, the primary core installation asset `manifest.yaml` has been renamed to `sandbox.yaml`. A new collision-free, all-in-one asset combining core and extensions is now available as `sandbox-with-extensions.yaml`. Users previously referencing `manifest.yaml` or attempting to combine core and extensions for GitOps workflows should update their deployment manifests.

### Key Highlights

#### Core Stability & Lifecycle Management
*   **Warm Pool Adoption Fixes**
    *   **Restore Warm Adoption from Pre-v1beta1 Warm Pools (#1191, #1197)**: Fixed a regression where SandboxClaims failed to warm-adopt sandboxes whose owner references were written by pre-v1beta1 (v0.4.x) pool controllers after an in-place upgrade, causing silent cold-starts. Owner references are now matched by group and kind instead of exact `apiVersion`.
    *   **Fix Warm-Claim Cold Restart on v0.5.0 Upgrade (#1124)**: Resolved an issue causing warm-started sandbox claims to cold-restart due to unretried optimistic lock conflicts or transient lookup errors during controller upgrades.
*   **NetworkPolicy Enforcement**
    *   **Propagate `sandbox-template-ref-hash` Label to Pods (#1067)**: Ensured that the `agents.x-k8s.io/sandbox-template-ref-hash` label is explicitly propagated from the Sandbox CR to the Pod, restoring network isolation for all template-derived Sandboxes previously blocked by the system-label filter.
*   **Warm Pool Enhancements**
    *   **Expanded Warm Pool Staleness Detection (#1102)**: Warm pool staleness detection now tracks `VolumeClaimTemplates` and `Service` configuration alongside `PodTemplate`. Updates to storage or service settings in a `SandboxTemplate` will now correctly trigger warm pool recreation under the `Recreate` update strategy.
    *   **Optimized Sandbox Cache Indexing (#1137)**: Improved warm pool controller efficiency by indexing the sandbox cache by warm pool label, avoiding O(n) list operations in `reconcilePool` for better performance.
*   **Controller Configuration**
    *   **Gate Webhook Implementation (#1186)**: Introduced an `--enable-webhook` flag (default: `true`) allowing operators to explicitly enable or disable the controller-runtime webhook server and registrations, reducing RBAC requirements for deployments not using webhooks.
    *   **Helm Chart Flag Honoring (#942)**: Fixed the Helm chart silently ignoring explicitly-set `false`/`0` controller values (e.g., `--set controller.leaderElect=false`), which previously left leader election enabled. Also added `controller.sandboxWarmPoolMaxBatchSize` and `controller.enableWarmPoolEviction` chart values.

#### Sandbox Router
*   **WebSocket Proxying (#923)**: The sandbox router now proxies WebSocket traffic to sandbox pods, supporting browser UIs like JupyterLab. Includes configurable idle timeout, max lifetime, max message size, and per-client connection limits, with `TRUSTED_PROXY_CIDRS` for security.
*   **Retry Loop Optimization (#1181)**: Replaced `time.After` with a reusable `time.NewTimer` in the retry loop, reducing unnecessary timer allocations and improving retry mechanism efficiency.
*   **Build Fix (#1133)**: Fixed an issue where the `sandbox-router-go` image was incorrectly built from the controller Dockerfile due to build context mismatches in `dev/tools/push-images`.

#### Developer Experience & Examples
*   **Streamlined Installation (#1012)**: Introduced a collision-free all-in-one install asset (`sandbox-with-extensions.yaml`) for seamless integration with kustomize and GitOps engines.
*   **New Sandbox Examples**
    *   **gVisor-isolated OpenClaw Sandbox with PVC Persistence (#1024)**: Added a production-shaped, gVisor-isolated deployment example for OpenClaw using `SandboxTemplate`, `SandboxWarmPool`, and `SandboxClaim`, with persistent storage and NodePort/LoadBalancer access.
    *   **Windows Sandbox Example (#1117)**: Added an example demonstrating how to run a Windows guest via KVM/QEMU within the Agent Sandbox.
    *   **Aider Sandbox Example (#1142)**: Provided a new example for running Aider (AI coding assistant) in an isolated sandbox environment.

#### Python SDK
*   **Track Sandboxes Created via SDK (#1039)**: Sandboxes created programmatically via the Python SDK are now stamped with `agents.x-k8s.io/created-by: python-client` label, with corresponding Prometheus telemetry.
*   **Encode Dot File Paths (#1115)**: Fixed Go SDK file operations for dot paths (e.g., `List(".")`) to prevent server-side path normalization redirects.

#### Documentation Improvements
*   **Consolidated Doc Fixes (#1178)**: Addressed several small documentation issues, including pod count mismatches, JSON patch examples, port-forwarding targets, CRD schema accuracy, and sandbox router paths.
*   **API Versioning Roadmap Clarity (#1163)**: Clarified the Alpha to Beta API Versioning roadmap status, noting the existing `v1beta1` API types across CRDs and the deprecation warning for `v1alpha1`.
*   **Link and Prerequisite Corrections (#1162, #1161, #1173, #1172, #1170, #1168, #1171)**: Fixed broken links, corrected prerequisite descriptions, updated URLs to HTTPS, and removed outdated references across various documentation pages and examples.

#### Performance & Testing Improvements
*   **CNI-Parameterized Benchmarking (#1195)**: Added CNI-parameterized benchmark job scripts under `dev/ci` to enable performance testing with different CNIs (e.g., Cilium, Kindnet).
*   **Cilium Metrics Integration (#1187)**: Enabled Cilium-agent Prometheus metrics on the kOps cluster and added dedicated report pages to analyze CNI performance during stress tests, identifying rate-limiting issues.
*   **Pprof Flame Graphs in Stress Reports (#1184)**: Integrated `pprof` flame graph generation for kube-apiserver CPU profiles directly into stress reports, aiding in bottleneck analysis.
*   **Automated Problem Reporting in Stress Tests (#1180)**: Enhanced stress test reporting with a new HTML report that analyzes data using DuckDB and highlights known performance problems.
*   **Capacity-Aware Stress Testing (#1183)**: Stress tests now fail explicitly when the configured load exceeds spare cluster pod capacity, preventing silently invalid test results.
*   **Comprehensive Prometheus Metrics Collection (#1176)**: Stress runs now collect Prometheus metrics from control-plane components, the sandbox controller, and kubelets into `metrics.jsonl.gz`.
*   **Phase-Based Stress Test Records (#1175, #1159)**: Stress sandbox records are now keyed by a 1-based `PhaseNumber`, and stress tests are split into fill, probe, and throughput phases to measure latency and throughput without conflating capacity queueing.
*   **CI Resilience & Debuggability**
    *   **Retry Cluster Bring-up Steps (#1101)**: Improved CI robustness by retrying transient failures during cluster setup in the presubmit runner.
    *   **Enriched Stress Harness Milestones (#1135)**: Stress harness now records per-stage launch latency, throughput, and per-sandbox timelines for detailed performance analysis.
    *   **Loud Failure on Bad Image Pushes (#1134)**: `dev/tools/push-images` now fails loudly on unknown or duplicate images, preventing silent tag issues.
    *   **Kubeadm Config Fix (#1126)**: Updated `kubeadm extraArgs` to `v1beta4` list format in `create-kind-cluster` to fix Kind cluster creation failures in E2E presubmits.
    *   **Release CI Fix (#1120)**: Fixed a bug causing release CI to fail by making protobuf/gRPC code generation self-bootstrapping.
    *   **Deterministic Skill Evaluation (#1127)**: Added a deterministic skill evaluation suite for the `triage-issues` skill.

#### Dependency Updates
*   **Go Modules and Docker Dependencies (#1147, #1146, #1145)**: Bumped `golang.org/x/net`, `golang.org/x/sync`, and `golang` versions across various `gomod-dependencies` and `docker-dependencies` groups.

### Installation

#### Standard Install (Core + Extensions)
Recommended for most users and GitOps engines (Argo CD, Config Sync, kustomize):
```bash
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.2/sandbox-with-extensions.yaml
```

#### Selective Install
Install components separately:
```bash
# Core only:
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.2/sandbox.yaml

# Extensions (opt-in):
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.2/extensions.yaml
```

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

--------
### Contributors
We extend our sincere thanks to all contributors to this release:
@Leonard013, @LuBingtan, @SHRUTI6991, @aditya-shantanu, @akvnn, @app/dependabot, @dongjiang1989, @esposem, @janetkuo, @lunarwhite, @mj006648, @sairajp-rewind, @tarujg

## New Contributors
* @minhthong582000 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1102
* @tarujg made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1012
* @mj006648 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1033
* @LuBingtan made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1115
* @Leonard013 made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1133
* @akvnn made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/942

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