Sandbox CRD字段说明 - 容器计算服务 ACS

Agent Sandbox 基于 Sandbox 自定义资源（CRD）描述沙箱的期望状态与运行状态。本文介绍 Sandbox 资源各字段的含义、类型和取值说明。

配置示例

以下示例展示了一个包含内联 Pod 模板、runtime sidecar注入和自定义存储卷模板的 Sandbox。

展开查看 Sandbox YAML 示例

apiVersion: agents.kruise.io/v1alpha1
kind: Sandbox
metadata:
  name: demo-sandbox
  labels:
    alibabacloud.com/acs: 'true'
    alibabacloud.com/compute-class: agent-sandbox
spec:
  paused: false                            # 是否休眠沙箱 Pod
  persistentContents:                      # 唤醒时保留的内容
  - filesystem
  runtimes:                                # 注入的 runtime sidecar
  - name: agent-runtime
  shutdownTime: "2027-01-01T00:00:00Z"     # 删除沙箱的绝对时间(RFC3339, UTC)
  volumeClaimTemplates:                    # 为该沙箱创建的 PVC 模板列表
  - metadata:
      name: workspace
    spec:
      accessModes:
        - ReadWriteOnce
      storageClassName: alicloud-disk-essd
      resources:
        requests:
          storage: 20Gi
  template:                                # 内联 Pod 模板
    spec:
      containers:
      - name: main
        image: registry.cn-hangzhou.aliyuncs.com/acs/busybox:v1.29.2
        command: ["sleep", "1d"]
        volumeMounts:
        - name: workspace                  # 挂载上面 volumeClaimTemplates 中的 PVC
          mountPath: /workspace

资源信息

项	说明
API 组和版本（apiVersion）	`agents.kruise.io/v1alpha1`
资源类型（kind）	`Sandbox`
资源名（plural）	`sandboxes`
单数名（singular）	`sandbox`
简称（shortName）	`sbx`
存储版本（storageVersion）	`v1alpha1`
status 子资源	是，`status` 作为独立子资源管理。

Sandbox

Sandbox 顶层字段说明如下。

字段	类型	是否必须	说明
apiVersion	String	是	API 组和版本，取值为 `agents.kruise.io/v1alpha1`。
kind	String	是	资源类型，固定取值为 `Sandbox`。
metadata	ObjectMeta	否	标准的 Kubernetes 对象元数据，例如 `name`、`namespace`、`labels`、`annotations`。
spec	SandboxSpec	是	沙箱的期望状态，详细字段请参见下文spec。
status	SandboxStatus	否	沙箱的实际运行状态，由系统观测并写入，详细字段请参见下文status。

spec

沙箱期望状态 spec（SandboxSpec）的字段说明如下。

字段	类型	是否必须	说明
paused	Boolean	否	是否休眠沙箱 Pod。默认值为 `false`。
persistentContents	[]String	否	唤醒（resume）Pod 时需要保留的内容。暂时仅支持`filesystem`（文件系统）。
shutdownTime	String	否	删除沙箱的绝对时间，采用 RFC3339 格式。到达该时间后沙箱被删除；若设置为过去的时间，则立即删除。时间必须携带时区偏移（RFC3339 要求），推荐使用 UTC，例如：2026-07-01T02:30:00Z。
runtimes	[]RuntimeConfig	否	为沙箱注入的 runtime sidecar 配置，可配置多个。详细字段请参见下文 RuntimeConfig。
pauseTime	String	否	自动休眠沙箱的绝对时间，采用 RFC3339 格式。到达该时间后沙箱自动休眠。时间必须携带时区偏移（RFC3339 要求），推荐使用 UTC，例如：2026-07-01T02:30:00Z。
template	PodTemplateSpec	否	内联的 Pod 模板，描述待创建的 Pod。
volumeClaimTemplates	[]PersistentVolumeClaim	否	为该沙箱创建的 PersistentVolumeClaim（PVC）模板列表。

说明

template、volumeClaimTemplates 来自内嵌结构 EmbeddedSandboxTemplate，在 YAML 中平铺到 spec 下。

RuntimeConfig

字段

类型

是否必须

说明

name

String

是

runtime 类型名称。可选值：

csi：注入 CSI 挂载 sidecar。
agent-runtime：注入 agent runtime sidecar。
traffic-proxy：注入流量代理 sidecar。

