v0.5.3

# 🚀 Announcing Agent Sandbox v0.5.3!

We're excited to announce the release of Agent Sandbox v0.5.3! This release brings significant advancements in core stability, controller performance, and introduces a robust suite of observability and stress testing tools. Key highlights include improved controller leadership handover, enhanced resource management with informer cache optimizations. We've also made strides in operator deployment readiness and enriched our documentation and examples.

### ⚠️ Breaking Changes / Action Required
*   **Immutable `Sandbox.spec.volumeClaimTemplates` (#858):** The `Sandbox.spec.volumeClaimTemplates` field is now immutable after creation (instead of previously being immutable implicitly). Attempts to add, modify, or remove this field during an update will be rejected by the API server with a validation error. This prevents potential data drift or reconciliation issues. Existing objects and no-op updates are unaffected.

### Key Highlights
#### API & Core Enhancements
*   **`safe-to-evict` Annotation Support (#615):** The `cluster-autoscaler.kubernetes.io/safe-to-evict` annotation is now exempted from restricted-domain validation in `SandboxClaim`'s `spec.additionalPodMetadata`, allowing for more flexible autoscaling behavior for claimed sandboxes.

#### Controller Performance & Stability
*   **Faster Leader Election Handover (#1249):** The controller manager now gracefully releases its leader-election Lease on shutdown, significantly reducing the leaderless window during rolling updates from ~15s (lease expiry) to ~0.7-1.7s. This ensures smoother controller transitions and improved availability.
*   **Optimized Informer Caches (#1253):** Controller performance is improved by stripping `metadata.managedFields` and unnecessary Pod spec fields from informer caches, reducing memory footprint and CPU usage. An opt-in `--cache-label-selectors` flag is introduced for server-side scoping of Pod and Service watches to sandbox-labeled objects.
*   **Reduced Sandbox Status Churn (#1225):** The controller now avoids writing sandbox status updates for nodeName-only changes during initial Pod scheduling, consolidating updates and reducing API server load.
*   **Efficient Warm Pool Adoption (#1245, #1118):** The SandboxClaim controller is optimized to prevent SandboxWarmPool status updates from re-enqueuing every referencing claim. Additionally, warm-pool adoption now finalizes in a single reconcile pass, improving efficiency and reducing no-op reconciles and retry loops.
*   **Increased Concurrent Workers (#1220, #1221):** The default value for `sandbox-concurrent-workers` has been increased from 1 to 100, enabling better parallel processing of Sandbox reconciles.
*   **Accurate Claim Creation Metrics (#1114):** Fixed a bug that caused SandboxClaim creation latency metrics to be re-recorded and skewed after suspend/resume cycles, ensuring more accurate reporting.
*   **Metric Cardinality Reduction (#1073):** The `warmpool_name` label has been removed from `ClaimStartupLatency` and `ClaimControllerStartupLatency` histograms to reduce metric cardinality.
*   **Optimized `NameHash` Function (#1193):** The internal `NameHash` function has been optimized using bit-manipulation, resulting in faster execution and reduced memory allocations.

#### Operator & Deployment Enhancements
*   **OperatorHub Publication Readiness (#363, #1260):** Significant work has been done to prepare the Agent Sandbox for Kubernetes OperatorHub publication. This includes new OLM bundle assets, versioned operator releases, sample CR files, and expanded ClusterServiceVersion (CSV) descriptions.
*   **Configurable Webhook Certificates (#1255):** The `agent-sandbox-controller` now supports configurable webhook certificate filenames (`--webhook-cert-name`, `--webhook-key-name`) and automatically falls back to a single `cert.pem` file if standard names are not found.

#### Documentation & Examples
*   **Comprehensive SDK Documentation (#780):** New, comprehensive Go and Python SDK reference documentation has been added, along with enhanced generation workflows.
*   **SSH-Native Sandbox Example (#1185):** A new `containarium-ssh-sandbox` example demonstrates running Containarium's `agent-box` runtime as a Sandbox via SSH, providing a secure, token-free access method for AI agents.
*   **Mutating Admission Webhook Example (#761):** A complete example and guide for a Mutating Admission Webhook is included, showcasing how to inject nanosecond-precision timestamp annotations for accurate latency measurements.

#### Observability & Performance Tuning
*   **Advanced Stress Testing Features (#1248, #1236):** The stress test harness now includes a `claims-warm-sustained` phase for sustained-rate SandboxClaim arrivals, monotonic client-side latency accounting, and client connection sharding for more accurate and comprehensive performance benchmarks.
*   **Rich Stress Report Dashboards (#1261, #1228, #1227, #1218, #1212, #1202, #1235):** The stress report now features:
    *   A client-side **Metric Explorer** page for interactive analysis of `metrics.jsonl`.
    *   A **Node Resources** page visualizing node-level CPU and iowait.
    *   **Etcd Server-Side Metrics** capturing disk health (WAL fsync, backend commit latency).
    *   A client-side **Watch Event Explorer** for detailed object lifecycle analysis.
    *   Detailed **Sandbox Controller Workqueue Queueing** metrics and charts.
    *   A **System-Wide Rate Limiting** page consolidating client-side throttling and API Priority & Fairness (APF) metrics.
    *   Enhanced **CPU totals on Flame Graphs** for better pprof analysis.
*   **Benchmark Infrastructure Improvements (#1264, #1263, #1233, #1219, #1209, #1211, #1205, #1210, #1194, #1230)**

### 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.3/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.3/sandbox.yaml

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

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

--------
### Contributors
We extend our sincere thanks to all contributors to this release:
@Oneimu, @aditya-shantanu, @app/dependabot, @barney-s, @chw120, @dongjiang1989, @drogovozDP, @esposem, @hsinhoyeh, @igooch, @justinsb, @lunarwhite, @mesutoezdil, @shrutiyam-glitch, @tarujg

### New Contributors
* @hsinhoyeh made their first contribution in https://github.com/kubernetes-sigs/agent-sandbox/pull/1185

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