docs(kubernetes): enhance resource pool and task orchestration documentation

Author: fengcone

kubernetes/README-ZH.md

@@ -25,22 +25,29 @@ BatchSandbox 自定义资源允许您创建和管理多个相同的沙箱环境
 
 ### 资源池化
 Pool 自定义资源维护一个预热的计算资源池，以实现快速沙箱供应：
-- 可配置的缓冲区大小（最小和最大）以平衡资源可用性和成本
-- 池容量限制以控制总体资源消耗
-- 基于需求的自动资源分配和释放
-- 实时状态监控，显示总数、已分配和可用资源
+- **可配置的缓冲区大小**：设置最小和最大缓冲区，以确保资源可用性同时控制成本。
+- **池容量限制**：通过池范围的最小和最大限制来控制总体资源消耗。
+- **回收策略 (Recycle Policies)**：支持不同的 Pod 回收策略：
+  - **Delete (默认)**：Pod 在返回池时会被删除并根据模板重新创建，确保环境绝对纯净。
+  - **Restart**：通过向所有容器的 PID 1 发送 SIGTERM 信号优雅终止进程，并依赖 Kubernetes 的 `restartPolicy` 触发重启。这种方式比 `Delete` 更快，但要求 `PodTemplateSpec` 中的 `restartPolicy` 设置为 `Always` 或 `OnFailure`。
+- **自动扩展**：基于当前需求和缓冲区设置进行动态资源分配和释放。
+- **实时状态监控**：显示总数、已分配、可用以及正在重启中的 Pod 数量。
 
 ### 任务编排
 集成的任务管理系统，在沙箱内执行自定义工作负载：
-- **可选执行**：任务调度完全可选 - 可以在不带任务的情况下创建沙箱
-- **基于进程的任务**：支持在沙箱环境中执行基于进程的任务
-- **异构任务分发**：使用 shardTaskPatches 为批处理中的每个沙箱定制单独的任务
+- **可选执行**：任务调度完全可选 - 可以在不带任务的情况下创建沙箱。
+- **基于进程的任务**：支持在沙箱环境中执行基于进程的任务。
+- **异构任务分发**：使用 `shardTaskPatches` 为批处理中的每个沙箱定制单独的任务。
+- **资源释放策略**：通过 `taskResourcePolicyWhenCompleted` 控制任务完成后资源何时返回池：
+  - **Retain (默认)**：保持沙箱资源，直到 `BatchSandbox` 被删除或过期。
+  - **Release**：在任务达到终态（SUCCEEDED 或 FAILED）后，立即自动将沙箱释放回资源池。
 
 ### 高级调度
 智能资源管理功能：
-- 最小和最大缓冲区设置，以确保资源可用性同时控制成本
-- 池范围的容量限制，防止资源耗尽
-- 基于需求的自动扩展
+- **基于需求的自动扩展**：根据实时的沙箱分配请求，自动扩展和收缩资源池中的 Pod 数量。
+- **缓冲区管理**：通过 `bufferMin` 和 `bufferMax` 设置平衡即时可用性与资源开销。
+- **池约束**：使用 `poolMin` 和 `poolMax` 设置资源使用的硬边界。
+- **滚动更新**：当修改 `PodTemplateSpec` 时，自动进行池更新和 Pod 轮转。
 
 ## 运行时 API 支持说明
 
@@ -390,6 +397,7 @@ spec:
     bufferMin: 2
     poolMax: 20
     poolMin: 5
+  podRecyclePolicy: Delete
 ```
 
 应用资源池配置：
@@ -442,6 +450,7 @@ spec:
     bufferMin: 2
     poolMax: 20
     poolMin: 5
+  podRecyclePolicy: Delete
 ```
 
 使用我们刚刚创建的资源池创建一批带有基于进程的异构任务的沙箱：
@@ -454,6 +463,7 @@ metadata:
 spec:
   replicas: 2
   poolRef: task-example-pool
+  taskResourcePolicyWhenCompleted: Release
   taskTemplate:
     spec:
       process:

kubernetes/README.md

@@ -25,22 +25,29 @@ The BatchSandbox custom resource allows you to create and manage multiple identi
 
 ### Resource Pooling
 The Pool custom resource maintains a pool of pre-warmed compute resources to enable rapid sandbox provisioning:
