本文介绍如何在 VCI Agent Sandbox 场景下，使用存储卷挂载能力，实现 Sandbox 在预热池实例中动态挂载（Dynamic）存储卷，满足不同业务、不同租户对差异化存储的需求。

功能说明

动态挂载模式无需在模板中预置 Volume，SandboxClaim 认领沙箱实例时指定容器内挂载目录（mountPath），并支持追加新的 Volume 与 volumeMount，由 VCI 以 Hidecar（影子容器）方式注入 CSI 挂载组件保障安全。适用于挂载目录在运行沙箱实例时才能确定、或已有 Annotation 含 mountPath 需低成本平移的场景。当前仅支持 TOS 类型的存储卷。

动态挂载能力通过在 SandboxTemplate 与 SandboxClaim 上添加 Annotation 声明来开启和配置。核心 Annotation 说明如下所示。

对象	Annotation Key	Annotation Value 示例值	说明
SandboxTemplate（podTemplate）	vke.volcengine.com/csi-sidecar-inject	false	是否开启动态挂载能力，取值： true：开启动态挂载并注入 Hidecar。 false：（默认值）不开启。
SandboxClaim	vke.volcengine.com/dynamic-volume-mount-config	[{"volumeName":"data-vol","pvName":"pv-tos-shared","mountPath":"/mnt/data","subPath":"/tenant-a"}]	声明每个 Pod 要新增的 volumeMount 信息。取值格式：JSON 数组。数组支持的字段说明如下： volumeName：目标卷名称。留空时系统自动使用 pvName 作为 volumeName。 pvName：卷对应的 PV 名称。 mountPath：容器内挂载目录，可以是容器内任意绝对路径。包含该字段即进入动态挂载模式。 subPath：PV 根目录下的子路径，用于多租户目录隔离。必须为相对 PV 根目录的合法子路径，禁止包含..。

使用限制

使用动态挂载能力时，请注意以下限制。

限制项	说明
模板注解强依赖	要求 SandboxTemplate 必须带有vke.volcengine.com/csi-sidecar-inject: "true" Annotation，缺失时所有带 mountPath 的请求将被拒绝。
单主容器限制	动态挂载模式默认按单个业务主容器处理，会优先选中第一个name不带sidecar关键字的容器。多容器场景（不推荐）如需使用动态挂载，非主容器的name必须包含sidecar关键字，否则将默认选中第一个容器。
不支持原地重启	动态挂载模式与容器原地更新（in-place update）、可写层持久化能力不可同时使用。容器重启后挂载点可能丢失，需重新创建 Sandbox。
认领限制	预热池中的 Sandbox 只会被认领一次。动态挂载失败、超时或异常时，该 Sandbox 实例将被直接清理并走冷启动链路，不会返回预热池复用，以避免数据处于中间态。
超时约束	动态挂载操作超时时间为 30 秒，超时后认领失败并清理 Sandbox 实例。
存储类型限制	动态挂载模式仅支持 TOS 存储类型。
subPath 安全校验	subPath 禁止包含..路径进行遍历，必须为相对 PV 根目录的合法子目录。
安全责任与风险	使用动态挂载能力相关安全责任和风险说明，请参见存储卷挂载概述。

前提条件

已创建 VCI 业务所需的集群。详细操作，请参见在 VPC-CNI 网络模型集群中使用 VCI、在 Flannel 网络模型集群中使用 VCI。

VCI 业务集群中已安装 VCI Agent Sandbox 对应的组件：agent-sandbox，用于支持 SandboxTemplate / SandboxWarmPool / SandboxClaim 等 CRD。详细操作，请参见安装指南。

已创建 TOS 存储桶（Bucket）。详细操作，请参见创建存储桶。

已在本地安装 kubectl 工具，并通过 kubectl 连接目标集群。详细说明，请参见使用 kubectl 连接集群。

操作步骤

步骤一：创建 SandboxTemplate

创建 SandboxTemplate，并在 podTemplate 的 Annotations 中声明vke.volcengine.com/csi-sidecar-inject: "true"，开启动态挂载模式。示例 SandboxTemplate YAML 文件dynamic-mount-template.yaml内容如下所示。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
name: dynamic-mount-template # SandboxTemplate 名称。
namespace: default # SandboxTemplate 所属命名空间。
spec:
podTemplate:
metadata:
annotations:
vke.volcengine.com/csi-sidecar-inject: "true" # 是否开启动态挂载（Hidecar 注入）。取值：true（开启）、false（不开启）。
vke.volcengine.com/burst-to-vci: enforce # 强制调度到 VCI。
spec:
containers:
- name: app
image: doc-cn-beijing.cr.volces.com/vke/nginx-demo:v1.0 # 容器镜像的地址和版本，请配置为您自己的镜像地址。若使用公网镜像，请确保您的集群能够访问公网。
command: ["/bin/sh", "-c", "sleep 36000"]
resources:
limits:
cpu: "2"
memory: 4Gi

执行以下命令，创建 SandboxTemplate。

kubectl create -f dynamic-mount-template.yaml

步骤二：创建 SandboxWarmPool