status

沙箱运行状态 status（SandboxStatus）的字段说明如下。

status 由系统观测后自动写入，用户无需手动配置。

字段	类型	说明
observedGeneration	Integer	已观测到的最新 `metadata.generation`。
phase	String	沙箱当前所处的阶段，取值请参见下文 SandboxPhase。
message	String	人类可读的状态描述信息。
conditions	[]Condition	沙箱资源的状态条件列表。每个条件以 `type` 唯一标识（按 `type` 合并），`status` 取值为 `True`、`False` 或 `Unknown`。`type` 取值请参见下文SandboxConditionType。
podInfo	PodInfo	底层 Pod 的关键信息，详细字段请参见下文 PodInfo。
nodeName	String	沙箱被调度到的节点名称。
sandboxIp	String	分配给沙箱的 IP 地址。
updateRevision	String	根据 `spec.template` 计算出的 template-hash。

PodInfo

字段	类型	说明
annotations	map[string]string	Pod 的关键 annotations。
labels	map[string]string	Pod 的关键 labels。
nodeName	String	Pod 所在的节点名称。
podIP	String	Pod 的 IP 地址。
podUID	String	Pod 的 UID。

枚举值说明

SandboxPhase

沙箱阶段 status.phase 的取值含义如下。

取值	说明
Pending	Pod 已被系统接受，但仍有容器未启动（例如正在拉取镜像或绑定节点）。
Running	Pod 已绑定到节点，所有容器均已启动；至少一个容器正在运行或处于重启过程中。
Paused	沙箱已触发休眠，休眠成功与否需结合 SandboxPaused Condition判断。
Resuming	沙箱正在唤醒，唤醒成功与否需结合SandboxResumed Condition判断。
Upgrading	沙箱正在通过 SandboxUpdateOps 重建升级，升级成功与否需结合Upgrading Condition判断。
Succeeded	Pod 内所有容器均以退出码 0 主动终止，且系统不会再重启这些容器。
Failed	Pod 内所有容器均已终止，且至少一个容器以非 0 退出码终止或被系统终止。
Terminating	沙箱删除后正在执行清理。

SandboxConditionType

状态条件 status.conditions[].type 的取值含义如下。

各 Condition 的 Status 取 True 为成功，False 为失败。

取值	说明
Ready	沙箱已具备正常服务能力，关联容器均已就绪（Ready）。
SandboxPaused	沙箱休眠的执行结果；成功时所有容器均已休眠。
SandboxResumed	沙箱唤醒的执行结果。
InplaceUpdate	原地更新状态。
Upgrading	升级流程状态。
RuntimeInitialized	沙箱内的 agent-runtime 已完成初始化（首次初始化，或在唤醒、重建、升级、动态挂载后重新初始化）。

说明

Condition 的取值为上表中的字符串，部分取值与源码常量名不完全一致（例如休眠对应 SandboxPaused、唤醒对应 SandboxResumed），请以取值字符串为准。

PersistentContents 可选值

唤醒时保留内容 spec.persistentContents 的可选值如下。

取值	说明
filesystem	唤醒时保留文件系统。

Sandbox Label

Key	说明
`agents.kruise.io/sandbox-claimed`	沙箱是否已被业务分配（claim）。`true` 表示已分配，`false` 表示位于预热池中可被复用。
`agents.kruise.io/sandbox-pool`	沙箱所属预热池的名称，SandboxSet 通过该 Label 管理同池沙箱。
`agents.kruise.io/sandbox-template`	沙箱所引用的 SandboxTemplate 名称，SandboxUpdateOps 通过该 Label 选择目标沙箱。

`kubectl get`命令输出

执行 kubectl get sandbox（或 kubectl get sbx）时，默认显示以下列。

列名	JSONPath	说明
NAME	`.metadata.name`	沙箱名称。
STATUS	`.status.phase`	沙箱当前阶段。
AGE	`.metadata.creationTimestamp`	自沙箱创建以来的时长。
CLAIMED	`.metadata.labels.agents\.kruise\.io/sandbox-claimed`	沙箱是否已被业务分配。
SHUTDOWN_TIME	`.spec.shutdownTime`	删除沙箱的绝对时间。
PAUSE_TIME	`.spec.pauseTime`	自动休眠沙箱的绝对时间。
MESSAGE	`.status.message`	状态描述信息。