-- Configurable buffer sizes (minimum and maximum) to balance resource availability and cost
-- Pool capacity limits to control overall resource consumption
-- Automatic resource allocation and deallocation based on demand
-- Real-time status monitoring showing total, allocated, and available resources
+- **Configurable Buffer Sizes**: Minimum and maximum buffer settings to ensure resource availability while controlling costs.
+- **Pool Capacity Limits**: Overall resource consumption control with pool-wide minimum and maximum limits.
+- **Recycle Policies**: Support for different pod recycling strategies:
+  - **Delete (Default)**: Pods are deleted and recreated from the template when returned to the pool, ensuring a completely clean environment.
+  - **Restart**: PID 1 in all containers is gracefully terminated (SIGTERM), and the Kubernetes `restartPolicy` triggers a restart. This is faster than `Delete` but requires the `restartPolicy` in `PodTemplateSpec` to be set to `Always` or `OnFailure`.
+- **Automatic Scaling**: Dynamic resource allocation and deallocation based on current demand and buffer settings.
+- **Real-time Status**: Monitoring of total, allocated, available, and restarting pods.
 
 ### Task Orchestration
 Integrated task management system that executes custom workloads within sandboxes:
-- **Optional Execution**: Task scheduling is completely optional - sandboxes can be created without tasks
-- **Process-Based Tasks**: Support for process-based tasks that execute within the sandbox environment
-- **Heterogeneous Task Distribution**: Customize individual tasks for each sandbox in a batch using shardTaskPatches
+- **Optional Execution**: Task scheduling is completely optional - sandboxes can be created without tasks.
+- **Process-Based Tasks**: Support for process-based tasks that execute within the sandbox environment.
+- **Heterogeneous Task Distribution**: Customize individual tasks for each sandbox in a batch using `shardTaskPatches`.
+- **Resource Release Policy**: Control when resources are returned to the pool after task completion via `taskResourcePolicyWhenCompleted`:
+  - **Retain (Default)**: Keeps the sandbox resources until the `BatchSandbox` is deleted or expires.
+  - **Release**: Automatically releases the sandbox back to the pool immediately after the task reaches a terminal state (SUCCEEDED or FAILED).
 
 ### Advanced Scheduling
 Intelligent resource management features:
-- Minimum and maximum buffer settings to ensure resource availability while controlling costs
-- Pool-wide capacity limits to prevent resource exhaustion
-- Automatic scaling based on demand
+- **Demand-based Scaling**: Automatically scales the number of pods in the pool based on real-time sandbox allocation requests.
+- **Buffer Management**: `bufferMin` and `bufferMax` settings to balance instant availability with resource overhead.
+- **Pool Constraints**: `poolMin` and `poolMax` to set hard boundaries on resource usage.
+- **Rolling Updates**: Automatic pool update and pod rotation when the `PodTemplateSpec` is modified.
 
 ## Runtime API Support Notes
 
@@ -389,6 +396,7 @@ spec:
     bufferMin: 2
     poolMax: 20
     poolMin: 5
+  podRecyclePolicy: Delete
 ```
 
 Apply the pool configuration:
@@ -441,6 +449,7 @@ spec:
     bufferMin: 2
     poolMax: 20
     poolMin: 5
+  podRecyclePolicy: Delete
 ```
 
 Create a batch of sandboxes with process-based heterogeneous tasks using the pool we just created:
@@ -453,6 +462,7 @@ metadata:
 spec:
   replicas: 2
   poolRef: task-example-pool
+  taskResourcePolicyWhenCompleted: Release
   taskTemplate:
     spec:
       process:

kubernetes/charts/opensandbox-controller/README.md

@@ -186,6 +186,7 @@ spec:
     bufferMin: 2
     poolMax: 20
     poolMin: 5
+  podRecyclePolicy: Delete
 ```
 
 ### Create a Batch Sandbox

kubernetes/config/samples/sandbox_v1alpha1_batchsandbox-with-task.yaml

@@ -21,6 +21,7 @@ spec:
         - -f
         - /dev/null
   expireTime: "2025-12-03T12:55:41Z"
+  taskResourcePolicyWhenCompleted: Release
   taskTemplate:
     spec:
       process:

kubernetes/config/samples/sandbox_v1alpha1_pool.yaml

@@ -71,3 +71,4 @@ spec:
     bufferMin: 1
     poolMax: 5
     poolMin: 0
+  podRecyclePolicy: Delete