Sandbox CRD field reference-Container Compute Service(ACS)-阿里云帮助中心

Agent Sandbox uses the Sandbox custom resource (CRD) to describe the desired and observed state of a sandbox.

Configuration example

The following example shows a Sandbox that includes an inline Pod template, an injected runtime sidecar, and a custom volume claim template.

Expand to view a Sandbox YAML example

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                            # Whether the sandbox Pod is hibernated
  persistentContents:                      # Content preserved during resume
  - filesystem
  runtimes:                                # Runtime sidecars to inject
  - name: agent-runtime
  shutdownTime: "2027-01-01T00:00:00Z"     # Absolute time to delete the sandbox (RFC3339, UTC)
  volumeClaimTemplates:                    # PVC templates created for this sandbox
  - metadata:
      name: workspace
    spec:
      accessModes:
        - ReadWriteOnce
      storageClassName: alicloud-disk-essd
      resources:
        requests:
          storage: 20Gi
  template:                                # Inline Pod template
    spec:
      containers:
      - name: main
        image: registry.cn-hangzhou.aliyuncs.com/acs/busybox:v1.29.2
        command: ["sleep", "1d"]
        volumeMounts:
        - name: workspace                  # Mount the PVC declared in volumeClaimTemplates
          mountPath: /workspace

Resource information

Item	Description
API group and version (apiVersion)	`agents.kruise.io/v1alpha1`
Resource kind (kind)	`Sandbox`
Plural name (plural)	`sandboxes`
Singular name (singular)	`sandbox`
Short name (shortName)	`sbx`
Storage version (storageVersion)	`v1alpha1`
status subresource	`status` is managed as a separate subresource.

Sandbox

The top-level fields of Sandbox are described below.

Field	Type	Required	Description
apiVersion	String	Yes	API group and version. Set to `agents.kruise.io/v1alpha1`.
kind	String	Yes	Resource kind. Must be `Sandbox`.
metadata	ObjectMeta	No	Standard Kubernetes object metadata, such as `name`, `namespace`, `labels`, and `annotations`.
spec	SandboxSpec	Yes	Desired state of the sandbox. For the field details, see spec.
status	SandboxStatus	No	Observed runtime state of the sandbox, populated by the system. For the field details, see status.

spec

The spec object (SandboxSpec) defines the sandbox desired state.

Field	Type	Required	Description
paused	Boolean	No	Whether to hibernate the sandbox Pod. Default: `false`.
persistentContents	[]String	No	Content preserved when the Pod resumes. Only `filesystem` (file system) is supported.
shutdownTime	String	No	Absolute time at which to delete the sandbox, in RFC3339 format. The sandbox is deleted when this time is reached; if set to a past time, the sandbox is deleted immediately. The time must include a timezone offset (as required by RFC3339). UTC is recommended, for example, 2026-07-01T02:30:00Z.
runtimes	[]RuntimeConfig	No	Runtime sidecar configuration injected into the sandbox. Multiple sidecars can be configured. For the field details, see RuntimeConfig.
pauseTime	String	No	Absolute time at which the sandbox is automatically hibernated, in RFC3339 format. The sandbox is hibernated when this time is reached. The time must include a timezone offset (as required by RFC3339). UTC is recommended, for example, 2026-07-01T02:30:00Z.
template	PodTemplateSpec	No	Inline Pod template that describes the Pod to create.
volumeClaimTemplates	[]PersistentVolumeClaim	No	List of PersistentVolumeClaim (PVC) templates created for this sandbox.

Note

template and volumeClaimTemplates come from the embedded EmbeddedSandboxTemplate structure and are flattened under spec in the YAML.

RuntimeConfig

Field

Type

Required

Description

name

String

Yes

Runtime type name. Valid values:

csi: injects a Container Storage Interface (CSI) mount sidecar.
agent-runtime: injects an agent runtime sidecar.
traffic-proxy: injects a traffic proxy sidecar.

status

The status object (SandboxStatus) reports the sandbox runtime state.

status is automatically populated by the system based on observations and does not need to be configured manually.

