文档中心

容器服务

VCI Agent Sandbox

生命周期管理

本文主要介绍 VCI Agent Sandbox 中进行创建、暂停、恢复、删除、变更等沙箱生命周期管理操作。

创建沙箱

您可以使用 VCI 资源创建一个沙箱。

说明

一个沙箱是一个 Sandbox Custom Resource。

当前 VCI 容器使用了 Kata Container 实现强隔离。

前提条件

VCI 业务集群中已创建 StorageClass，用于动态创建沙箱数据盘 PVC。详情请参见使用云盘动态存储卷、使用 NAS 动态存储卷、使用 vePFS 动态存储卷。

如需通过 SandboxSnapShotClass 定义沙箱快照的删除/保留策略，请提前创建相关 Custom Resource。示例 YAML 如下所示。详情请参见数据持久化。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxSnapShotClass
metadata:
name: class-for-retain-snapshot # SandboxSnapShotClass 名称。
spec:
deletionPolicy: Retain # 沙箱快照删除/保留策略。取值：Retain（保留） / Delete（删除）。
driver: sandbox.agent.io/vci # 快照后端 Provider。目前仅支持 vci 一种类型 Provider。

已有运行沙箱所需的镜像，并确保沙箱所在集群中的节点可拉取镜像。您也可以上传镜像到镜像仓库（CR）产品中，详情请参见基于 Docker 推送和拉取镜像。

使用已有快照创建沙箱时，可从如下两种途径获取快照 ID：

使用已有沙箱关机时 VCI 自动创建的快照 ID。

用户自行创建的 Snapshot 类型 Custom Resource。

首次创建沙箱

从零开始首次在 VCI Agent Sandbox 环境中创建沙箱时，按如下示例代码创建。

apiVersion: agents.x-k8s.io/v1alpha1​
kind: Sandbox​
metadata:​
  annotations:​
    agent.sandbox.io/snapshot-class: "class-for-retain-snapshot" # 选填，沙箱关联的 SandboxSnapShotClass 名称。此处和 snapshot-deletion-policy 均指定快照删除策略时，以 snapshot-deletion-policy 指定的策略为准。​
    agent.sandbox.io/snapshot-deletion-policy: Delete # 选填，删除沙箱时，是否联动删除快照。未指定时，会使用 SandboxSnapShotClass 的删除策略。取值：Delete（删除）/Retain（保留）。​
    agent.sandbox.io/snapshot-retention-days: "3" # 选填，快照的保留天数，到期自动删除快照。未指定时，会使用 SandboxSnapShotClass 的保留天数。取值范围：正整数，取值类型：String。​
    agent.sandbox.io/snapshot-max-num: "3" # 选填，单个沙箱关联的快照最大数量。取值范围：正整数，取值类型：String。​
  name: test-sandbox-example  # 沙箱名称。​
spec:​
  replicas: 1  # 沙箱当前运行 Pod 副本数，只允许设置 0（无计算资源，即暂停沙箱）或 1（提供 1 个 VCI Pod 计算资源，即沙箱开机）。​
  volumeClaimTemplates:  # 数据盘 PVC 模板。​
    - spec: ​
        accessModes:​
          - ReadWriteMany​
        resources:​
          requests:​
            storage: 20Gi​
        storageClassName: test-storage-class  # StorageClass 名称，用于动态创建沙箱数据盘 PVC。​
        volumeMode: Filesystem​
      metadata:​
        name: generated-name​
  podTemplate:  # 沙箱对应的 VCI Pod 模板。​
    metadata:​
      annotations:​
        vci.volcengine.com/tls-enable: "false" # 是否开启日志采集。取值：true（开启）/false（关闭）。​
        vke.volcengine.com/burst-to-vci: enforce # 强制调度到 VCI。​
        vci.vke.volcengine.com/enable-auto-create-imc: "true"  # 开启自动镜像缓存。​
        vci.volcengine.com/usable-disk-capacity: "40"  # 指定系统盘真实可用空间（可写层空间），单位为 GiB。​
        vci.volcengine.com/persistent-container: "true" # 是否开启容器可写层数据持久化。取值：true（开启）/false（关闭）。​
      labels:​
        app: test-server​
    spec:​
      containers:​
      - image: vke-cn-beijing.cr.volces.com/vke/nginx:latest  # 运行沙箱所需的镜像。​
        imagePullPolicy: IfNotPresent​
        name: test-server​
        resources: { }​
        terminationMessagePath: /dev/termination-log​
        terminationMessagePolicy: File​
      dnsPolicy: ClusterFirst​
      restartPolicy: Always​
      schedulerName: default-scheduler​
      terminationGracePeriodSeconds: 30​

