Sandbox CRD欄位說明 - Container Compute Service

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`	狀態原因資訊。