预热池将基于模板预热一批处于 Running 状态的 Sandbox，使认领请求直接命中预热实例。动态挂载所需的 Hidecar 与 Init 容器也在此阶段完成注入。

创建 SandboxWarmPool，示例 YAML 文件dynamic-mount-warmpool.yaml内容如下所示。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
name: dynamic-mount-warmpool # 预热池名称。
namespace: default # 预热池所属命名空间。
spec:
replicas: 10 # 预热池 Sandbox 数量。数值越大预热实例越多、认领命中率越高，但资源占用也越高，建议按业务并发峰值评估。
sandboxTemplateRef:
name: dynamic-mount-template # 关联的 SandboxTemplate 名称。
updateStrategy:
type: Recreate

执行以下命令创建 SandboxWarmPool。

kubectl apply -f dynamic-mount-warmpool.yaml

步骤三：创建保密字典（Secret）

通过 Secret 管理访问 TOS 的凭证。

创建 Secret 的 YAML 文件。示例文件vke-tos-secret.yaml代码如下。

apiVersion: v1
kind: Secret
metadata:
name: tos-key # 保密字典名称。
namespace: default # 保密字典所属命名空间。
type: Opaque # 保密字典类型，本例中选择通用类型，存储任意键值对。
data:
akId: ****** # Base 64 编码后的账号 AK，需要替换为真实信息。
akSecret: ****** # Base 64 编码后的账号 SK，与上述 AK 匹配，需要替换为真实信息。

执行以下命令，创建 Secret。

kubectl create -f vke-tos-secret.yaml

步骤四：创建 TOS 存储 PV

准备动态挂载的目标 PV，目前动态挂载模式仅支持 TOS 存储类型。

创建 PV 的 YAML 文件。示例 YAML 文件pv-tos-shared.yaml内容如下所示。

apiVersion: v1
kind: PersistentVolume
metadata:
name: pv-tos-shared # PV 名称。
spec:
csi:
driver: tos.csi.volcengine.com # CSI 驱动类型，本场景必须设置为 tos.csi.volcengine.com，表示使用 csi-tos 插件。
nodePublishSecretRef:
name: tos-key # 已创建的 TOS 访问配置相关 Secret 名称。
namespace: default # Secret 所在命名空间。
nodeStageSecretRef: # 用于引用一个 Kubernetes Secret，将其中的鉴权信息传给 csi-tos 的节点插件（Node Plugin）。
name: tos-key # 已创建的 TOS 访问配置相关 Secret 名称。
namespace: default # Secret 所在命名空间。
volumeAttributes:
bucket: vke-tos # 已创建的 TOS 存储桶名称。
path: /
url: https://tos-s3-cn-beijing.ivolces.com # TOS 存储桶域名。
volumeHandle: pv-tos-shared # PV 的唯一标识符，与 PV 名称保持一致。volumeHandle 应该唯一对应 <url>:<bucket><path>，避免相同 volumeHandle 对应不同 <url>:<bucket><path>，否则可能导致错误挂载盘。

执行以下命令，创建 PV。

kubectl create -f pv-tos-shared.yaml

步骤五：创建 Sandbox

本文提供如下两种创建 Sandbox 方式。

通过 SandboxClaim 认领

通过 E2B SDK 创建

通过创建 SandboxClaim 并指定 mountPath 的方式，发起认领 Sandbox 并声明动态挂载配置。Annotation 中包含mountPath字段即进入动态挂载模式，控制器通过 Hidecar 通道执行 CSI 挂载，将指定 PV 的子目录挂载到容器内的任意绝对路径。

创建 SandboxClaim。示例 YAML 文件dynamic-mount-claim.yaml内容如下所示。

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
name: dynamic-mount-claim # SandboxClaim 名称。
namespace: default # SandboxClaim 所属命名空间。
annotations:
vke.volcengine.com/dynamic-volume-mount-config: '[{"volumeName":"data-vol","pvName":"pv-tos-shared","mountPath":"/mnt/data","subPath":"/tenant-a"}]' # 声明每个 Pod 要新增的 Volume Mount 信息。
spec:
sandboxTemplateRef:
name: dynamic-mount-template # 申领沙箱所使用的 SandboxTemplate 名称。

执行以下命令，创建 SandboxClaim。

kubectl create -f dynamic-mount-claim.yaml

验证结果

确认存储卷已按预期挂载到容器指定目录，并可正常读写。

确认/mnt/data为独立挂载点。

kubectl exec dynamic-mount-claim -c app -n default -- df -h /mnt/data

预期返回结果如下，Mounted on 列为/mnt/data，Filesystem 为 TOS 挂载，说明 TOS 已挂载到目标目录。

Filesystem Size Used Avail Use% Mounted on
tosfs 10T 0 10T 0% /mnt/data

kubectl exec dynamic-mount-claim -c app -n default -- ls -la /mnt/data

预期返回结果如下，列出 TOS Bucket 中tenant-a子目录下的文件与目录。

total 4
drwxr-xr-x 2 root root 0 Sep 15 16:20 .
drwxr-xr-x 3 root root 0 Sep 15 16:20 ..
-rw-r--r-- 1 root root 26 Sep 15 16:20 hello-from-tos.txt

容器服务