等待 CRD 的status.phase显示为 Running 时，表示沙箱创建成功。示例代码片段如下所示。

status:​
  conditions:​
  - lastTransitionTime: "2025-11-18T02:21:30Z" # 状态切换时间，即 status=False/Unknown 到 status=True 的时间点。​
    message: Pod is Ready; Service Exists​
    observedGeneration: 1​
    reason: DependenciesReady # 表示沙箱依赖的 Pod、Service、PV&PVC 都已经创建完成并就绪。​
    status: "True" # status=True 表示沙箱已就绪；status=False 表示沙箱未就绪。​
    type: Ready​
  replicas: 1 # 沙箱当前运行 Pod 副本数，只允许设置 0（无计算资源，即暂停沙箱）或 1（提供 1 个 VCI Pod 计算资源，即沙箱开机）。​
  phase: Running # 表示沙箱创建成功。​
  selector: agents.x-k8s.io/sandbox-name-hash=e6b82627 # 通过该 label selector 可查询到沙箱对应的 Pod。​
  service: demo-sandbox  # 沙箱关联的 Service 名称。​
  serviceFQDN: ubuntu-sshd.default.svc.cluster.local   # 对应 Service 所在集群内的完整域名。集群内的客户端可以用它直接访问沙箱（例如 ssh、http 等，取决于 Service 端口配置）。​

使用已有快照创建沙箱

VCI Agent Sandbox 环境中使用已有快照创建沙箱时，在首次创建沙箱模块下示例代码的基础上，增加 Annotation：vci.volcengine.com/snapshot-id。完整示例代码如下。

apiVersion: agents.x-k8s.io/v1alpha1​
kind: Sandbox​
metadata:​
  name: test-sandbox-example  # 沙箱名称。​
spec:​
  replicas: 1  # 沙箱当前运行 Pod 副本数，只允许设置 0（无计算资源，即暂停沙箱）或 1（提供 1 个 VCI Pod 计算资源，即沙箱开机）。​
  volumeClaimTemplates:  # 数据盘 PVC 模板。​
    - spec:​
        accessModes:​
          - ReadWriteMany​
        resources:​
          requests:​
            storage: 20Gi​
        storageClassName: test-storage-class  # StorageClass 名称，用于动态创建沙箱数据盘 PVC。​
        volumeMode: Filesystem​
      metadata:​
        name: generated-name​
  podTemplate:  # 沙箱对应的 VCI Pod 模板。​
    metadata:​
      annotations:​
        vci.volcengine.com/tls-enable: "false"​
        vke.volcengine.com/burst-to-vci: enforce # 强制调度到 VCI。​
        vci.vke.volcengine.com/enable-auto-create-imc: "true"  # 开启自动镜像缓存。​
        vci.volcengine.com/usable-disk-capacity: "40"  # 指定系统盘真实可用空间（可写层空间），单位为 GiB。​
        vci.volcengine.com/persistent-container: "true"  # 是否实现容器可写层数据持久化。取值：true（是）/false（否）。​
        vci.volcengine.com/snapshot-id: "snapshot-1" # 已有快照的 ID。该参数默认仅第一次创建沙箱时生效。​
      labels:​
        app: test-server​
    spec:​
      containers:​
      - image: vke-cn-beijing.cr.volces.com/vke/nginx:latest  # 运行沙箱所需的镜像。该镜像必须与 snapshot-id 中指定的已有快照所用镜像保持一致。​
        imagePullPolicy: IfNotPresent​
        name: test-server​
        resources: { }​
        terminationMessagePath: /dev/termination-log​
        terminationMessagePolicy: File​
      dnsPolicy: ClusterFirst​
      restartPolicy: Always​
      schedulerName: default-scheduler​
      terminationGracePeriodSeconds: 30​

暂停沙箱

自动创建快照

通过将沙箱的replicas设置为 0，达到暂停沙箱的目的。默认情况下，暂停沙箱时 VCI Agent Sandbox 将自动生成快照。示例代码片段如下所示。

apiVersion: agents.x-k8s.io/v1alpha1​
kind: Sandbox​
metadata:​
  annotations:​
  name: test-sandbox-example​
spec:​
  replicas: 0 # 设置副本数为 0 时会释放 VCI Pod 资源且停止计费，但元数据会被保留，达到暂停沙箱的目的。​

等待 CRD 的status.phase显示为 Paused 时，表示沙箱暂停成功。示例代码片段如下所示。