Field	Type	Description
observedGeneration	Integer	Latest observed `metadata.generation`.
phase	String	Current phase of the sandbox. For valid values, see SandboxPhase.
message	String	Human-readable status message.
conditions	[]Condition	List of status conditions for the sandbox resource. Each condition is identified by its `type` field. `status` can be `True`, `False`, or `Unknown`. For valid `type` values, see SandboxConditionType.
podInfo	PodInfo	Key information about the underlying Pod. For the field details, see PodInfo.
nodeName	String	Name of the node the sandbox is scheduled to.
sandboxIp	String	IP address assigned to the sandbox.
updateRevision	String	Template-hash calculated from `spec.template`.

PodInfo

Field	Type	Description
annotations	map[string]string	Key annotations of the Pod.
labels	map[string]string	Key labels of the Pod.
nodeName	String	Name of the node the Pod runs on.
podIP	String	IP address of the Pod.
podUID	String	UID of the Pod.

Enumeration values

SandboxPhase

Values of the sandbox phase status.phase have the following meanings.

Value	Description
Pending	The Pod has been accepted by the system, but some containers have not yet started (for example, images are being pulled or a node is being bound).
Running	The Pod is bound to a node and all containers have started. At least one container is running or restarting.
Paused	The sandbox has been signaled to hibernate. The SandboxPaused condition indicates whether hibernation succeeded.
Resuming	The sandbox is resuming. The SandboxResumed condition indicates whether the resume succeeded.
Upgrading	The sandbox is being rebuilt for an upgrade through SandboxUpdateOps. The Upgrading condition indicates whether the upgrade succeeded.
Succeeded	All containers in the Pod have terminated voluntarily with exit code 0, and the system does not restart them.
Failed	All containers in the Pod have terminated, and at least one container terminated with a non-zero exit code or was killed by the system.
Terminating	Cleanup is in progress after the sandbox was deleted.

SandboxConditionType

Values of the status condition status.conditions[].type have the following meanings.

For each condition, Status is True on success and False on failure.

Value	Description
Ready	The sandbox is ready to serve. All associated containers are ready.
SandboxPaused	Result of the sandbox hibernation. On success, all containers are hibernated.
SandboxResumed	Result of the sandbox resume.
InplaceUpdate	In-place update status.
Upgrading	Upgrade workflow status.
RuntimeInitialized	The agent-runtime inside the sandbox has finished initialization (first-time initialization, or re-initialization after resume, rebuild, upgrade, or dynamic mount).

Note

Condition values are the strings listed in the preceding table. Some values do not exactly match the source-code constants (for example, hibernation maps to SandboxPaused and resume maps to SandboxResumed). Use the string values as authoritative.

Valid values for PersistentContents

Valid values for the resume-time preserved content spec.persistentContents:

Value	Description
filesystem	Preserve the file system during resume.

Sandbox labels

Key	Description
`agents.kruise.io/sandbox-claimed`	Whether the sandbox has been claimed by a workload. `true` means claimed; `false` means it is in the warm pool and can be reused.
`agents.kruise.io/sandbox-pool`	Name of the warm pool the sandbox belongs to. SandboxSet uses this label to manage sandboxes in the same pool.
`agents.kruise.io/sandbox-template`	Name of the SandboxTemplate referenced by the sandbox. SandboxUpdateOps uses this label to select target sandboxes.

`kubectl get` output

Running kubectl get sandbox (or kubectl get sbx) displays the following columns by default.

Column	JSONPath	Description
NAME	`.metadata.name`	Sandbox name.
STATUS	`.status.phase`	Current phase of the sandbox.
AGE	`.metadata.creationTimestamp`	Time elapsed since the sandbox was created.
CLAIMED	`.metadata.labels.agents\.kruise\.io/sandbox-claimed`	Whether the sandbox has been claimed by a workload.
SHUTDOWN_TIME	`.spec.shutdownTime`	Absolute time at which to delete the sandbox.
PAUSE_TIME	`.spec.pauseTime`	Absolute time at which the sandbox is automatically hibernated.
MESSAGE	`.status.message`	Status message.