VCI Agent Sandbox 的预热池能力，通过预创建 + 就绪缓存的方式，消除冷启动延迟，实现秒级申领交付。本文主要介绍预热池能力及其工作流程。

功能介绍

预热池（SandboxWarmPool）是 VCI Agent Sandbox 的核心扩展能力。在无预热池的情况下，每次创建沙箱都需要经历调度、镜像拉取、容器启动、健康检查等完整流程，耗时可达数十秒。预热池通过提前完成这些步骤，将就绪的 Pod 放入缓存池中，当业务申领沙箱时直接从池中分配，实现亚秒级交付。

功能优势

痛点场景	无预热池	预热池方案
冷启动延迟	单 Pod 启动约数十秒，叠加镜像拉取，交互中断。	预创建就绪 Pod，申领直接交付，延迟降至亚秒级。
资源浪费	空闲沙箱长期占用，资源闲置。	闲置超时自动回收，按需补充，资源利用率提升 50% 以上。
并发峰值响应	大规模并发时创建滞后，排队等待。	弹性扩缩容匹配负载，峰值无感知扩容。
多租户安全隔离	共享环境易泄漏，权限管控难。	基于 Kata 强隔离，单沙箱独立环境。

核心 CRD 资源

预热池依赖 4 个核心 CRD 协同工作：

CRD 资源	作用	关键能力
SandboxTemplate	定义沙箱配置模板，包含镜像、资源规格、安全策略等。	配置复用、统一规范、版本管理。
SandboxWarmPool	预热池管理，负责预创建和维护就绪 Pod 池。	预创建就绪 Pod、自动补全、弹性扩缩、闲置回收。
SandboxClaim	沙箱申领请求，业务侧通过该 CRD 获取沙箱实例。	从池或模板申请沙箱、动态覆盖配置、超时控制。
Sandbox	沙箱实例，代表实际运行的 Pod。	生命周期管理、状态上报、隔离环境。

使用限制

预热池能力与系统盘状态持久化（Snapshot）能力暂时不支持同时使用。预热池管理的是一组状态完全相同的就绪沙箱实例，而系统盘快照则用于保存单个沙箱的独立运行状态。如需使用系统盘快照恢复能力，请参见生命周期管理中的快照相关说明。

前提条件

使用预热池方案进行 VCI Agent Sandbox 启动加速前，请确保满足如下前提条件：

已安装 VCI Agent Sandbox，详情请参见安装指南。

已准备好沙箱使用的容器镜像，并已推送至可访问的镜像仓库。您可以推送镜像至 CR 产品，操作详情请参见推送和拉取镜像。

操作步骤

步骤一：创建 SandboxTemplate

SandboxTemplate 定义了沙箱的基础配置，包括运行环境、资源限制、安全上下文等，是预热池创建 Pod 的模板。

创建 SandboxTemplate，示例 YAML 文件sandbox-template.yaml内容如下：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
name: code-interpreter-template # 沙箱模板名称。
namespace: default # 沙箱模板所属命名空间。
spec:
podTemplate: # 沙箱 Pod 的配置模板，语法与标准 Kubernetes PodSpec 一致。
metadata:
annotations:
agent.sandbox.io/snapshot-max-num: "2" # 单个沙箱关联的快照最大数量。取值范围：正整数，取值类型：String。
vci.vke.volcengine.com/enable-auto-create-imc: "true" # 是否开启自动镜像缓存，加速镜像拉取。取值：false（不开启）、true（开启）。
vci.vke.volcengine.com/preferred-instance-family: vci.u1,vci.n3i # 指定 VCI 规格族。
vci.volcengine.com/persistent-container: "true" # 是否持久化可写层数据。取值：false（否）、true（是）。
vci.volcengine.com/tls-enable: "false" # 是否将 VCI 容器日志采集至日志服务，取值：false（不开启日志采集）、true（开启日志采集）。
vci.volcengine.com/usable-disk-capacity: "40" # 指定系统盘可写层空间大小（单位：GiB）。
vke.volcengine.com/burst-to-vci: enforce # 强制调度到 VCI。
spec:
containers:
- name: sandbox
image: vke-cn-beijing.cr.volces.com/vke/nginx:latest # 容器镜像的地址和版本，请配置为您自己的镜像地址。若使用公网镜像，请确保您的集群能够访问公网。
resources:
limits:
cpu: "2"
memory: "4Gi"
env: # 环境变量配置，建议保持默认配置。
- name: SANDBOX_TIMEOUT # Sandbox 生命周期超时时间 Key。
value: "3600" # Sandbox 生命周期超时时间 Value，单位为秒。
- name: MAX_EXECUTION_TIME # 创建沙箱模板的最大执行耗时时间 Key。
value: "600" # 创建沙箱模板的最大执行耗时时间 Value，单位为秒。
volumeMounts: # 挂载卷配置，建议保持默认配置。
- name: workspace
mountPath: /workspace
volumes: # 挂载卷配置，建议保持默认配置。
- name: workspace
emptyDir: {}