status:​
  conditions:​
  - lastTransitionTime: "2026-02-05T06:24:40Z"​
    message: Pod does not exist, replicas is 0; Service Exists​
    observedGeneration: 2​
    reason: DependenciesReady​
    status: "True"​
    type: Ready​
  phase: Paused # 表示沙箱暂停中。​
  replicas: 0 # 副本数为 0，表示 VCI Pod 资源已释放且停止计费，但元数据被保留，沙箱处于暂停状态。​
  service: test-sandbox-example​
  serviceFQDN: test-sandbox-example.default.svc.cluster.local​
  snapShotId: fake-id # 记录关机时的快照 ID，沙箱再次启动时会使用该 ID。​

不创建快照

如果不希望在沙箱暂停时自动创建快照，可以通过配置 Annotation：agent.sandbox.io/auto-create-snapshot: "false"，关闭自动创建快照的功能。

apiVersion: agents.x-k8s.io/v1alpha1​
kind: Sandbox​
metadata:​
  annotations:​
    agent.sandbox.io/auto-create-snapshot: "false"  # 沙箱暂停时是否产生快照。取值：false（不产生快照），true（产生快照）。​
  name: test-sandbox-example​
spec:​
  replicas: 0 # 设置副本数为 0 时会释放 VCI Pod 资源且停止计费，但元数据会被保留，达到暂停沙箱的目的。​

等待 CRD 的status.phase显示为 Paused 时，表示沙箱暂停成功且不会自动产生快照。示例代码片段如下所示。

status:​
  conditions:​
  - lastTransitionTime: "2026-02-05T06:24:40Z"​
    message: Pod does not exist, replicas is 0; Service Exists​
    observedGeneration: 2​
    reason: DependenciesReady​
    status: "True"​
    type: Ready​
  phase: Paused # 表示沙箱暂停中。​
  replicas: 0 # 副本数为 0，表示 VCI Pod 资源已释放且停止计费，但元数据被保留，沙箱处于暂停状态。​
  service: test-sandbox-example​
  serviceFQDN: test-sandbox-example.default.svc.cluster.local​

恢复沙箱

通过将沙箱的replicas设置为 1，达到恢复沙箱的目的。恢复沙箱时使用上一次关机的快照。示例代码片段如下所示。

apiVersion: agents.x-k8s.io/v1alpha1​
kind: Sandbox​
metadata:​
  annotations:​
  name: test-sandbox-example​
spec:​
  podTemplate:​
    spec:​
      containers:​
      - command:​
        - /usr/sbin/sshd​
        - -D​
        image: vke-cn-beijing.cr.volces.com/vke/nginx:latest​
        name: ubuntu-sshd​
        ports:​
        - containerPort: 22​
          protocol: TCP​
        volumeMounts:​
        - mountPath: /usr/share/nginx/html​
          name: nginx-data​
      tolerations:​
      - effect: NoSchedule​
        key: vci.vke.volcengine.com/node-type​
        operator: Exists​
  replicas: 1 # 设置副本数为 1 时会占用 1 个 VCI Pod 资源并开始计费，同时使用最近一次暂停的系统盘快照，达到恢复沙箱的目的。​

恢复沙箱后，确认该 Custom Resource 的status.phase为 Running 时，视为沙箱恢复成功。

更新沙箱

重建更新

更新沙箱的 CPU、内存和 GPU 配置时，需要先暂停沙箱，再更新podTemplate内的resources资源。配置设置完成后，再恢复沙箱。此过程会销毁原来的 Pod 后再重建新的 Pod 来更新沙箱配置。

暂停沙箱，即：将replicas设置为 0，且确认status.phase为 Paused。

更新podTemplate内的resources字段配置。

spec:
replicas: 1 # 沙箱当前运行 Pod 副本数，只允许设置 0（无计算资源，即暂停沙箱）或 1（提供 1 个 VCI Pod 计算资源，即沙箱开机）。
podTemplate:
spec:
containers:
- name: ubuntu-sshd # 设置容器名称。
image: vke-cn-beijing.cr.volces.com/vke/nginx:latest # 配置容器镜像
command: ["/usr/sbin/sshd", "-D"]
ports:
- containerPort: 22
resources: # 设置容器的 CPU、内存、GPU 规格。
requests:
cpu: 2
memory: 4GB
limits:
cpu: 2
memory: 4GB
volumeClaimTemplates:
- metadata:
name: nginx-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
storageClassName: sandbox-nfs # 声明 Volume 模版，用于容器挂载 NAS 盘。

恢复沙箱，将replicas设置为 1，并确认该 Custom Resource 的status.phase为 Running。

原地更新

更新沙箱镜像时，支持在不重建 Pod 的情况下，原地更新，即不销毁原来的 Pod，直接在该 Pod 上更新沙箱镜像，缩短配置变更时间。

