生命周期与存储

Agent Sandbox 将期望的运行模式、观测到的状态、计划过期时间以及持久化数据模型分离开来。客户端必须将这些内容视为不同的契约。

运行和挂起模式

在核心 Sandbox 上设置 spec.operatingMode：

Running 表示请求一个处于活动状态的 workload。
Suspended 表示请求停止该 workload，同时保留 Sandbox 对象及其声明式配置。

示例补丁：

kubectl patch sandbox python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  --type=merge \
  -p '{"spec":{"operatingMode":"Suspended"}}'

kubectl patch sandbox python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  --type=merge \
  -p '{"spec":{"operatingMode":"Running"}}'

挂起 Sandbox 会终止活动的 workload Pod。将其切换回 Running 会使 controller 再次准备该 workload。

状态条件

将 Sandbox 条件视为带类型的布尔状态记录。不要仅根据条件是否存在来推断状态。

在 v0.5.4 中，Suspended 条件在初始 reconciliation 之后仍然保留：

Suspended=True 表示 Sandbox 处于挂起状态。
Suspended=False 表示它未处于挂起状态。
终止原因 PodTerminating 取代了旧的 PodNotTerminated 原因。

使用以下方式检查条件：

kubectl get sandbox python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  -o jsonpath='{range .status.conditions[*]}{.type}{"="}{.status}{" reason="}{.reason}{"\n"}{end}'

请等待操作所需的特定布尔状态：

kubectl wait --for=condition=Ready=True sandbox/python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  --timeout=180s

kubectl wait --for=condition=Suspended=True sandbox/python-sandbox \
  -n "$BUSINESS_NAMESPACE" \
  --timeout=180s

计划关停

shutdownTime 是一个绝对的 RFC3339 时间戳。例如：

spec:
  shutdownTime: "2026-08-11T12:30:00Z"

它不是相对时长。命令、网络流量、CPU 使用率或 heartbeat 不会自动延长它。

客户端 SDK 可以提供类似“从现在起 30 分钟”的相对助手函数，但该助手最终会向 Kubernetes resource 写入一个固定的绝对 shutdownTime。若要延长生命周期，必须由客户端或其他被授权组件显式更新。

关停策略

对于核心 Sandbox，shutdownPolicy 支持以下值：

策略	过期后的 Sandbox 对象	过期后的 Pod 和 Service
`Delete`	已删除	已删除
`Retain`	保留，带有过期状态	已删除

默认策略是 Retain。即使 Sandbox 对象被保留，底层 workload 资源也会在过期时被删除。

SandboxClaim 有其自己的扩展生命周期策略：Delete、DeleteForeground 和 Retain。DeleteForeground 会将 claim 保持在 terminating 状态，直到底层 Sandbox 和 Pod 都已终止，从而允许外部系统观察关停进度。

持久数据

当 Sandbox 需要 Kubernetes 管理的持久化存储时，请使用 spec.volumeClaimTemplates。controller 会根据这些模板创建 PersistentVolumeClaims。

持久化存储会保留写入挂载卷的数据。它不会保留：

仅安装在容器可写层中的 package。
挂载卷之外的操作系统更改。
内存中的进程状态。
整个可执行环境快照。

请将可重复的环境构建到受信任的 image 中，并将业务数据存储到合适的 persistent volume 或外部服务中。

不可变的 Volume Claim Templates

Sandbox.spec.volumeClaimTemplates 在创建后即不可变。API 会拒绝添加、删除或修改模板的更新。

当模板必须更改时：

准备替代存储和 Sandbox 定义。
停止应用写入，或使用应用特定的一致性机制。
通过存储系统支持的工作流迁移或恢复数据。
创建一个替代 Sandbox。
在删除原始 resource 之前验证替代对象。

controller 回滚并不会使原地模板更新变为有效。

空闲关停边界

此版本不提供原生的空闲关停。Agent Sandbox 不会根据 API 请求、shell 活动、网络流量、CPU、I/O 或 heartbeat 推断空闲状态。

不要将 shutdownTime 描述为空闲关停。一个产品化的空闲机制需要可信的活动信号，以及一个有授权的组件来有意续期或使 Sandbox 生命周期过期。

#生命周期与存储

#目录

#运行和挂起模式

#状态条件

#计划关停

#关停策略

#持久数据

#不可变的 Volume Claim Templates

#空闲关停边界