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):

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.5.3/sandbox-with-extensions.yaml

Selective Install

Install components separately:

# 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

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 #1185

Full Changelog: v0.5.2...v0.5.3