在沙箱 YAML 文件中配置 Annotation：vci.volcengine.com/persistent-container: "true"。

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata:
annotations:
agent.sandbox.io/snapshot-class: "class-for-retain-snapshot" # 选填，沙箱关联的 SandboxSnapShotClass 名称。此处和 snapshot-deletion-policy 均指定快照删除策略时，以 snapshot-deletion-policy 指定的策略为准。
agent.sandbox.io/snapshot-deletion-policy: Delete # 选填，删除沙箱时，是否联动删除快照。未指定时，会使用 SandboxSnapShotClass 的删除策略。取值：Delete（删除）/Retain（保留）。
agent.sandbox.io/snapshot-retention-days: "3" # 选填，快照的保留天数，到期自动删除快照。未指定时，会使用 SandboxSnapShotClass 的保留天数。取值范围：正整数，取值类型：String。
agent.sandbox.io/snapshot-max-num: "3" # 选填，单个沙箱关联的快照最大数量。取值范围：正整数，取值类型：String。
agent.sandbox.io/auto-create-snapshot: "false" # 选填，沙箱暂停时是否产生快照。取值：false（不产生快照），true（产生快照）。
name: test-sandbox-example # 沙箱名称。
spec:
replicas: 1 # 沙箱当前运行 Pod 副本数，只允许设置 0（无计算资源，即暂停沙箱）或 1（提供 1 个 VCI Pod 计算资源，即沙箱开机）。
volumeClaimTemplates: # 数据盘 PVC 模板。
- spec:
accessModes:
- ReadWriteMany
resources:
requests:
storage: 20Gi
storageClassName: test-storage-class # StorageClass 名称，用于动态创建沙箱数据盘 PVC。
volumeMode: Filesystem
metadata:
name: generated-name
podTemplate: # 沙箱对应的 VCI Pod 模板。
metadata:
annotations:
vci.volcengine.com/tls-enable: "false" # 是否开启日志采集。取值：true（开启）/false（关闭）。
vke.volcengine.com/burst-to-vci: enforce # 强制调度到 VCI。
vci.vke.volcengine.com/enable-auto-create-imc: "true" # 开启自动镜像缓存。
vci.volcengine.com/usable-disk-capacity: "40" # 指定系统盘真实可用空间（可写层空间），单位为 GiB。
vci.volcengine.com/persistent-container: "true" # 是否开启容器可写层数据持久化。取值：true（开启）/false（关闭）。
vci.volcengine.com/image-restart-policy: "in-place" # 镜像更新策略，in-place 表示在不重建 Pod 的情况下原地更新容器镜像。
labels:
app: test-server
spec:
containers:
- image: vke-cn-beijing.cr.volces.com/vke/nginx:latest # 运行沙箱所需的镜像。
imagePullPolicy: IfNotPresent
name: test-server
resources: { }
terminationMessagePath: /dev/termination-log
terminationMessagePolicy: File
dnsPolicy: ClusterFirst
restartPolicy: Always
schedulerName: default-scheduler
terminationGracePeriodSeconds: 30

后续直接通过 YAML 更新podTemplate中配置的镜像，VCI Agent Sandbox 会原地更新容器镜像。

更新完成后查看该 Custom Resource 的status.phase为 Running 且容器镜像已切换为目标版本时，表示原地更新沙箱已完成。

删除沙箱

如果不需要沙箱，可以直接删除对应的 Sandbox 资源。删除沙箱时，对应的 VCI Pod、Snapshot、Custom Resource 以及 PVC 资源会自动删除。

数据盘数据保存策略由存储类的保存策略决定：

Retain：PVC 释放后，PV 保持在 Released 状态，不自动删除或回收。

Delete：PVC 释放后，自动删除 PV 及其底层存储资源。

如果需要定时删除，可以通过设置shutdownTime来实现。示例代码如下。

spec:​
  podTemplate:​
    spec:​
      containers:​
      - image: vke-cn-beijing.cr.volces.com/vke/nginx:latest​
        name: nginx​
        ports:​
        - containerPort: 80​
          protocol: TCP​
        volumeMounts:​
        - mountPath: /usr/share/nginx/html​
          name: nginx-data​
  replicas: 1  # 沙箱当前运行 Pod 副本数，只允许设置 0（无计算资源，即暂停沙箱）或 1（提供 1 个 VCI Pod 计算资源，即沙箱开机）。​
  shutdownTime: "2024-11-17T20:44:05Z" # 超过这个时间，沙箱对应的 Pod 就会被删除掉，但是 Sandbox 资源会保留。​

最近更新时间：2026.07.15 10:52:47

这个页面对您有帮助吗？

有用

无用