执行以下命令创建 SandboxTemplate。

kubectl apply -f sandbox-template.yaml

步骤二：创建 SandboxWarmPool

SandboxWarmPool 定义预热池的规模，控制器会根据配置预创建指定数量的就绪 Pod。

创建 SandboxWarmPool，示例 YAML 文件sandbox-warmpool.yaml内容如下：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
name: sandbox-warm-pool # 预热池名称。
namespace: default # 预热池所属命名空间。
spec:
sandboxTemplateRef:
name: code-interpreter-template # 关联的 SandboxTemplate 名称，预热池将按此模板创建 Pod。
replicas: 200 # 预热池中维持的就绪 Pod 数量。请根据业务并发量合理设置，数量过大会导致资源浪费。

执行以下命令创建 SandboxWarmPool。

kubectl apply -f sandbox-warmpool.yaml

步骤三：创建 SandboxClaim

业务需要沙箱时，通过 SandboxClaim 申请沙箱。优先从预热池获取就绪 Pod 并立即绑定交付。

创建 SandboxClaim，示例 YAML 文件sandbox-claim.yaml内容如下：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
name: sandbox-claim # SandboxClaim 名称。
namespace: default # SandboxClaim 所属命名空间。
spec:
sandboxTemplateRef:
name: code-interpreter-template # 申领沙箱所使用的模板名称。控制器会优先从关联该模板的预热池中分配就绪 Pod；若池中无可用 Pod，则按模板配置新建 Pod。

执行以下命令创建 SandboxClaim。

kubectl apply -f sandbox-claim.yaml

验证结果

创建 SandboxClaim 后，执行以下命令查看沙箱申领状态。

kubectl get sandboxclaim sandbox-claim -o yaml

当 SandboxClaim 的status.phase为 Bound 时，表示已成功从预热池获取沙箱实例。可通过status.sandboxRef查看绑定的沙箱名称。

status:
phase: Bound
sandboxRef:
name: sandbox-warm-pool-xxxxx

执行以下命令查看预热池状态，确认池中实例数量符合预期。

kubectl get sandboxwarmpool sandbox-warm-pool -o yaml

预期返回结果如下：

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
name: sandbox-warm-pool
namespace: default
uid: 8f3c9d2a-1b4e-4c7a-******
creationTimestamp: "2026-07-14T06:30:00Z"
generation: 1
spec:
replicas: 5 # 预热池中期望预热的沙箱实例数量。
template:
spec:
image: sandbox-runtime:v1.2.0
resources:
requests:
cpu: "500m"
memory: 1Gi
limits:
cpu: "1"
memory: 2Gi
status:
phase: Ready # 预热池整体状态，Ready 表示池已就绪。
replicas: 5 # 池中实例总数。
availableReplicas: 5 # 已就绪、可被申领的实例数。
boundReplicas: 1 # 已被 SandboxClaim 绑定占用的实例数。
idleReplicas: 4 # 空闲可用的实例数。
conditions:
- type: Ready
status: "True"
reason: PoolReady
message: "Warm pool has reached desired replicas"
lastTransitionTime: "2026-07-14T06:31:20Z"

容器服务